vkCreateMicromapEXT - Create a new micromap object

Description

Similar to other objects in Vulkan, the micromap creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into a micromap is determined by the parameters of MicromapCreateInfoEXT.

The micromap data is stored in the object referred to by MicromapCreateInfoEXT::buffer. Once memory has been bound to that buffer, it must be populated by micromap build or micromap copy commands such as cmdBuildMicromapsEXT, buildMicromapsEXT, cmdCopyMicromapEXT, and copyMicromapEXT.

Note

The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the micromap data using micromap copy commands. During capture the tool will use copyMicromapToMemoryEXT or cmdCopyMicromapToMemoryEXT with a mode of COPY_MICROMAP_MODE_SERIALIZE_EXT, and copyMemoryToMicromapEXT or cmdCopyMemoryToMicromapEXT with a mode of COPY_MICROMAP_MODE_DESERIALIZE_EXT during replay.

The input buffers passed to micromap build commands will be referenced by the implementation for the duration of the command. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure.

Valid Usage

• The micromap feature must be enabled

• If MicromapCreateInfoEXT::deviceAddress is not zero, the micromapCaptureReplay feature must be enabled
• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid MicromapCreateInfoEXT structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pMicromap must be a valid pointer to a MicromapEXT handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

See Also

VK_EXT_opacity_micromap, AllocationCallbacks, Device, MicromapCreateInfoEXT, MicromapEXT

A convenience wrapper to make a compatible pair of calls to createMicromapEXT and destroyMicromapEXT

To ensure that destroyMicromapEXT is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkCmdBuildMicromapsEXT - Build a micromap

Description

The cmdBuildMicromapsEXT 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 MicromapBuildInfoEXT::scratchData buffer device addresses must be synchronized with the PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of (ACCESS_2_MICROMAP_READ_BIT_EXT | ACCESS_2_MICROMAP_WRITE_BIT_EXT). Accesses to MicromapBuildInfoEXT::dstMicromap must be synchronized with the PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of ACCESS_2_MICROMAP_WRITE_BIT_EXT.

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

Valid Usage

• For each pInfos[i], dstMicromap must have been created with a value of MicromapCreateInfoEXT::size greater than or equal to the memory size required by the build operation, as returned by getMicromapBuildSizesEXT with pBuildInfo = pInfos[i]

• The mode member of each element of pInfos must be a valid BuildMicromapModeEXT value
• The dstMicromap member of any element of pInfos must be a valid MicromapEXT handle
• For each element of pInfos its type member must match the value of MicromapCreateInfoEXT::type when its dstMicromap was created
• 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
• 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
• 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
• For each element of pInfos, the buffer used to create its dstMicromap member must be bound to device memory
• If pInfos[i].mode is 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 MicromapBuildSizesInfoEXT structure returned from a call to getMicromapBuildSizesEXT with an identical MicromapBuildInfoEXT structure and primitive count
• 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 BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT usage flag
• 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 BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag
• For each element of pInfos, its scratchData.deviceAddress, data.deviceAddress, and triangleArray.deviceAddress members must be valid device addresses obtained from getBufferDeviceAddress
• 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 DeviceMemory object
• For each element of pInfos, its scratchData.deviceAddress member must be a multiple of PhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment
• For each element of pInfos, its triangleArray.deviceAddress and data.deviceAddress members must be a multiple of 256

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfos must be a valid pointer to an array of infoCount valid MicromapBuildInfoEXT structures
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• infoCount must be greater than 0

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_EXT_opacity_micromap, CommandBuffer, MicromapBuildInfoEXT

vkBuildMicromapsEXT - Build a micromap on the host

Description

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

The buildMicromapsEXT 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

• For each pInfos[i], dstMicromap must have been created with a value of MicromapCreateInfoEXT::size greater than or equal to the memory size required by the build operation, as returned by getMicromapBuildSizesEXT with pBuildInfo = pInfos[i]

• The mode member of each element of pInfos must be a valid BuildMicromapModeEXT value
• The dstMicromap member of any element of pInfos must be a valid MicromapEXT handle
• For each element of pInfos its type member must match the value of MicromapCreateInfoEXT::type when its dstMicromap was created
• 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
• 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
• 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
• For each element of pInfos, the buffer used to create its dstMicromap member must be bound to host-visible device memory
• For each element of pInfos, all referenced addresses of pInfos[i].data.hostAddress must be valid host memory
• For each element of pInfos, all referenced addresses of pInfos[i].triangleArray.hostAddress must be valid host memory
• The ::micromapHostCommands feature must be enabled
• If pInfos[i].mode is 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 MicromapBuildSizesInfoEXT structure returned from a call to getMicromapBuildSizesEXT with an identical MicromapBuildInfoEXT structure and primitive count
• 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)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfos must be a valid pointer to an array of infoCount valid MicromapBuildInfoEXT structures
• infoCount must be greater than 0
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_EXT_opacity_micromap, DeferredOperationKHR, Device, MicromapBuildInfoEXT

vkDestroyMicromapEXT - Destroy a micromap object

Valid Usage

• All submitted commands that refer to micromap must have completed execution

• If AllocationCallbacks were provided when micromap was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when micromap was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If micromap is not NULL_HANDLE, micromap must be a valid MicromapEXT handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If micromap is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to micromap must be externally synchronized

See Also

VK_EXT_opacity_micromap, AllocationCallbacks, Device, MicromapEXT

vkCmdCopyMicromapEXT - Copy a micromap

Description

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 PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT pipeline stage and an access type of ACCESS_2_MICROMAP_READ_BIT_EXT or ACCESS_2_MICROMAP_WRITE_BIT_EXT as appropriate.

Valid Usage

• The buffer used to create pInfo->src must be bound to device memory

• The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyMicromapInfoEXT structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• 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 CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

VK_EXT_opacity_micromap, CommandBuffer, CopyMicromapInfoEXT

vkCopyMicromapEXT - Copy a micromap on the host

Description

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

Valid Usage

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object

• Any previous deferred operation that was associated with deferredOperation must be complete
• The buffer used to create pInfo->src must be bound to host-visible device memory
• The buffer used to create pInfo->dst must be bound to host-visible device memory
• The ::micromapHostCommands feature must be enabled
• The buffer used to create pInfo->src must be bound to memory that was not allocated with multiple instances
• The buffer used to create pInfo->dst must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyMicromapInfoEXT structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_EXT_opacity_micromap, CopyMicromapInfoEXT, DeferredOperationKHR, Device

vkCmdCopyMicromapToMemoryEXT - Copy a micromap to device memory

Description

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

This command produces the same results as copyMicromapToMemoryEXT, 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 cmdCopyMemoryToMicromapEXT or copyMemoryToMicromapEXT.

The defined header structure for the serialized data consists of:

• UUID_SIZE bytes of data matching PhysicalDeviceIDProperties::driverUUID
• UUID_SIZE bytes of data identifying the compatibility for comparison using getDeviceMicromapCompatibilityEXT The serialized data is written to the buffer (or read from the buffer) according to the host endianness.

Valid Usage

• pInfo->dst.deviceAddress must be a valid device address for a buffer bound to device memory

• pInfo->dst.deviceAddress must be aligned to 256 bytes
• If the buffer pointed to by pInfo->dst.deviceAddress is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer used to create pInfo->src must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyMicromapToMemoryInfoEXT structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• 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 CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

VK_EXT_opacity_micromap, CommandBuffer, CopyMicromapToMemoryInfoEXT

vkCopyMicromapToMemoryEXT - Serialize a micromap on the host

Description

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

This command produces the same results as cmdCopyMicromapToMemoryEXT, 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 cmdCopyMemoryToMicromapEXT or copyMemoryToMicromapEXT.

Valid Usage

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object

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

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyMicromapToMemoryInfoEXT structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_EXT_opacity_micromap, CopyMicromapToMemoryInfoEXT, DeferredOperationKHR, Device

vkCmdCopyMemoryToMicromapEXT - Copy device memory to a micromap

Description

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

This command can accept micromaps produced by either cmdCopyMicromapToMemoryEXT or copyMicromapToMemoryEXT.

Valid Usage

• pInfo->src.deviceAddress must be a valid device address for a buffer bound to device memory

• pInfo->src.deviceAddress must be aligned to 256 bytes
• If the buffer pointed to by pInfo->src.deviceAddress is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer used to create pInfo->dst must be bound to device memory

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyMemoryToMicromapInfoEXT structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• 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 CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

VK_EXT_opacity_micromap, CommandBuffer, CopyMemoryToMicromapInfoEXT

vkCopyMemoryToMicromapEXT - Deserialize a micromap on the host

Description

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

This command can accept micromaps produced by either cmdCopyMicromapToMemoryEXT or copyMicromapToMemoryEXT.

Valid Usage

• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object

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

Valid Usage (Implicit)

• device must be a valid Device handle

• If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle
• pInfo must be a valid pointer to a valid CopyMemoryToMicromapInfoEXT structure
• If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_EXT_opacity_micromap, CopyMemoryToMicromapInfoEXT, DeferredOperationKHR, Device

vkCmdWriteMicromapsPropertiesEXT - Write micromap result parameters to query results.

Description

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

• If queryType is QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then the value written out is the number of bytes required by a serialized micromap.
• If queryType is QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT, then the value written out is the number of bytes required by a compacted micromap.

Valid Usage

• queryPool must have been created with a queryType matching queryType

• The queries identified by queryPool and firstQuery must be unavailable
• The buffer used to create each micromap in pMicrmaps must be bound to device memory
• The sum of query plus micromapCount must be less than or equal to the number of queries in queryPool
• All micromaps in pMicromaps must have been constructed prior to the execution of this command
• All micromaps in pMicromaps must have been constructed with BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT if queryType is QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT
• queryType must be QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT or QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pMicromaps must be a valid pointer to an array of micromapCount valid MicromapEXT handles
• queryType must be a valid QueryType value
• queryPool must be a valid QueryPool handle
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• micromapCount must be greater than 0
• Each of commandBuffer, queryPool, and the elements of pMicromaps must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

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

Command Properties

'

See Also

VK_EXT_opacity_micromap, CommandBuffer, MicromapEXT, QueryPool, QueryType

vkWriteMicromapsPropertiesEXT - Query micromap meta-data on the host

Description

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

Valid Usage

• All micromaps in pMicromaps must have been constructed prior to the execution of this command

• All micromaps in pMicromaps must have been constructed with BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT if queryType is QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT
• queryType must be QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT or QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT
• If queryType is QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then pData must point to a DeviceSize
• If queryType is
• dataSize must be greater than or equal to micromapCount*stride
• The buffer used to create each micromap in pMicromaps must be bound to host-visible device memory
• The ::micromapHostCommands feature must be enabled
• The buffer used to create each micromap in pMicromaps must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• pMicromaps must be a valid pointer to an array of micromapCount valid MicromapEXT handles
• queryType must be a valid QueryType value
• pData must be a valid pointer to an array of dataSize bytes
• micromapCount must be greater than 0
• dataSize must be greater than 0
• Each element of pMicromaps must have been created, allocated, or retrieved from device

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_EXT_opacity_micromap, Device, MicromapEXT, QueryType

vkGetDeviceMicromapCompatibilityEXT - Check if a serialized micromap is compatible with the current device

Valid Usage

• The micromap feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pVersionInfo must be a valid pointer to a valid MicromapVersionInfoEXT structure
• pCompatibility must be a valid pointer to a AccelerationStructureCompatibilityKHR value

See Also

VK_EXT_opacity_micromap, AccelerationStructureCompatibilityKHR, Device, MicromapVersionInfoEXT

vkGetMicromapBuildSizesEXT - Retrieve the required size for a micromap

Description

The dstMicromap and mode members of pBuildInfo are ignored. Any DeviceOrHostAddressKHR members of pBuildInfo are ignored by this command.

A micromap created with the micromapSize returned by this command supports any build with a MicromapBuildInfoEXT structure subject to the following properties:

• The build command is a host build command, and buildType is ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
• The build command is a device build command, and buildType is ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR

• For MicromapBuildInfoEXT:

  • Its type, and flags members are equal to pBuildInfo->type and pBuildInfo->flags, respectively.
  • The sum of usage information in either pUsageCounts or ppUsageCounts is equal to the sum of usage information in either pBuildInfo->pUsageCounts or pBuildInfo->ppUsageCounts.

Similarly, the buildScratchSize value will support any build command specifying the BUILD_MICROMAP_MODE_BUILD_EXT mode under the above conditions.

Valid Usage

• MicromapBuildInfoEXT::dstMicromap must have been created from device

• The micromap feature must be enabled
• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• buildType must be a valid AccelerationStructureBuildTypeKHR value
• pBuildInfo must be a valid pointer to a valid MicromapBuildInfoEXT structure
• pSizeInfo must be a valid pointer to a MicromapBuildSizesInfoEXT structure

See Also

VK_EXT_opacity_micromap, AccelerationStructureBuildTypeKHR, Device, MicromapBuildInfoEXT, MicromapBuildSizesInfoEXT

VkMicromapBuildInfoEXT - Structure specifying the data used to build a micromap

Description

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 MicromapTriangleEXT to match this pattern.

For opacity micromaps, the data at data is packed as either one bit per element for OPACITY_MICROMAP_FORMAT_2_STATE_EXT or two bits per element for 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.

For displacement micromaps, the data at data is interpreted as discussed in Displacement Micromap Encoding.

Valid Usage

• Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL

• If type is MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of MicromapUsageEXT must be a valid value from OpacityMicromapFormatEXT
• If type is MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of MicromapTriangleEXT must be a valid value from OpacityMicromapFormatEXT
• If type is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the format member of MicromapUsageEXT must be a valid value from DisplacementMicromapFormatNV
• If type is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the format member of MicromapTriangleEXT must be a valid value from DisplacementMicromapFormatNV

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT

• pNext must be NULL
• type must be a valid MicromapTypeEXT value
• flags must be a valid combination of BuildMicromapFlagBitsEXT values
• If usageCountsCount is not 0, and pUsageCounts is not NULL, pUsageCounts must be a valid pointer to an array of usageCountsCount MicromapUsageEXT structures
• If usageCountsCount is not 0, and ppUsageCounts is not NULL, ppUsageCounts must be a valid pointer to an array of usageCountsCount valid pointers to MicromapUsageEXT structures

See Also

VK_EXT_opacity_micromap, BuildMicromapFlagsEXT, BuildMicromapModeEXT, DeviceOrHostAddressConstKHR, DeviceOrHostAddressKHR, DeviceSize, MicromapEXT, MicromapTypeEXT, MicromapUsageEXT, StructureType, buildMicromapsEXT, cmdBuildMicromapsEXT, getMicromapBuildSizesEXT

VkMicromapCreateInfoEXT - Structure specifying the parameters of a newly created micromap object

Description

If deviceAddress is zero, no specific address is requested.

If deviceAddress is not zero, deviceAddress must be an address retrieved from an identically created micromap on the same implementation. The micromap must also be placed on an identically created buffer and at the same offset.

Applications should avoid creating micromaps with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors.

Note

The expected usage for this is that a trace capture/replay tool will add the BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as storage for a micromap where deviceAddress is not zero. This also means that the tool will need to add MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow the flag to be set where the application may not have otherwise required it. During capture the tool will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid.

Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Apps/tools should avoid mixing app-provided and implementation-provided addresses for buffers created with BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.

If the micromap will be the target of a build operation, the required size for a micromap can be queried with getMicromapBuildSizesEXT.

Valid Usage

• If deviceAddress is not zero, createFlags must include MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT

• If createFlags includes MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT, PhysicalDeviceOpacityMicromapFeaturesEXT::micromapCaptureReplay must be TRUE
• buffer must have been created with a usage value containing BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT
• buffer must not have been created with BUFFER_CREATE_SPARSE_RESIDENCY_BIT
• The sum of offset and size must be less than the size of buffer
• offset must be a multiple of 256 bytes

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT

• pNext must be NULL
• createFlags must be a valid combination of MicromapCreateFlagBitsEXT values
• buffer must be a valid Buffer handle
• type must be a valid MicromapTypeEXT value

See Also

VK_EXT_opacity_micromap, Buffer, DeviceAddress, DeviceSize, MicromapCreateFlagsEXT, MicromapTypeEXT, StructureType, createMicromapEXT

VkMicromapVersionInfoEXT - Micromap version information

Description

Note

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

Valid Usage (Implicit)

See Also

VK_EXT_opacity_micromap, StructureType, getDeviceMicromapCompatibilityEXT

VkCopyMicromapInfoEXT - Parameters for copying a micromap

Valid Usage

• mode must be COPY_MICROMAP_MODE_COMPACT_EXT or COPY_MICROMAP_MODE_CLONE_EXT

• The source acceleration structure src must have been constructed prior to the execution of this command
• If mode is COPY_MICROMAP_MODE_COMPACT_EXT, src must have been constructed with BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT in the build
• The buffer used to create src must be bound to device memory
• The buffer used to create dst must be bound to device memory

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_MICROMAP_INFO_EXT

• pNext must be NULL
• src must be a valid MicromapEXT handle
• dst must be a valid MicromapEXT handle
• mode must be a valid CopyMicromapModeEXT value
• Both of dst, and src must have been created, allocated, or retrieved from the same Device

See Also

VK_EXT_opacity_micromap, CopyMicromapModeEXT, MicromapEXT, StructureType, cmdCopyMicromapEXT, copyMicromapEXT

VkCopyMicromapToMemoryInfoEXT - Parameters for serializing a micromap

Valid Usage

• The source micromap src must have been constructed prior to the execution of this command

• The memory pointed to by dst must be at least as large as the serialization size of src, as reported by writeMicromapsPropertiesEXT or cmdWriteMicromapsPropertiesEXT with a query type of QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT
• mode must be COPY_MICROMAP_MODE_SERIALIZE_EXT

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_MICROMAP_TO_MEMORY_INFO_EXT

• pNext must be NULL
• src must be a valid MicromapEXT handle
• mode must be a valid CopyMicromapModeEXT value

See Also

VK_EXT_opacity_micromap, CopyMicromapModeEXT, DeviceOrHostAddressKHR, MicromapEXT, StructureType, cmdCopyMicromapToMemoryEXT, copyMicromapToMemoryEXT

VkCopyMemoryToMicromapInfoEXT - Parameters for deserializing a micromap

Valid Usage

• The source memory pointed to by src must contain data previously serialized using cmdCopyMicromapToMemoryEXT

• mode must be COPY_MICROMAP_MODE_DESERIALIZE_EXT
• The data in src must have a format compatible with the destination physical device as returned by getDeviceMicromapCompatibilityEXT
• dst must have been created with a size greater than or equal to that used to serialize the data in src

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COPY_MEMORY_TO_MICROMAP_INFO_EXT

• pNext must be NULL
• dst must be a valid MicromapEXT handle
• mode must be a valid CopyMicromapModeEXT value

See Also

VK_EXT_opacity_micromap, CopyMicromapModeEXT, DeviceOrHostAddressConstKHR, MicromapEXT, StructureType, cmdCopyMemoryToMicromapEXT, copyMemoryToMicromapEXT

VkMicromapBuildSizesInfoEXT - Structure specifying build sizes for a micromap

Valid Usage (Implicit)

See Also

VK_EXT_opacity_micromap, Bool32, DeviceSize, StructureType, getMicromapBuildSizesEXT

VkMicromapUsageEXT - Structure specifying the usage information used to build a micromap

Valid Usage

• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT then format must be OPACITY_MICROMAP_FORMAT_2_STATE_EXT or OPACITY_MICROMAP_FORMAT_4_STATE_EXT

• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is OPACITY_MICROMAP_FORMAT_2_STATE_EXT then subdivisionLevel must be less than or equal to PhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity2StateSubdivisionLevel
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is OPACITY_MICROMAP_FORMAT_4_STATE_EXT then subdivisionLevel must be less than or equal to PhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity4StateSubdivisionLevel
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then format must be DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then subdivisionLevel must be less than or equal to PhysicalDeviceDisplacementMicromapPropertiesNV::maxDisplacementMicromapSubdivisionLevel

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

See Also

VK_EXT_opacity_micromap, AccelerationStructureTrianglesDisplacementMicromapNV, AccelerationStructureTrianglesOpacityMicromapEXT, MicromapBuildInfoEXT

VkMicromapTriangleEXT - Structure specifying the micromap format and data for a triangle

Valid Usage

• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT then format must be OPACITY_MICROMAP_FORMAT_2_STATE_EXT or OPACITY_MICROMAP_FORMAT_4_STATE_EXT

• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is OPACITY_MICROMAP_FORMAT_2_STATE_EXT then subdivisionLevel must be less than or equal to PhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity2StateSubdivisionLevel
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_OPACITY_MICROMAP_EXT and format is OPACITY_MICROMAP_FORMAT_4_STATE_EXT then subdivisionLevel must be less than or equal to PhysicalDeviceOpacityMicromapPropertiesEXT::maxOpacity4StateSubdivisionLevel
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then format must be DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV
• If the MicromapTypeEXT of the micromap is MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then subdivisionLevel must be less than or equal to PhysicalDeviceDisplacementMicromapPropertiesNV::maxDisplacementMicromapSubdivisionLevel

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

See Also

VK_EXT_opacity_micromap

VkPhysicalDeviceOpacityMicromapFeaturesEXT - Structure describing the ray tracing opacity micromap features that can be supported by an implementation

Members

This structure describes the following feature:

Description

If the PhysicalDeviceOpacityMicromapFeaturesEXT structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceOpacityMicromapFeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_opacity_micromap, Bool32, StructureType

VkPhysicalDeviceOpacityMicromapPropertiesEXT - Structure describing the opacity micromap properties of a physical device

Description

If the PhysicalDeviceOpacityMicromapPropertiesEXT structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Valid Usage (Implicit)

See Also

VK_EXT_opacity_micromap, StructureType

VkAccelerationStructureTrianglesOpacityMicromapEXT - Structure specifying an opacity micromap in a bottom-level acceleration structure

Description

If AccelerationStructureTrianglesOpacityMicromapEXT is included in the pNext chain of a AccelerationStructureGeometryTrianglesDataKHR structure, that geometry will reference that micromap.

For each triangle in the geometry, the acceleration structure build fetches an index from indexBuffer using indexType and indexStride. If that value is the unsigned cast of one of the values from OpacityMicromapSpecialIndexEXT then that triangle behaves as described for that special value in Ray Opacity Micromap. Otherwise that triangle uses the opacity micromap information from micromap at that index plus baseTriangle.

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 count used to build this geometry. For a given format and subdivisionLevel the number of triangles in this geometry matching those values after indirection and special index handling must be equal to the sum of matching count provided.

If micromap is NULL_HANDLE, then every value read from indexBuffer must be one of the values in OpacityMicromapSpecialIndexEXT.

Valid Usage

• Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT

• indexType must be a valid IndexType value
• If usageCountsCount is not 0, and pUsageCounts is not NULL, pUsageCounts must be a valid pointer to an array of usageCountsCount MicromapUsageEXT structures
• If usageCountsCount is not 0, and ppUsageCounts is not NULL, ppUsageCounts must be a valid pointer to an array of usageCountsCount valid pointers to MicromapUsageEXT structures
• If micromap is not NULL_HANDLE, micromap must be a valid MicromapEXT handle

See Also

VK_EXT_opacity_micromap, DeviceOrHostAddressConstKHR, DeviceSize, IndexType, MicromapEXT, MicromapUsageEXT, StructureType

VkMicromapTypeEXT - Type of micromap

See Also

VK_EXT_opacity_micromap, MicromapBuildInfoEXT, MicromapCreateInfoEXT

VkBuildMicromapFlagBitsEXT - Bitmask specifying additional parameters for micromap builds

See Also

VK_EXT_opacity_micromap, BuildMicromapFlagsEXT