use(_:count:stages:)
Ensures the shaders in the render pass’s subsequent draw commands have access to the resources you allocate from multiple heaps.
Declaration
func use(_ heaps: UnsafePointer<any MTLHeap>, count: Int, stages: MTLRenderStages)Parameters
Discussion
You can make the resources in heaps 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 resources within heaps through an argument buffer. The method ensures each resource is in a format that’s compatible with the shaders that depend on it.
The method’s applies the read resource usage option to all of the resources within heaps, except for textures. The method ignores any texture that has renderTarget, shaderWrite, or both in its usage property. For all other textures in heaps, the method optimizes each texture’s memory layout for rendering with a sampler. However, your shaders can’t read from those textures by calling this method because the texture needs a different memory layout that’s suitable for reading.
Methods that apply a usage option for resources (see Argument buffer resource preparation commands) override any previous calls that apply to a resource. For example, you can change the usage option for a buffer to write by passing it to useResource(_:usage:stages:) after calling this method. However, you can’t reverse the call order because this method resets the usage for all resources within heaps to read, overriding previous calls to useResource(_:usage:stages:).
The method instructs Metal to apply hazard tracking for resources you allocate from a heap that you create with MTLHazardTrackingMode.tracked. However, for untracked resources — which come from heaps you create with MTLHazardTrackingMode.untracked — you need to account for hazards by applying MTLFence or MTLEvent instances.
Apps typically call the method for heaps that have resources in argument buffers for a 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.