Class

MTLRenderPipelineDescriptor

An argument of options you pass to a device to get a render pipeline state object.

Declaration

@interface MTLRenderPipelineDescriptor : NSObject

Overview

The MTLRenderPipelineDescriptor object specifies the rendering configuration state used during a rendering pass, including rasterization (such as multisampling), visibility, blending, tessellation, and graphics function state. Use standard allocation and initialization techniques to create a MTLRenderPipelineDescriptor object. A MTLRenderPipelineDescriptor object is later used to create a MTLRenderPipelineState object.

To specify the vertex or fragment function in the rendering pipeline descriptor, set the vertexFunction or fragmentFunction property, respectively, to the desired MTLFunction object. Note that the properties in the Specifying Tessellation State section are ignored if the vertexFunction property is not set to a post-tessellation vertex function. A vertex function is a post-tessellation vertex function if the [[ patch(patch-type, N) ]] attribute precedes the function’s signature in your Metal shading language source.

The properties in the Specifying Tessellation State section are only used if the vertexFunction property is set to a post-tessellation vertex function. A post-tessellation vertex function is a vertex function declared with the [[ patch(patch-type, N) ]] attribute in your Metal shading language source. Refer to the Post-Tessellation Vertex Function section of the Metal Shading Language Guide for more information.

Setting the fragmentFunction property to nil disables the rasterization of pixels into the color attachment. This action is typically used for outputting vertex function data into a buffer object or for depth-only rendering.

If the vertex shader has an argument with per-vertex input attributes, set the vertexDescriptor property to a MTLVertexDescriptor object that describes the organization of that vertex data.

Multisampling and the Render Pipeline

If a color attachment supports multisampling (in effect, the attachment is a MTLTextureType2DMultisample type color texture), you can create multiple samples per fragment, and the following rendering pipeline descriptor properties determine coverage:

  • sampleCount is the number of samples for each pixel.

  • If alphaToCoverageEnabled is set to YES, then the alpha channel fragment output for colorAttachments is used to compute a coverage mask that affects the values being written to all attachments (color, depth, and stencil).

  • If alphaToOneEnabled is set to YES, then alpha channel fragment values for colorAttachments are forced to 1.0, which is the largest representable value.

If alphaToCoverageEnabled is set to YES, an implementation-defined coverageToMask function uses the alpha channel fragment output from colorAttachments to create an intermediate coverage mask, which sets a number of bits in its output proportionally to the value of the floating point input. For example, if the input is 0.0f, the function sets the output to 0x0. If the input is 1.0f, all output bits are set (in effect, ~0x0). If the input is 0.5f, the function sets half of the bits, as defined by the implementation (which often uses dither patterns).

To determine a final coverage mask, a logical AND is performed on the resulting coverage mask alphaCoverageMask with the masks from the rasterizer and fragment shader, as shown in Listing 1.

Listing 1

Pseudo-code for computing a coverage mask

if (alphaToCoverageEnabled) then
    alphaCoverageMask = coverageToMask(colorAttachment0.alpha);
finalCoverageMask = originalRasterizerCoverageMask
                  & alphaCoverageMask & fragShaderSampleMaskOutput;

Topics

Specifying Graphics Functions and Associated Data

vertexFunction

A programmable function that processes individual vertices in a rendering pass.

fragmentFunction

A programmable function that processes individual fragments in a rendering pass.

vertexDescriptor

The organization of vertex data in an attribute’s argument table.

vertexBuffers

An array that contains the buffer mutability options for a render pipeline's vertex function.

fragmentBuffers

An array that contains the buffer mutability options for a render pipeline's fragment function.

Specifying Rendering Pipeline State

reset

Specifies the default rendering pipeline state values for the descriptor.

colorAttachments

An array of attachments that store color data.

depthAttachmentPixelFormat

The pixel format of the attachment that stores depth data.

stencilAttachmentPixelFormat

The pixel format of the attachment that stores stencil data.

Specifying Rasterization and Visibility State

sampleCount

The number of samples in each fragment.

alphaToCoverageEnabled

Indicates whether the alpha channel fragment output for colorAttachments is read and used to compute a sample coverage mask.

alphaToOneEnabled

Indicates whether the alpha channel values for colorAttachments are forced to 1.0, which is the largest representable value.

rasterizationEnabled

Determines whether primitives are rasterized.

inputPrimitiveTopology

Indicates the type of primitive topology being rendered.

rasterSampleCount

The number of samples in each fragment.

Specifying Tessellation State

maxTessellationFactor

Specifies the maximum tessellation factor to be used by the tessellator when tessellating a patch (or patches).

tessellationFactorScaleEnabled

Determines whether the tessellation factor is scaled.

tessellationFactorFormat

The format of the tessellation factors specified in the tessellation factor buffer.

tessellationControlPointIndexType

The size of the control point indices in a control point index buffer.

tessellationFactorStepFunction

The step function used to determine the tessellation factors for a patch from the tessellation factor buffer.

tessellationOutputWindingOrder

The winding order of triangles output by the tessellator.

tessellationPartitionMode

The partitioning mode used by the tessellator to derive the number and spacing of segments used to subdivide a corresponding edge.

Identifying Properties

label

A string that identifies this object.

Indirect Command Buffers

supportIndirectCommandBuffers

A Boolean value that determines whether the render pipeline state can be used in an indirect command buffer.

Constants

MTLPrimitiveTopologyClass

The primitive topologies available for rendering.

MTLTessellationFactorFormat

The format of the tessellation factors in a tessellation factor buffer.

MTLTessellationControlPointIndexType

The size of the control point indices in a control point index buffer.

MTLTessellationFactorStepFunction

The step function used to determine the tessellation factors for a patch from the tessellation factor buffer.

MTLTessellationPartitionMode

The partitioning mode used by the tessellator to derive the number and spacing of segments used to subdivide a corresponding edge.

Relationships

Inherits From

Conforms To

See Also

State & Descriptor

MTLRenderPipelineState

An object that contains the graphics functions and configuration state used in a render pass.