MTLRenderPipelineDescriptor

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

Declaration

class MTLRenderPipelineDescriptor

Mentioned in

Overview

An MTLRenderPipelineDescriptor instance configures the state of the pipeline to use during a rendering pass, including rasterization (such as multisampling), visibility, blending, tessellation, and graphics function state. Use standard allocation and initialization techniques to create an MTLRenderPipelineDescriptor object. Then configure and use the descriptor to create an 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. The system ignores the tessellation stage properties if you don’t set the vertexFunction property 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. See the “Post-Tessellation Vertex Functions” section of Metal Shading Language Specification for more information.

Setting the fragmentFunction property to nil disables the rasterization of pixels into the color attachment. This action is typically 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 an MTLVertexDescriptor object that describes the organization of that vertex data.

Multisampling and the render pipeline

If a color attachment supports multisampling (essentially, the attachment is an MTLTextureType.type2DMultisample type color texture), you can create multiple samples per fragment, and the following rendering pipeline descriptor properties determine coverage:

rasterSampleCount is the number of samples for each pixel.
If isAlphaToCoverageEnabled is true, the GPU uses the alpha channel fragment output for colorAttachments to compute a coverage mask that affects the values the GPU writes to all attachments (color, depth, and stencil).
If isAlphaToOneEnabled is true, the GPU changes alpha channel fragment values for colorAttachments to 1.0, which is the largest representable value.

If isAlphaToCoverageEnabled is true, 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, the function sets all output bits (in effect, ~0x0). If the input is 0.5f, the function sets half of the bits, according to the implementation, which often uses dither patterns.

To determine a final coverage mask, the function performs a logical AND on the resulting coverage mask alphaCoverageMask with the masks from the rasterizer and fragment shader, as the following code shows:

if (alphaToCoverageEnabled) then
    alphaCoverageMask = coverageToMask(colorAttachment0.alpha);

finalCoverageMask = originalRasterizerCoverageMask
                    & alphaCoverageMask
                    & fragShaderSampleMaskOutput;

Topics

Identifying the render pipeline state object

label

Specifying graphics functions and associated data

Specifying buffer layouts and fetch behavior

vertexDescriptor

Specifying buffer mutability

Specifying rendering pipeline state

Specifying rasterization and visibility state

Specifying tessellation state

Specifying indirect command buffers usage

supportIndirectCommandBuffers

Specifying the maximum vertex amplification count

maxVertexAmplificationCount

Specifying precompiled shader binaries

Specifying callable functions for the pipeline

Specifying shader validation

shaderValidation