Guides and Sample Code

Developer

Metal Best Practices Guide

On This Page

Load and Store Actions

Best Practice: Set appropriate load and store actions for your render targets.

Actions performed on your Metal render targets must be configured appropriately to avoid costly and unnecessary rendering work at the start (load action) or end (store action) of a rendering pass.

Choose an Appropriate Load Action

Use the following guidelines to determine the appropriate load action for a particular render target. These guidelines are also summarized in Table 9-1.

  • If all the render target pixels are rendered to, choose the DontCare action. There are no costs associated with this action, and texture data is always interpreted as undefined.

  • If the previous contents of the render target do not need to be preserved and only some of its pixels are rendered to, choose the Clear action. This action incurs the cost of writing a clear value to each pixel.

  • If the previous contents of the render target need to be preserved and only some of its pixels are rendered to, choose the Load action. This action incurs the cost of loading the previous contents.

Table 9-1Choosing a render target load action

Previous contents preserved

Pixels rendered to

Load action

N/A

All

DontCare

No

Some

Clear

Yes

Some

Load

Choose an Appropriate Store Action

Use the following guidelines to determine the appropriate store action for a particular render target.

  • If the contents of the render target do not need to be preserved, choose the DontCare action. There are no costs associated with this action, and texture data is always interpreted as undefined. This is a common case for depth and stencil render targets.

  • If the contents of the render target need to be preserved, choose the Store action. This is always the case for drawables and other displayable render targets.

  • If the render target is a multisample texture, refer to Table 9-2.

    Table 9-2Choosing a render target store action for a multisample texture

    Multisampled contents preserved

    Resolve texture specified

    Resolved contents preserved

    Store action

    Yes

    Yes

    Yes

    storeAndMultisampleResolve

    No

    Yes

    Yes

    MultisampleResolve

    Yes

    No

    N/A

    Store

    No

    No

    N/A

    DontCare

In some cases, the store action of a particular render target may not be known up front. To defer this decision, set the temporary unknown value when you create a MTLRenderPassAttachmentDescriptor object. You must specify a known store action before you finish encoding your rendering pass, otherwise an error occurs. Setting the unknown value may avoid potential costs incurred by setting the Store store action prematurely.

Evaluate Actions Between Rendering Passes

Render targets used across multiple rendering passes should be evaluated closely for optimal combinations of store and load actions between rendering passes. Table 9-3 lists these combinations.

Table 9-3Store and load actions between rendering passes

First rendering pass store action

Second rendering pass load action

DontCare

One of the following actions:

DontCare

Clear

One of the following actions:

Store

MultisampleResolve

storeAndMultisampleResolve

Load