Class

MTLRenderPassAttachmentDescriptor

A render target that serves as the output destination for pixels generated by a render pass.

Declaration

@interface MTLRenderPassAttachmentDescriptor : NSObject

Overview

A MTLRenderPassAttachmentDescriptor object is used to configure an individual render target of a framebuffer. Each MTLRenderPassAttachmentDescriptor object specifies one texture that a graphics rendering pass can write into.

Typically, you do not directly create MTLRenderPassAttachmentDescriptor objects. Instead, when you initialize a MTLRenderPassDescriptor object, a default set of attachment objects is created automatically. For each attachment that you intend to use as a render target, you retrieve the MTLRenderPassAttachmentDescriptor object from the render pass descriptor and configure its properties for how it is used during this rendering pass.

You must set the attachment’s texture property, choosing an appropriate pixel format. The level, slice, and depthPlane properties specify the mipmap level, slice, and depth plane (for 3D textures) of the texture, respectively.

The loadAction and storeAction properties specify actions that are performed at the start or end of a rendering pass, respectively, for the attachment. For example, if the loadAction property of an attachment is set to MTLRenderPassAttachmentDescriptor, then at the start of a rendering pass, the contents of the texture are filled with a value that is appropriate for the type of attachment.

There are specific MTLRenderPassAttachmentDescriptor subclasses for color, depth, and stencil attachments. Each subclass provides additional properties to configure for that kind of attachment. Table 1 provides the list of subclasses.

Table 1

Attachment descriptor subclasses

Attachment type

Render pass attachment descriptor subclass

Color attachment

MTLRenderPassColorAttachmentDescriptor

Depth attachment

MTLRenderPassDepthAttachmentDescriptor

Stencil attachment

MTLRenderPassStencilAttachmentDescriptor

Multisampling

To perform multisampled antialiased rendering, you use two textures. Attach a MTLTextureType2DMultisample texture to the texture property and a 2D or cube texture to the resolveTexture property. When a rendering command is executed, all rendering is performed on the multisample texture as usual. Then, the contents of the multisample texture are resolved and written into the resolve texture. The resolveLevel, resolveSlice, and resolveDepthPlane properties specify where the resolved image is written to. The contents of the multisample texture are then discarded.

Topics

Specifying the Texture for the Attachment

texture

The texture object associated with this attachment.

level

The mipmap level of the texture used for rendering to the attachment.

slice

The slice of the texture used for rendering to the attachment.

depthPlane

The depth plane of the texture used for rendering to the attachment.

Specifying Rendering Pass Actions

loadAction

The action performed by this attachment at the start of a rendering pass for a render command encoder.

storeAction

The action performed by this attachment at the end of a rendering pass for a render command encoder.

storeActionOptions

The options that modify the store action performed by this attachment.

Specifying the Texture to Resolve Multisample Data

resolveTexture

The destination texture used when multisampled texture data is resolved into single sample values.

resolveLevel

The mipmap level of the texture used for the multisample resolve action.

resolveSlice

The slice of the texture used for the multisample resolve action.

resolveDepthPlane

The depth plane of the texture used for the multisample resolve action.

Constants

MTLLoadAction

The action performed at the start of a rendering pass for a render command encoder.

MTLStoreAction

The action performed at the end of a rendering pass for a render command encoder.

MTLStoreActionOptions

Options that modify a store action.

Relationships

Inherits From

Conforms To

See Also

Render Target

MTLRenderPassColorAttachmentDescriptor

A color render target that serves as the output destination for color pixels generated by a render pass.

MTLRenderPassDepthAttachmentDescriptor

A depth render target that serves as the output destination for depth pixels generated by a render pass.

MTLRenderPassStencilAttachmentDescriptor

A stencil render target that serves as the output destination for stencil pixels generated by a render pass.