Instance Method

nextDrawable()

Returns a Metal drawable.

Declaration

func nextDrawable() -> CAMetalDrawable?

Return Value

A Metal drawable. Use the drawable’s texture property to configure a MTLRenderPipelineColorAttachmentDescriptor object for rendering to the layer.

Discussion

A CAMetalLayer object maintains an internal pool of textures for displaying layer content, each wrapped in a CAMetalDrawable object. At any given time, one of these textures is displayed onscreen. Use this method to retrieve the next available drawable from the pool. If all drawables are in use, the layer waits up to one second for one to become available, after which it returns nil. The allowsNextDrawableTimeout property affects this behavior.

This method returns nil if the layer’s pixelFormat or other properties are invalid.

Use a MTLRenderCommandEncoder object to render into the drawable’s texture and present it for display (typically registered via the present(_:) method of a command buffer). Try to minimize the time between when you fetch the drawable and when you submit the command buffer that uses it. For example, you might perform other work on the CPU, render to offscreen textures or execute compute passes, then obtain the drawable and encode a command buffer to render to it. After you submit this command buffer, release all strong references to the drawable. A texture can be reused only if it is not onscreen and all strong references to the drawable have been released. If you don’t release drawables correctly, the layer runs out of drawables to vend and future calls to nextDrawable() will return nil.

For best results, contain any code that uses a drawable within a tight autorelease pool block, as shown in Listing 1. This ensures that the drawable is released promptly.

Listing 1

An autoreleasepool that contains drawables

@autoreleasepool {
    // code that uses a drawable
}

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software