Function Prototype

vkCmdBuildAccelerationStructureNV

Build an acceleration structure
primary / secondary
outside
compute
action

To build an acceleration structure call:

void vkCmdBuildAccelerationStructureNV(
    VkCommandBuffer commandBuffer,
    const VkAccelerationStructureInfoNV* pInfo,
    VkBuffer instanceData,
    VkDeviceSize instanceOffset,
    VkBool32 update,
    VkAccelerationStructureNV dst,
    VkAccelerationStructureNV src,
    VkBuffer scratch,
    VkDeviceSize scratchOffset);
  • commandBuffer is the command buffer into which the command will be recorded.
  • pInfo contains the shared information for the acceleration structure’s structure.
  • instanceData is the buffer containing an array of VkAccelerationStructureInstanceKHR structures defining acceleration structures. This parameter must be NULL for bottom level acceleration structures.
  • instanceOffset is the offset in bytes (relative to the start of instanceData) at which the instance data is located.
  • update specifies whether to update the dst acceleration structure with the data in src.
  • dst is a pointer to the target acceleration structure for the build.
  • src is a pointer to an existing acceleration structure that is to be used to update the dst acceleration structure.
  • scratch is the VkBuffer that will be used as scratch memory for the build.
  • scratchOffset is the offset in bytes relative to the start of scratch that will be used as a scratch memory.

Accesses to dst, src, and scratch must be synchronized with the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR

pipeline stage and an access type of VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.

Valid Usage

VUID-vkCmdBuildAccelerationStructureNV-dst-02488

dst must have been created with compatible VkAccelerationStructureInfoNV where VkAccelerationStructureInfoNV::type and VkAccelerationStructureInfoNV::flags are identical, VkAccelerationStructureInfoNV::instanceCount and VkAccelerationStructureInfoNV::geometryCount for dst are greater than or equal to the build size and each geometry in VkAccelerationStructureInfoNV::pGeometries for dst has greater than or equal to the number of vertices, indices, and AABBs

VUID-vkCmdBuildAccelerationStructureNV-update-02490

If update is VK_TRUE, src must have previously been constructed with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in VkAccelerationStructureInfoNV::flags in the original build

VUID-vkCmdBuildAccelerationStructureNV-update-02491

If update is VK_FALSE, the size member of the VkMemoryRequirements structure returned from a call to vkGetAccelerationStructureMemoryRequirementsNV with VkAccelerationStructureMemoryRequirementsInfoNV::accelerationStructure set to dst and VkAccelerationStructureMemoryRequirementsInfoNV::type set to VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NVmust be less than or equal to the size of scratch minus scratchOffset

VUID-vkCmdBuildAccelerationStructureNV-update-02492

If update is VK_TRUE, the size member of the VkMemoryRequirements structure returned from a call to vkGetAccelerationStructureMemoryRequirementsNV with VkAccelerationStructureMemoryRequirementsInfoNV::accelerationStructure set to dst and VkAccelerationStructureMemoryRequirementsInfoNV::type set to VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NVmust be less than or equal to the size of scratch minus scratchOffset

VUID-vkCmdBuildAccelerationStructureNV-scratch-03522

scratch must have been created with VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag

VUID-vkCmdBuildAccelerationStructureNV-instanceData-03523

If instanceData is not VK_NULL_HANDLE, instanceDatamust have been created with VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag

VUID-vkCmdBuildAccelerationStructureNV-accelerationStructureReference-03786

Each VkAccelerationStructureInstanceKHR::accelerationStructureReference value in instanceData must be a valid device address containing a value obtained from vkGetAccelerationStructureHandleNV

VUID-vkCmdBuildAccelerationStructureNV-update-03524

If update is VK_TRUE, then objects that were previously active must not be made inactive as per Inactive Primitives and Instances

VUID-vkCmdBuildAccelerationStructureNV-update-03525

If update is VK_TRUE, then objects that were previously inactive must not be made active as per Inactive Primitives and Instances

VUID-vkCmdBuildAccelerationStructureNV-update-03526

If update is VK_TRUE, the src and dst objects must either be the same object or not have any memory aliasing

VUID-vkCmdBuildAccelerationStructureNV-dst-07787

dst must be bound completely and contiguously to a single VkDeviceMemory object via vkBindAccelerationStructureMemoryNV

Valid Usage (Implicit)

VUID-vkCmdBuildAccelerationStructureNV-instanceData-parameter

If instanceData is not VK_NULL_HANDLE, instanceData must be a valid VkBuffer handle

VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support compute operations

VUID-vkCmdBuildAccelerationStructureNV-renderpass

This command must only be called outside of a render pass instance

VUID-vkCmdBuildAccelerationStructureNV-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdBuildAccelerationStructureNV-commonparent

Each of commandBuffer, dst, instanceData, scratch, and src that are valid handles of non-ignored parameters 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 ::