# useHeap(_:stages:) Ensures the shaders in the render pass’s subsequent draw commands have access to the resources you allocate from a heap. ``` func useHeap(_ heap: any MTLHeap, stages: MTLRenderStages) ``` ## Parameters `heap` An [`MTLHeap`](/documentation/Metal/MTLHeap) instance with resources that subsequent draw commands depend on. `stages` All the render stages that depend on resources within `heap`, including [`object`](/documentation/Metal/MTLRenderStages/object), [`mesh`](/documentation/Metal/MTLRenderStages/mesh), [`vertex`](/documentation/Metal/MTLRenderStages/vertex), [`fragment`](/documentation/Metal/MTLRenderStages/fragment), and [`tile`](/documentation/Metal/MTLRenderStages/tile). ## Discussion You can make the resources in `heap` *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 `heap` 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`](/documentation/Metal/MTLResourceUsage/read) resource usage option to all of the resources within `heap`, except for textures. The method ignores any texture that has [`renderTarget`](/documentation/Metal/MTLTextureUsage/renderTarget), [`shaderWrite`](/documentation/Metal/MTLTextureUsage/shaderWrite), or both in its [`usage`](/documentation/Metal/MTLTexture/usage) property. For all other textures in `heap`, 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. > Important: > You can instruct Metal to allow a shader to read from texture or write to other resources in heap, by calling ``doc://com.apple.metal/documentation/Metal/MTLRenderCommandEncoder/useResource(_:usage:stages:)``. Methods that apply a usage option for resources (see [Argument buffer resource preparation commands](/documentation/Metal/argument-buffer-resource-preparation-commands)) override any previous calls that apply to a resource. For example, you can change the usage option for buffer in `heap` to [`write`](/documentation/Metal/MTLResourceUsage/write) by passing it to [`useResource(_:usage:stages:)`](/documentation/Metal/MTLRenderCommandEncoder/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 `heap` to [`read`](/documentation/Metal/MTLResourceUsage/read), overriding previous calls to [`useResource(_:usage:stages:)`](/documentation/Metal/MTLRenderCommandEncoder/useResource(_:usage:stages:)). The method instructs Metal to apply hazard tracking for resources you allocate from a heap that you create with [`MTLHazardTrackingMode.tracked`](/documentation/Metal/MTLHazardTrackingMode/tracked). However, for untracked resources — which come from heaps you create with [`MTLHazardTrackingMode.untracked`](/documentation/Metal/MTLHazardTrackingMode/untracked) — you need to account for hazards by applying [`MTLFence`](/documentation/Metal/MTLFence) or [`MTLEvent`](/documentation/Metal/MTLEvent) instances. > Note: > The ``doc://com.apple.metal/documentation/Metal/MTLHeapDescriptor/hazardTrackingMode`` property of a new ``doc://com.apple.metal/documentation/Metal/MTLHeapDescriptor`` instance is ``doc://com.apple.metal/documentation/Metal/MTLHazardTrackingMode/default``, which is equivalent to ``doc://com.apple.metal/documentation/Metal/MTLHazardTrackingMode/untracked`` because heaps don’t track resources by default. 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](/documentation/Metal/improving-cpu-performance-by-using-argument-buffers) and [Go bindless with Metal 3](https://developer.apple.com/videos/play/wwdc2022/10101/), respectively. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)