Class

MTLRenderPassAttachmentDescriptor

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

Declaration

class 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 MTLTextureType.type2DMultisample 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

var texture: MTLTexture?

The texture object associated with this attachment.

var level: Int

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

var slice: Int

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

var depthPlane: Int

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

Specifying Rendering Pass Actions

var loadAction: MTLLoadAction

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

var storeAction: MTLStoreAction

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

var storeActionOptions: MTLStoreActionOptions

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

Specifying the Texture to Resolve Multisample Data

var resolveTexture: MTLTexture?

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

var resolveLevel: Int

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

var resolveSlice: Int

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

var resolveDepthPlane: Int

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

Constants

enum MTLLoadAction

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

enum MTLStoreAction

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

struct MTLStoreActionOptions

Options that modify a store action.

Enumerations

enum MTLMultisampleStencilResolveFilter

Constants used to control the multisample stencil resolve operation.

Relationships

Inherits From

See Also

Specifying the Attachments for a Rendering Pass

Setting Load and Store Actions

Set actions that define how a render pass loads and stores a render target.

var colorAttachments: MTLRenderPassColorAttachmentDescriptorArray

An array of state information for attachments that store color data.

var depthAttachment: MTLRenderPassDepthAttachmentDescriptor!

State information for an attachment that stores depth data.

var stencilAttachment: MTLRenderPassStencilAttachmentDescriptor!

State information for an attachment that stores stencil data.

class MTLRenderPassColorAttachmentDescriptor

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

class MTLRenderPassDepthAttachmentDescriptor

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

class MTLRenderPassStencilAttachmentDescriptor

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