useResource(_:usage:stages:)
Ensures the shaders in the render pass’s subsequent draw commands have access to a resource.
Declaration
func useResource(_ resource: any MTLResource, usage: MTLResourceUsage, stages: MTLRenderStages)Parameters
- resource:
An Mtlresource instance that subsequent draw commands depend on.
- usage:
All the applicable access types the render pass’s shaders use for the resource, including Read and Write.
For applicable resources, you may be able to prevent the GPU from unnecessarily decompressing color attachments on some devices by setting
usageto Read. - stages:
All the render stages that depend on
resource, including Object, Mesh, Vertex, Fragment, and Tile.
Mentioned in
Discussion
You can make a resource resident (available in GPU memory) for the remaining duration of the render pass by calling this method. Call the method before encoding draw calls that may access resource through an argument buffer. The method ensures the resource is in a format that’s compatible with the shaders that depend on it.
For example, you can explicitly bind resources for the vertex stage with the methods in the Vertex shader resource preparation commands collection.
The method also informs Metal when to apply hazard tracking for a resource you create with MTLHazardTrackingMode.tracked. For a resource you create with MTLHazardTrackingMode.untracked, you need to apply an MTLFence or an MTLEvent to account for potential reading and writing hazards.
You can reconfigure an individual resource’s usage options for subsequent draw calls in the same render pass by calling this method again.
Apps typically call the method for a resource in an argument buffer as a part of their bindless implementation. For more information about argument buffers and bindless implementations, see Improving CPU performance by using argument buffers and Go bindless with Metal 3, respectively.