Vulkan® 1.3.283 - A Specification (with all ratified extensions)

34. Micromap

34.1. Micromaps

Acceleration structures store and organize geometry for ray tracing, but in some cases it is beneficial to include some information within the geometry, particularly for triangles. A micromap organizes this data around a map of values corresponding to subdivided microtriangles which can be added to a triangle geometry when building a bottom level acceleration structure.

An opacity micromap is a type of micromap which stores information to control intersection opacity as described in Ray Opacity Micromap.

A micromap is considered to be constructed if a micromap build command or copy command has been executed with the given acceleration structure as the destination.

34.1.1. Building Micromaps

To build micromaps call:

// Provided by VK_EXT_opacity_micromap
void vkCmdBuildMicromapsEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    infoCount,
    const VkMicromapBuildInfoEXT*               pInfos);

commandBuffer is the command buffer into which the command will be recorded.
infoCount is the number of micromaps to build. It specifies the number of the pInfos structures that must be provided.
pInfos is a pointer to an array of infoCount VkMicromapBuildInfoEXT structures defining the data used to build each micromap.

The vkCmdBuildMicromapsEXT command provides the ability to initiate multiple micromaps builds, however there is no ordering or synchronization implied between any of the individual micromap builds.

Note

This means that there cannot be any memory aliasing between any micromap memories or scratch memories being used by any of the builds.

Accesses to the micromap scratch buffers as identified by the VkMicromapBuildInfoEXT::scratchData buffer device addresses must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of (VK_ACCESS_2_MICROMAP_READ_BIT_EXT | VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT). Accesses to VkMicromapBuildInfoEXT::dstMicromap must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT.

Accesses to other input buffers as identified by any used values of VkMicromapBuildInfoEXT::data or VkMicromapBuildInfoEXT::triangleArray must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_SHADER_READ_BIT.

Valid Usage

VUID-vkCmdBuildMicromapsEXT-pInfos-07461
For each pInfos[i], dstMicromap must have been created with a value of VkMicromapCreateInfoEXT::size greater than or equal to the memory size required by the build operation, as returned by vkGetMicromapBuildSizesEXT with pBuildInfo = pInfos[i]
VUID-vkCmdBuildMicromapsEXT-mode-07462
The mode member of each element of pInfos must be a valid VkBuildMicromapModeEXT value
VUID-vkCmdBuildMicromapsEXT-dstMicromap-07463
The dstMicromap member of any element of pInfos must be a valid VkMicromapEXT handle
VUID-vkCmdBuildMicromapsEXT-pInfos-07464
For each element of pInfos its type member must match the value of VkMicromapCreateInfoEXT::type when its dstMicromap was created
VUID-vkCmdBuildMicromapsEXT-dstMicromap-07465
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstMicromap member of any other element of pInfos, which is accessed by this command
VUID-vkCmdBuildMicromapsEXT-dstMicromap-07466
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command
VUID-vkCmdBuildMicromapsEXT-scratchData-07467
The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

VUID-vkCmdBuildMicromapsEXT-pInfos-07508
For each element of pInfos, the buffer used to create its dstMicromap member must be bound to device memory
VUID-vkCmdBuildMicromapsEXT-pInfos-07509
If pInfos[i].mode is VK_BUILD_MICROMAP_MODE_BUILD_EXT, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the buildScratchSize member of the VkMicromapBuildSizesInfoEXT structure returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure and primitive count
VUID-vkCmdBuildMicromapsEXT-data-07510
The buffers from which the buffer device addresses for all of the data and triangleArray members of all pInfos[i] are queried must have been created with the VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT usage flag
VUID-vkCmdBuildMicromapsEXT-pInfos-07511
For each element of pInfos[i] the buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag
VUID-vkCmdBuildMicromapsEXT-pInfos-07512
For each element of pInfos, its scratchData.deviceAddress, data.deviceAddress, and triangleArray.deviceAddress members must be valid device addresses obtained from vkGetBufferDeviceAddress
VUID-vkCmdBuildMicromapsEXT-pInfos-07513
For each element of pInfos, if scratchData.deviceAddress, data.deviceAddress, or triangleArray.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object
VUID-vkCmdBuildMicromapsEXT-pInfos-07514
For each element of pInfos, its scratchData.deviceAddress member must be a multiple of VkPhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment
VUID-vkCmdBuildMicromapsEXT-pInfos-07515
For each element of pInfos, its triangleArray.deviceAddress and data.deviceAddress members must be a multiple of 256

Valid Usage (Implicit)

VUID-vkCmdBuildMicromapsEXT-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdBuildMicromapsEXT-pInfos-parameter
pInfos must be a valid pointer to an array of infoCount valid VkMicromapBuildInfoEXT structures
VUID-vkCmdBuildMicromapsEXT-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdBuildMicromapsEXT-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support compute operations
VUID-vkCmdBuildMicromapsEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdBuildMicromapsEXT-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdBuildMicromapsEXT-infoCount-arraylength
infoCount must be greater than 0

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	Action

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary
Secondary

Outside

Compute

Action

Formats which can be set in VkMicromapUsageEXT::format and VkMicromapTriangleEXT::format for micromap builds, are:

// Provided by VK_EXT_opacity_micromap
typedef enum VkOpacityMicromapFormatEXT {
    VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT = 1,
    VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT = 2,
} VkOpacityMicromapFormatEXT;

VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT indicates that the given micromap format has one bit per subtriangle encoding either fully opaque or fully transparent.
VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT indicates that the given micromap format has two bits per subtriangle encoding four modes which can be interpreted as described in ray traversal.

Note

For compactness, these values are stored as 16-bit in some structures.

The VkMicromapBuildInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildInfoEXT {
    VkStructureType                     sType;
    const void*                         pNext;
    VkMicromapTypeEXT                   type;
    VkBuildMicromapFlagsEXT             flags;
    VkBuildMicromapModeEXT              mode;
    VkMicromapEXT                       dstMicromap;
    uint32_t                            usageCountsCount;
    const VkMicromapUsageEXT*           pUsageCounts;
    const VkMicromapUsageEXT* const*    ppUsageCounts;
    VkDeviceOrHostAddressConstKHR       data;
    VkDeviceOrHostAddressKHR            scratchData;
    VkDeviceOrHostAddressConstKHR       triangleArray;
    VkDeviceSize                        triangleArrayStride;
} VkMicromapBuildInfoEXT;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
type is a VkMicromapTypeEXT value specifying the type of micromap being built.
flags is a bitmask of VkBuildMicromapFlagBitsEXT specifying additional parameters of the micromap.
mode is a VkBuildMicromapModeEXT value specifying the type of operation to perform.
dstMicromap is a pointer to the target micromap for the build.
usageCountsCount specifies the number of usage counts structures that will be used to determine the size of this micromap.
pUsageCounts is a pointer to an array of VkMicromapUsageEXT structures.
ppUsageCounts is a pointer to an array of pointers to VkMicromapUsageEXT structures.
data is the device or host address to memory which contains the data for the micromap.
scratchData is the device or host address to memory that will be used as scratch memory for the build.
triangleArray is the device or host address to memory containing the VkMicromapTriangleEXT data
triangleArrayStride is the stride in bytes between each element of triangleArray

Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL. The elements of the non-NULL array describe the total counts used to build each micromap. Each element contains a count which is the number of micromap triangles of that format and subdivisionLevel contained in the micromap. Multiple elements with the same format and subdivisionLevel are allowed and the total count for that format and subdivisionLevel is the sum of the count for each element.

Each micromap triangle refers to one element in triangleArray which contains the format and subdivisionLevel for that particular triangle as well as a dataOffset in bytes which is the location relative to data where that triangle’s micromap data begins. The data at triangleArray is laid out as a 4 byte unsigned integer for the dataOffset followed by a 2 byte unsigned integer for the subdivision level then a 2 byte unsigned integer for the format. In practice, compilers compile VkMicromapTriangleEXT to match this pattern.

For opacity micromaps, the data at data is packed as either one bit per element for VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or two bits per element for VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT and is packed from LSB to MSB in each byte. The data at each index in those bytes is interpreted as discussed in Ray Opacity Micromap.

Valid Usage

VUID-VkMicromapBuildInfoEXT-pUsageCounts-07516
Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL
VUID-VkMicromapBuildInfoEXT-type-07517
If type is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of VkMicromapUsageEXT must be a valid value from VkOpacityMicromapFormatEXT
VUID-VkMicromapBuildInfoEXT-type-07518
If type is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of VkMicromapTriangleEXT must be a valid value from VkOpacityMicromapFormatEXT

Valid Usage (Implicit)

VUID-VkMicromapBuildInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT
VUID-VkMicromapBuildInfoEXT-pNext-pNext
pNext must be NULL
VUID-VkMicromapBuildInfoEXT-type-parameter
type must be a valid VkMicromapTypeEXT value
VUID-VkMicromapBuildInfoEXT-flags-parameter
flags must be a valid combination of VkBuildMicromapFlagBitsEXT values
VUID-VkMicromapBuildInfoEXT-pUsageCounts-parameter
If usageCountsCount is not 0, and pUsageCounts is not NULL, pUsageCounts must be a valid pointer to an array of usageCountsCount VkMicromapUsageEXT structures
VUID-VkMicromapBuildInfoEXT-ppUsageCounts-parameter
If usageCountsCount is not 0, and ppUsageCounts is not NULL, ppUsageCounts must be a valid pointer to an array of usageCountsCount valid pointers to VkMicromapUsageEXT structures

The VkBuildMicromapModeEXT enumeration is defined as:

// Provided by VK_EXT_opacity_micromap
typedef enum VkBuildMicromapModeEXT {
    VK_BUILD_MICROMAP_MODE_BUILD_EXT = 0,
} VkBuildMicromapModeEXT;

VK_BUILD_MICROMAP_MODE_BUILD_EXT specifies that the destination micromap will be built using the specified data.

The VkMicromapUsageEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapUsageEXT {
    uint32_t    count;
    uint32_t    subdivisionLevel;
    uint32_t    format;
} VkMicromapUsageEXT;

count is the number of triangles in the usage format defined by the subdivisionLevel and format below in the micromap
subdivisionLevel is the subdivision level of this usage format
format is the format of this usage format

Valid Usage

VUID-VkMicromapUsageEXT-format-07519
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT then format must be VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT
VUID-VkMicromapUsageEXT-format-07520
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT then subdivisionLevel must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity2StateSubdivisionLevel
VUID-VkMicromapUsageEXT-format-07521
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT then subdivisionLevel must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity4StateSubdivisionLevel

The format is interpreted based on the type of the micromap using it.

The VkMicromapTriangleEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapTriangleEXT {
    uint32_t    dataOffset;
    uint16_t    subdivisionLevel;
    uint16_t    format;
} VkMicromapTriangleEXT;

dataOffset is the offset in bytes of the start of the data for this triangle. This is a byte aligned value.
subdivisionLevel is the subdivision level of this triangle
format is the format of this triangle

Valid Usage

VUID-VkMicromapTriangleEXT-format-07522
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT then format must be VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT
VUID-VkMicromapTriangleEXT-format-07523
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT then subdivisionLevel must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity2StateSubdivisionLevel
VUID-VkMicromapTriangleEXT-format-07524
If the VkMicromapTypeEXT of the micromap is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT then subdivisionLevel must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity4StateSubdivisionLevel

The format is interpreted based on the type of the micromap using it.

34.1.2. Copying Micromaps

An additional command exists for copying micromaps without updating their contents. Before copying, an application must query the size of the resulting micromap.

To query micromap size parameters call:

// Provided by VK_EXT_opacity_micromap
void vkCmdWriteMicromapsPropertiesEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    micromapCount,
    const VkMicromapEXT*                        pMicromaps,
    VkQueryType                                 queryType,
    VkQueryPool                                 queryPool,
    uint32_t                                    firstQuery);

commandBuffer is the command buffer into which the command will be recorded.
micromapCount is the count of micromaps for which to query the property.
pMicromaps is a pointer to an array of existing previously built micromaps.
queryType is a VkQueryType value specifying the type of queries managed by the pool.
queryPool is the query pool that will manage the results of the query.
firstQuery is the first query index within the query pool that will contain the micromapCount number of results.

Accesses to any of the micromaps listed in pMicromaps must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_2_MICROMAP_READ_BIT_EXT.

If queryType is VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then the value written out is the number of bytes required by a serialized micromap.
If queryType is VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT, then the value written out is the number of bytes required by a compacted micromap.

Valid Usage

VUID-vkCmdWriteMicromapsPropertiesEXT-queryPool-07525
queryPool must have been created with a queryType matching queryType
VUID-vkCmdWriteMicromapsPropertiesEXT-queryPool-07526
The queries identified by queryPool and firstQuery must be unavailable
VUID-vkCmdWriteMicromapsPropertiesEXT-buffer-07527
The buffer used to create each micromap in pMicrmaps must be bound to device memory
VUID-vkCmdWriteMicromapsPropertiesEXT-query-07528
The sum of query plus micromapCount must be less than or equal to the number of queries in queryPool

VUID-vkCmdWriteMicromapsPropertiesEXT-pMicromaps-07501
All micromaps in pMicromaps must have been constructed prior to the execution of this command
VUID-vkCmdWriteMicromapsPropertiesEXT-pMicromaps-07502
All micromaps in pMicromaps must have been constructed with VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT if queryType is VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT
VUID-vkCmdWriteMicromapsPropertiesEXT-queryType-07503
queryType must be VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT or VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT

Valid Usage (Implicit)

VUID-vkCmdWriteMicromapsPropertiesEXT-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdWriteMicromapsPropertiesEXT-pMicromaps-parameter
pMicromaps must be a valid pointer to an array of micromapCount valid VkMicromapEXT handles
VUID-vkCmdWriteMicromapsPropertiesEXT-queryType-parameter
queryType must be a valid VkQueryType value
VUID-vkCmdWriteMicromapsPropertiesEXT-queryPool-parameter
queryPool must be a valid VkQueryPool handle
VUID-vkCmdWriteMicromapsPropertiesEXT-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdWriteMicromapsPropertiesEXT-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support compute operations
VUID-vkCmdWriteMicromapsPropertiesEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdWriteMicromapsPropertiesEXT-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdWriteMicromapsPropertiesEXT-micromapCount-arraylength
micromapCount must be greater than 0
VUID-vkCmdWriteMicromapsPropertiesEXT-commonparent
Each of commandBuffer, queryPool, and the elements of pMicromaps must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	Action

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary
Secondary

Outside

Compute

Action

To copy a micromap call:

// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMicromapEXT(
    VkCommandBuffer                             commandBuffer,
    const VkCopyMicromapInfoEXT*                pInfo);

commandBuffer is the command buffer into which the command will be recorded.
pInfo is a pointer to a VkCopyMicromapInfoEXT structure defining the copy operation.

This command copies the pInfo->src micromap to the pInfo->dst micromap in the manner specified by pInfo->mode.

Accesses to pInfo->src and pInfo->dst must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_2_MICROMAP_READ_BIT_EXT or VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT as appropriate.

Valid Usage

VUID-vkCmdCopyMicromapEXT-buffer-07529
The buffer used to create pInfo->src must be bound to device memory
VUID-vkCmdCopyMicromapEXT-buffer-07530
The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

VUID-vkCmdCopyMicromapEXT-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdCopyMicromapEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMicromapInfoEXT structure
VUID-vkCmdCopyMicromapEXT-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdCopyMicromapEXT-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support compute operations
VUID-vkCmdCopyMicromapEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdCopyMicromapEXT-videocoding
This command must only be called outside of a video coding scope

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	Action

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary
Secondary

Outside

Compute

Action

The VkCopyMicromapInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMicromapInfoEXT {
    VkStructureType          sType;
    const void*              pNext;
    VkMicromapEXT            src;
    VkMicromapEXT            dst;
    VkCopyMicromapModeEXT    mode;
} VkCopyMicromapInfoEXT;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
src is the source micromap for the copy.
dst is the target micromap for the copy.
mode is a VkCopyMicromapModeEXT value specifying additional operations to perform during the copy.

Valid Usage

VUID-VkCopyMicromapInfoEXT-mode-07531
mode must be VK_COPY_MICROMAP_MODE_COMPACT_EXT or VK_COPY_MICROMAP_MODE_CLONE_EXT
VUID-VkCopyMicromapInfoEXT-src-07532
The source acceleration structure src must have been constructed prior to the execution of this command
VUID-VkCopyMicromapInfoEXT-mode-07533
If mode is VK_COPY_MICROMAP_MODE_COMPACT_EXT, src must have been constructed with VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT in the build
VUID-VkCopyMicromapInfoEXT-buffer-07534
The buffer used to create src must be bound to device memory
VUID-VkCopyMicromapInfoEXT-buffer-07535
The buffer used to create dst must be bound to device memory

Valid Usage (Implicit)

VUID-VkCopyMicromapInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_COPY_MICROMAP_INFO_EXT
VUID-VkCopyMicromapInfoEXT-pNext-pNext
pNext must be NULL
VUID-VkCopyMicromapInfoEXT-src-parameter
src must be a valid VkMicromapEXT handle
VUID-VkCopyMicromapInfoEXT-dst-parameter
dst must be a valid VkMicromapEXT handle
VUID-VkCopyMicromapInfoEXT-mode-parameter
mode must be a valid VkCopyMicromapModeEXT value
VUID-VkCopyMicromapInfoEXT-commonparent
Both of dst, and src must have been created, allocated, or retrieved from the same VkDevice

Possible values of mode specifying additional operations to perform during the copy, are:

// Provided by VK_EXT_opacity_micromap
typedef enum VkCopyMicromapModeEXT {
    VK_COPY_MICROMAP_MODE_CLONE_EXT = 0,
    VK_COPY_MICROMAP_MODE_SERIALIZE_EXT = 1,
    VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT = 2,
    VK_COPY_MICROMAP_MODE_COMPACT_EXT = 3,
} VkCopyMicromapModeEXT;

VK_COPY_MICROMAP_MODE_CLONE_EXT creates a direct copy of the micromap specified in src into the one specified by dst. The dst micromap must have been created with the same parameters as src.
VK_COPY_MICROMAP_MODE_SERIALIZE_EXT serializes the micromap to a semi-opaque format which can be reloaded on a compatible implementation.
VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT deserializes the semi-opaque serialization format in the buffer to the micromap.
VK_COPY_MICROMAP_MODE_COMPACT_EXT creates a more compact version of a micromap src into dst. The micromap dst must have been created with a size at least as large as that returned by vkCmdWriteMicromapsPropertiesEXT after the build of the micromap specified by src.

To copy a micromap to device memory call:

// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMicromapToMemoryEXT(
    VkCommandBuffer                             commandBuffer,
    const VkCopyMicromapToMemoryInfoEXT*        pInfo);

commandBuffer is the command buffer into which the command will be recorded.
pInfo is an a pointer to a VkCopyMicromapToMemoryInfoEXT structure defining the copy operation.

Accesses to pInfo->src must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_2_MICROMAP_READ_BIT_EXT. Accesses to the buffer indicated by pInfo->dst.deviceAddress must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_TRANSFER_WRITE_BIT.

This command produces the same results as vkCopyMicromapToMemoryEXT, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToMicromapEXT or vkCopyMemoryToMicromapEXT.

The defined header structure for the serialized data consists of:

VK_UUID_SIZE bytes of data matching VkPhysicalDeviceIDProperties::driverUUID
VK_UUID_SIZE bytes of data identifying the compatibility for comparison using vkGetDeviceMicromapCompatibilityEXT The serialized data is written to the buffer (or read from the buffer) according to the host endianness.

Valid Usage

VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07536
pInfo->dst.deviceAddress must be a valid device address for a buffer bound to device memory
VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07537
pInfo->dst.deviceAddress must be aligned to 256 bytes
VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07538
If the buffer pointed to by pInfo->dst.deviceAddress is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
VUID-vkCmdCopyMicromapToMemoryEXT-buffer-07539
The buffer used to create pInfo->src must be bound to device memory

Valid Usage (Implicit)

VUID-vkCmdCopyMicromapToMemoryEXT-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMicromapToMemoryInfoEXT structure
VUID-vkCmdCopyMicromapToMemoryEXT-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdCopyMicromapToMemoryEXT-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support compute operations
VUID-vkCmdCopyMicromapToMemoryEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdCopyMicromapToMemoryEXT-videocoding
This command must only be called outside of a video coding scope

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	Action

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary
Secondary

Outside

Compute

Action

// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMicromapToMemoryInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    VkMicromapEXT               src;
    VkDeviceOrHostAddressKHR    dst;
    VkCopyMicromapModeEXT       mode;
} VkCopyMicromapToMemoryInfoEXT;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
src is the source micromap for the copy
dst is the device or host address to memory which is the target for the copy
mode is a VkCopyMicromapModeEXT value specifying additional operations to perform during the copy.

Valid Usage

VUID-VkCopyMicromapToMemoryInfoEXT-src-07540
The source micromap src must have been constructed prior to the execution of this command
VUID-VkCopyMicromapToMemoryInfoEXT-dst-07541
The memory pointed to by dst must be at least as large as the serialization size of src, as reported by vkWriteMicromapsPropertiesEXT or vkCmdWriteMicromapsPropertiesEXT with a query type of VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT
VUID-VkCopyMicromapToMemoryInfoEXT-mode-07542
mode must be VK_COPY_MICROMAP_MODE_SERIALIZE_EXT

Valid Usage (Implicit)

VUID-VkCopyMicromapToMemoryInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_COPY_MICROMAP_TO_MEMORY_INFO_EXT
VUID-VkCopyMicromapToMemoryInfoEXT-pNext-pNext
pNext must be NULL
VUID-VkCopyMicromapToMemoryInfoEXT-src-parameter
src must be a valid VkMicromapEXT handle
VUID-VkCopyMicromapToMemoryInfoEXT-mode-parameter
mode must be a valid VkCopyMicromapModeEXT value

To copy device memory to a micromap call:

// Provided by VK_EXT_opacity_micromap
void vkCmdCopyMemoryToMicromapEXT(
    VkCommandBuffer                             commandBuffer,
    const VkCopyMemoryToMicromapInfoEXT*        pInfo);

commandBuffer is the command buffer into which the command will be recorded.
pInfo is a pointer to a VkCopyMicromapToMemoryInfoEXT structure defining the copy operation.

Accesses to pInfo->dst must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_2_MICROMAP_READ_BIT_EXT. Accesses to the buffer indicated by pInfo->src.deviceAddress must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of VK_ACCESS_TRANSFER_READ_BIT.

This command can accept micromaps produced by either vkCmdCopyMicromapToMemoryEXT or vkCopyMicromapToMemoryEXT.

Valid Usage

VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07543
pInfo->src.deviceAddress must be a valid device address for a buffer bound to device memory
VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07544
pInfo->src.deviceAddress must be aligned to 256 bytes
VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07545
If the buffer pointed to by pInfo->src.deviceAddress is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
VUID-vkCmdCopyMemoryToMicromapEXT-buffer-07546
The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

VUID-vkCmdCopyMemoryToMicromapEXT-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMemoryToMicromapInfoEXT structure
VUID-vkCmdCopyMemoryToMicromapEXT-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdCopyMemoryToMicromapEXT-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support compute operations
VUID-vkCmdCopyMemoryToMicromapEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdCopyMemoryToMicromapEXT-videocoding
This command must only be called outside of a video coding scope

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	Action

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary
Secondary

Outside

Compute

Action

The VkCopyMemoryToMicromapInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkCopyMemoryToMicromapInfoEXT {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDeviceOrHostAddressConstKHR    src;
    VkMicromapEXT                    dst;
    VkCopyMicromapModeEXT            mode;
} VkCopyMemoryToMicromapInfoEXT;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
src is the device or host address to memory containing the source data for the copy.
dst is the target micromap for the copy.
mode is a VkCopyMicromapModeEXT value specifying additional operations to perform during the copy.

Valid Usage

VUID-VkCopyMemoryToMicromapInfoEXT-src-07547
The source memory pointed to by src must contain data previously serialized using vkCmdCopyMicromapToMemoryEXT
VUID-VkCopyMemoryToMicromapInfoEXT-mode-07548
mode must be VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT
VUID-VkCopyMemoryToMicromapInfoEXT-src-07549
The data in src must have a format compatible with the destination physical device as returned by vkGetDeviceMicromapCompatibilityEXT
VUID-VkCopyMemoryToMicromapInfoEXT-dst-07550
dst must have been created with a size greater than or equal to that used to serialize the data in src

Valid Usage (Implicit)

VUID-VkCopyMemoryToMicromapInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_COPY_MEMORY_TO_MICROMAP_INFO_EXT
VUID-VkCopyMemoryToMicromapInfoEXT-pNext-pNext
pNext must be NULL
VUID-VkCopyMemoryToMicromapInfoEXT-dst-parameter
dst must be a valid VkMicromapEXT handle
VUID-VkCopyMemoryToMicromapInfoEXT-mode-parameter
mode must be a valid VkCopyMicromapModeEXT value

To check if a serialized micromap is compatible with the current device call:

// Provided by VK_EXT_opacity_micromap
void vkGetDeviceMicromapCompatibilityEXT(
    VkDevice                                    device,
    const VkMicromapVersionInfoEXT*             pVersionInfo,
    VkAccelerationStructureCompatibilityKHR*    pCompatibility);

device is the device to check the version against.
pVersionInfo is a pointer to a VkMicromapVersionInfoEXT structure specifying version information to check against the device.
pCompatibility is a pointer to a VkAccelerationStructureCompatibilityKHR value in which compatibility information is returned.

Valid Usage

VUID-vkGetDeviceMicromapCompatibilityEXT-micromap-07551
The micromap feature must be enabled

Valid Usage (Implicit)

VUID-vkGetDeviceMicromapCompatibilityEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkGetDeviceMicromapCompatibilityEXT-pVersionInfo-parameter
pVersionInfo must be a valid pointer to a valid VkMicromapVersionInfoEXT structure
VUID-vkGetDeviceMicromapCompatibilityEXT-pCompatibility-parameter
pCompatibility must be a valid pointer to a VkAccelerationStructureCompatibilityKHR value

The VkMicromapVersionInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapVersionInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    const uint8_t*     pVersionData;
} VkMicromapVersionInfoEXT;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
pVersionData is a pointer to the version header of a micromap as defined in vkCmdCopyMicromapToMemoryEXT

Note

pVersionData is a pointer to an array of 2×VK_UUID_SIZE uint8_t values instead of two VK_UUID_SIZE arrays as the expected use case for this member is to be pointed at the header of a previously serialized micromap (via vkCmdCopyMicromapToMemoryEXT or vkCopyMicromapToMemoryEXT) that is loaded in memory. Using arrays would necessitate extra memory copies of the UUIDs.

Valid Usage (Implicit)

VUID-VkMicromapVersionInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_MICROMAP_VERSION_INFO_EXT
VUID-VkMicromapVersionInfoEXT-pNext-pNext
pNext must be NULL
VUID-VkMicromapVersionInfoEXT-pVersionData-parameter
pVersionData must be a valid pointer to an array of $2 \times V K_U U I D_S I Z E$ uint8_t values

34.2. Host Micromap Operations

Implementations are also required to provide host implementations of the micromap operations if the micromapHostCommands feature is enabled:

vkBuildMicromapsEXT corresponding to vkCmdBuildMicromapsEXT
vkCopyMicromapEXT corresponding to vkCmdCopyMicromapEXT
vkCopyMicromapToMemoryEXT corresponding to vkCmdCopyMicromapToMemoryEXT
vkCopyMemoryToMicromapEXT corresponding to vkCmdCopyMemoryToMicromapEXT
vkWriteMicromapsPropertiesEXT corresponding to vkCmdWriteMicromapsPropertiesEXT

These commands are functionally equivalent to their device counterparts, except that they are executed on the host timeline, rather than being enqueued into command buffers.

All micromaps used by the host commands must be bound to host-visible memory, and all input data for micromap builds must be referenced using host addresses instead of device addresses. Applications are not required to map micromap memory when using the host commands.

Note

The vkBuildMicromapsEXT and vkCmdBuildMicromapsEXT may use different algorithms, and thus are not required to produce identical structures.

Apart from these details, the host and device operations are interchangeable.

Note

For efficient execution, micromaps manipulated using these commands should always be bound to host cached memory, as the implementation may need to repeatedly read and write this memory during the execution of the command.

To build micromaps on the host, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkBuildMicromapsEXT(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    uint32_t                                    infoCount,
    const VkMicromapBuildInfoEXT*               pInfos);

device is the VkDevice for which the micromaps are being built.
deferredOperation is an optional VkDeferredOperationKHR to request deferral for this command.
infoCount is the number of micromaps to build. It specifies the number of the pInfos that must be provided.
pInfos is a pointer to an array of infoCount VkMicromapBuildInfoEXT structures defining the geometry used to build each micromap.

This command fulfills the same task as vkCmdBuildMicromapsEXT but is executed by the host.

The vkBuildMicromapsEXT command provides the ability to initiate multiple micromaps builds, however there is no ordering or synchronization implied between any of the individual micromap builds.

Note

This means that there cannot be any memory aliasing between any micromap memories or scratch memories being used by any of the builds.

Valid Usage

VUID-vkBuildMicromapsEXT-pInfos-07461
For each pInfos[i], dstMicromap must have been created with a value of VkMicromapCreateInfoEXT::size greater than or equal to the memory size required by the build operation, as returned by vkGetMicromapBuildSizesEXT with pBuildInfo = pInfos[i]
VUID-vkBuildMicromapsEXT-mode-07462
The mode member of each element of pInfos must be a valid VkBuildMicromapModeEXT value
VUID-vkBuildMicromapsEXT-dstMicromap-07463
The dstMicromap member of any element of pInfos must be a valid VkMicromapEXT handle
VUID-vkBuildMicromapsEXT-pInfos-07464
For each element of pInfos its type member must match the value of VkMicromapCreateInfoEXT::type when its dstMicromap was created
VUID-vkBuildMicromapsEXT-dstMicromap-07465
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstMicromap member of any other element of pInfos, which is accessed by this command
VUID-vkBuildMicromapsEXT-dstMicromap-07466
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command
VUID-vkBuildMicromapsEXT-scratchData-07467
The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

VUID-vkBuildMicromapsEXT-pInfos-07552
For each element of pInfos, the buffer used to create its dstMicromap member must be bound to host-visible device memory
VUID-vkBuildMicromapsEXT-pInfos-07553
For each element of pInfos, all referenced addresses of pInfos[i].data.hostAddress must be valid host memory
VUID-vkBuildMicromapsEXT-pInfos-07554
For each element of pInfos, all referenced addresses of pInfos[i].triangleArray.hostAddress must be valid host memory
VUID-vkBuildMicromapsEXT-micromapHostCommands-07555
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapHostCommands feature must be enabled
VUID-vkBuildMicromapsEXT-pInfos-07556
If pInfos[i].mode is VK_BUILD_MICROMAP_MODE_BUILD_EXT, all addresses between pInfos[i].scratchData.hostAddress and pInfos[i].scratchData.hostAddress + N - 1 must be valid host memory, where N is given by the buildScratchSize member of the VkMicromapBuildSizesInfoEXT structure returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure and primitive count
VUID-vkBuildMicromapsEXT-pInfos-07557
For each element of pInfos, the buffer used to create its dstMicromap member must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

VUID-vkBuildMicromapsEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkBuildMicromapsEXT-deferredOperation-parameter
If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle
VUID-vkBuildMicromapsEXT-pInfos-parameter
pInfos must be a valid pointer to an array of infoCount valid VkMicromapBuildInfoEXT structures
VUID-vkBuildMicromapsEXT-infoCount-arraylength
infoCount must be greater than 0
VUID-vkBuildMicromapsEXT-deferredOperation-parent
If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS
VK_OPERATION_DEFERRED_KHR
VK_OPERATION_NOT_DEFERRED_KHR

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy or compact a micromap on the host, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMicromapEXT(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyMicromapInfoEXT*                pInfo);

device is the device which owns the micromaps.
deferredOperation is an optional VkDeferredOperationKHR to request deferral for this command.
pInfo is a pointer to a VkCopyMicromapInfoEXT structure defining the copy operation.

This command fulfills the same task as vkCmdCopyMicromapEXT but is executed by the host.

Valid Usage

VUID-vkCopyMicromapEXT-deferredOperation-03678
Any previous deferred operation that was associated with deferredOperation must be complete
VUID-vkCopyMicromapEXT-buffer-07558
The buffer used to create pInfo->src must be bound to host-visible device memory
VUID-vkCopyMicromapEXT-buffer-07559
The buffer used to create pInfo->dst must be bound to host-visible device memory
VUID-vkCopyMicromapEXT-micromapHostCommands-07560
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapHostCommands feature must be enabled
VUID-vkCopyMicromapEXT-buffer-07561
The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances
VUID-vkCopyMicromapEXT-buffer-07562
The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

VUID-vkCopyMicromapEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkCopyMicromapEXT-deferredOperation-parameter
If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle
VUID-vkCopyMicromapEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMicromapInfoEXT structure
VUID-vkCopyMicromapEXT-deferredOperation-parent
If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS
VK_OPERATION_DEFERRED_KHR
VK_OPERATION_NOT_DEFERRED_KHR

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy host accessible memory to a micromap, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMemoryToMicromapEXT(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyMemoryToMicromapInfoEXT*        pInfo);

device is the device which owns pInfo->dst.
deferredOperation is an optional VkDeferredOperationKHR to request deferral for this command.
pInfo is a pointer to a VkCopyMemoryToMicromapInfoEXT structure defining the copy operation.

This command fulfills the same task as vkCmdCopyMemoryToMicromapEXT but is executed by the host.

This command can accept micromaps produced by either vkCmdCopyMicromapToMemoryEXT or vkCopyMicromapToMemoryEXT.

Valid Usage

VUID-vkCopyMemoryToMicromapEXT-deferredOperation-03678
Any previous deferred operation that was associated with deferredOperation must be complete
VUID-vkCopyMemoryToMicromapEXT-pInfo-07563
pInfo->src.hostAddress must be a valid host pointer
VUID-vkCopyMemoryToMicromapEXT-pInfo-07564
pInfo->src.hostAddress must be aligned to 16 bytes
VUID-vkCopyMemoryToMicromapEXT-buffer-07565
The buffer used to create pInfo->dst must be bound to host-visible device memory
VUID-vkCopyMemoryToMicromapEXT-micromapHostCommands-07566
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapHostCommands feature must be enabled
VUID-vkCopyMemoryToMicromapEXT-buffer-07567
The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

VUID-vkCopyMemoryToMicromapEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkCopyMemoryToMicromapEXT-deferredOperation-parameter
If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle
VUID-vkCopyMemoryToMicromapEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMemoryToMicromapInfoEXT structure
VUID-vkCopyMemoryToMicromapEXT-deferredOperation-parent
If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS
VK_OPERATION_DEFERRED_KHR
VK_OPERATION_NOT_DEFERRED_KHR

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

To copy a micromap to host accessible memory, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkCopyMicromapToMemoryEXT(
    VkDevice                                    device,
    VkDeferredOperationKHR                      deferredOperation,
    const VkCopyMicromapToMemoryInfoEXT*        pInfo);

device is the device which owns pInfo->src.
deferredOperation is an optional VkDeferredOperationKHR to request deferral for this command.
pInfo is a pointer to a VkCopyMicromapToMemoryInfoEXT structure defining the copy operation.

This command fulfills the same task as vkCmdCopyMicromapToMemoryEXT but is executed by the host.

This command produces the same results as vkCmdCopyMicromapToMemoryEXT, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToMicromapEXT or vkCopyMemoryToMicromapEXT.

Valid Usage

VUID-vkCopyMicromapToMemoryEXT-deferredOperation-03678
Any previous deferred operation that was associated with deferredOperation must be complete
VUID-vkCopyMicromapToMemoryEXT-buffer-07568
The buffer used to create pInfo->src must be bound to host-visible device memory
VUID-vkCopyMicromapToMemoryEXT-pInfo-07569
pInfo->dst.hostAddress must be a valid host pointer
VUID-vkCopyMicromapToMemoryEXT-pInfo-07570
pInfo->dst.hostAddress must be aligned to 16 bytes
VUID-vkCopyMicromapToMemoryEXT-micromapHostCommands-07571
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapHostCommands feature must be enabled
VUID-vkCopyMicromapToMemoryEXT-buffer-07572
The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

VUID-vkCopyMicromapToMemoryEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkCopyMicromapToMemoryEXT-deferredOperation-parameter
If deferredOperation is not VK_NULL_HANDLE, deferredOperation must be a valid VkDeferredOperationKHR handle
VUID-vkCopyMicromapToMemoryEXT-pInfo-parameter
pInfo must be a valid pointer to a valid VkCopyMicromapToMemoryInfoEXT structure
VUID-vkCopyMicromapToMemoryEXT-deferredOperation-parent
If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS
VK_OPERATION_DEFERRED_KHR
VK_OPERATION_NOT_DEFERRED_KHR

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

To query micromap size parameters on the host, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkWriteMicromapsPropertiesEXT(
    VkDevice                                    device,
    uint32_t                                    micromapCount,
    const VkMicromapEXT*                        pMicromaps,
    VkQueryType                                 queryType,
    size_t                                      dataSize,
    void*                                       pData,
    size_t                                      stride);

device is the device which owns the micromaps in pMicromaps.
micromapCount is the count of micromaps for which to query the property.
pMicromaps is a pointer to an array of existing previously built micromaps.
queryType is a VkQueryType value specifying the property to be queried.
dataSize is the size in bytes of the buffer pointed to by pData.
pData is a pointer to a user-allocated buffer where the results will be written.
stride is the stride in bytes between results for individual queries within pData.

This command fulfills the same task as vkCmdWriteMicromapsPropertiesEXT but is executed by the host.

Valid Usage

VUID-vkWriteMicromapsPropertiesEXT-pMicromaps-07501
All micromaps in pMicromaps must have been constructed prior to the execution of this command
VUID-vkWriteMicromapsPropertiesEXT-pMicromaps-07502
All micromaps in pMicromaps must have been constructed with VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT if queryType is VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT
VUID-vkWriteMicromapsPropertiesEXT-queryType-07503
queryType must be VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT or VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT
VUID-vkWriteMicromapsPropertiesEXT-queryType-07573
If queryType is VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then stride must be a multiple of the size of VkDeviceSize
VUID-vkWriteMicromapsPropertiesEXT-queryType-07574
If queryType is VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then pData must point to a VkDeviceSize
VUID-vkWriteMicromapsPropertiesEXT-queryType-07575
If queryType is
VUID-vkWriteMicromapsPropertiesEXT-dataSize-07576
dataSize must be greater than or equal to micromapCount*stride
VUID-vkWriteMicromapsPropertiesEXT-buffer-07577
The buffer used to create each micromap in pMicromaps must be bound to host-visible device memory
VUID-vkWriteMicromapsPropertiesEXT-micromapHostCommands-07578
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapHostCommands feature must be enabled
VUID-vkWriteMicromapsPropertiesEXT-buffer-07579
The buffer used to create each micromap in pMicromaps must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

VUID-vkWriteMicromapsPropertiesEXT-device-parameter
device must be a valid VkDevice handle
VUID-vkWriteMicromapsPropertiesEXT-pMicromaps-parameter
pMicromaps must be a valid pointer to an array of micromapCount valid VkMicromapEXT handles
VUID-vkWriteMicromapsPropertiesEXT-queryType-parameter
queryType must be a valid VkQueryType value
VUID-vkWriteMicromapsPropertiesEXT-pData-parameter
pData must be a valid pointer to an array of dataSize bytes
VUID-vkWriteMicromapsPropertiesEXT-micromapCount-arraylength
micromapCount must be greater than 0
VUID-vkWriteMicromapsPropertiesEXT-dataSize-arraylength
dataSize must be greater than 0
VUID-vkWriteMicromapsPropertiesEXT-pMicromaps-parent
Each element of pMicromaps must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY