VkSparseMemoryBind(3)

# VkSparseMemoryBind(3) Manual Page

## Name

VkSparseMemoryBind - Structure specifying a sparse memory bind operation

Loading… please wait.

## C Specification

The `VkSparseMemoryBind` structure is defined as:

    // Provided by VK_VERSION_1_0
    typedef struct VkSparseMemoryBind {
        VkDeviceSize               resourceOffset;
        VkDeviceSize               size;
        VkDeviceMemory             memory;
        VkDeviceSize               memoryOffset;
        VkSparseMemoryBindFlags    flags;
    } VkSparseMemoryBind;

## Members

- `resourceOffset` is the offset into the resource.

- `size` is the size of the memory region to be bound.

- `memory` is the VkDeviceMemory object that the range of the resource is bound to. If `memory` is VK_NULL_HANDLE, the range is unbound.

- `memoryOffset` is the offset into the VkDeviceMemory object to bind the resource range to. If `memory` is VK_NULL_HANDLE, this value is ignored.

- `flags` is a bitmask of VkSparseMemoryBindFlagBits specifying usage of the binding operation.

## Description

The binding range [`resourceOffset`, `resourceOffset` + `size`) has different constraints based on `flags`. If `flags` contains `VK_SPARSE_MEMORY_BIND_METADATA_BIT`, the binding range must be within the mip tail region of the metadata aspect. This metadata region is defined by:

  metadataRegion = [base, base + `imageMipTailSize`)

  base = `imageMipTailOffset` + `imageMipTailStride` × n

and `imageMipTailOffset`, `imageMipTailSize`, and `imageMipTailStride` values are from the VkSparseImageMemoryRequirements corresponding to the metadata aspect of the image, and n is a valid array layer index for the image,

`imageMipTailStride` is considered to be zero for aspects where `VkSparseImageMemoryRequirements`::`formatProperties.flags` contains `VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT`.

If `flags` does not contain `VK_SPARSE_MEMORY_BIND_METADATA_BIT`, the binding range must be within the range [0,VkMemoryRequirements::`size`).

Valid Usage

- VUID-VkSparseMemoryBind-memory-01096
  If `memory` is not VK_NULL_HANDLE, `memory` and `memoryOffset` must match the memory requirements of the resource, as described in section https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#resources-association

- VUID-VkSparseMemoryBind-resourceOffset-09491
  If the resource being bound is a `VkBuffer`, `resourceOffset` and `memoryOffset` must be an integer multiple of the `alignment` of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with the buffer resource

- VUID-VkSparseMemoryBind-resourceOffset-09492
  If the resource being bound is a `VkImage`, `resourceOffset` and `memoryOffset` must be an integer multiple of the `alignment` of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with the image resource

- VUID-VkSparseMemoryBind-memory-01097
  If `memory` is not VK_NULL_HANDLE, `memory` must not have been created with a memory type that reports `VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT` bit set

- VUID-VkSparseMemoryBind-size-01098
  `size` must be greater than `0`

- VUID-VkSparseMemoryBind-resourceOffset-01099
  `resourceOffset` must be less than the size of the resource

- VUID-VkSparseMemoryBind-size-01100
  `size` must be less than or equal to the size of the resource minus `resourceOffset`

- VUID-VkSparseMemoryBind-memoryOffset-01101
  `memoryOffset` must be less than the size of `memory`

- VUID-VkSparseMemoryBind-size-01102
  `size` must be less than or equal to the size of `memory` minus `memoryOffset`

- VUID-VkSparseMemoryBind-memory-02730
  If `memory` was created with VkExportMemoryAllocateInfo::`handleTypes` not equal to `0`, at least one handle type it contained must also have been set in VkExternalMemoryBufferCreateInfo::`handleTypes` or VkExternalMemoryImageCreateInfo::`handleTypes` when the resource was created

- VUID-VkSparseMemoryBind-memory-02731
  If `memory` was created by a memory import operation, the external handle type of the imported memory must also have been set in VkExternalMemoryBufferCreateInfo::`handleTypes` or VkExternalMemoryImageCreateInfo::`handleTypes` when the resource was created

Valid Usage (Implicit)

- VUID-VkSparseMemoryBind-memory-parameter
  If `memory` is not VK_NULL_HANDLE, `memory` must be a valid VkDeviceMemory handle

- VUID-VkSparseMemoryBind-flags-parameter
  `flags` must be a valid combination of VkSparseMemoryBindFlagBits values

## See Also

VK_VERSION_1_0, VkDeviceMemory, VkDeviceSize, VkSparseBufferMemoryBindInfo, VkSparseImageOpaqueMemoryBindInfo, VkSparseMemoryBindFlags

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0