C Specification

To build an acceleration structure call:

// Provided by VK_NV_ray_tracing
void vkCmdBuildAccelerationStructureNV(
    VkCommandBuffer                             commandBuffer,
    const VkAccelerationStructureInfoNV*        pInfo,
    VkBuffer                                    instanceData,
    VkDeviceSize                                instanceOffset,
    VkBool32                                    update,
    VkAccelerationStructureNV                   dst,
    VkAccelerationStructureNV                   src,
    VkBuffer                                    scratch,
    VkDeviceSize                                scratchOffset);

Parameters

  • 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.

Description

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
Valid Usage (Implicit)

  • VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-pInfo-parameter
    pInfo must be a valid pointer to a valid VkAccelerationStructureInfoNV structure

  • VUID-vkCmdBuildAccelerationStructureNV-instanceData-parameter
    If instanceData is not VK_NULL_HANDLE, instanceData must be a valid VkBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-dst-parameter
    dst must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdBuildAccelerationStructureNV-src-parameter
    If src is not VK_NULL_HANDLE, src must be a valid VkAccelerationStructureNV handle

  • VUID-vkCmdBuildAccelerationStructureNV-scratch-parameter
    scratch must be a valid VkBuffer handle

  • VUID-vkCmdBuildAccelerationStructureNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • 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

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Compute

Action

See Also

VK_NV_ray_tracing, VkAccelerationStructureInfoNV, VkAccelerationStructureNV, VkBool32, VkBuffer, VkCommandBuffer, VkDeviceSize

Document Notes

For more information, see the Vulkan Specification

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

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0