vkCmdBuildAccelerationStructureNV(3)

# vkCmdBuildAccelerationStructureNV(3) Manual Page

## Name

vkCmdBuildAccelerationStructureNV - Build an acceleration structure

Loading… please wait.

## 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

- VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241
  `geometryCount` must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::`maxGeometryCount`

- 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-02489
  If `update` is `VK_TRUE`, `src` must not be VK_NULL_HANDLE

- 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_NV` must 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_NV` must 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, `instanceData` must 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 https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#acceleration-structure-inactive-prims

- VUID-vkCmdBuildAccelerationStructureNV-update-03525
  If `update` is `VK_TRUE`, then objects that were previously inactive must not be made active as per https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#acceleration-structure-inactive-prims

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