Function Prototype

vkCreateAccelerationStructureKHR

Create a new acceleration structure object

To create an acceleration structure, call:

VkResult vkCreateAccelerationStructureKHR(
    VkDevice                                           device,
    const VkAccelerationStructureCreateInfoKHR*        pCreateInfo,
    const VkAllocationCallbacks*       pAllocator,
    VkAccelerationStructureKHR*                        pAccelerationStructure);
  • device is the logical device that creates the acceleration structure object.
  • pCreateInfo is a pointer to a VkAccelerationStructureCreateInfoKHR structure containing parameters affecting creation of the acceleration structure.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.
  • pAccelerationStructure is a pointer to a VkAccelerationStructureKHR handle in which the resulting acceleration structure object is returned.

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

The acceleration structure data is stored in the object referred to by VkAccelerationStructureCreateInfoKHR::buffer. Once memory has been bound to that buffer, it must be populated by acceleration structure build or acceleration structure copy commands such as vkCmdBuildAccelerationStructuresKHR, vkBuildAccelerationStructuresKHR, vkCmdCopyAccelerationStructureKHR, and vkCopyAccelerationStructureKHR.

The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the acceleration structure data using acceleration structure copy commands. During capture the tool will use vkCopyAccelerationStructureToMemoryKHR or vkCmdCopyAccelerationStructureToMemoryKHR with a mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR, and vkCopyMemoryToAccelerationStructureKHR or vkCmdCopyMemoryToAccelerationStructureKHR with a mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR during replay.

Memory does not need to be bound to the underlying buffer when vkCreateAccelerationStructureKHR is called.

The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures 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 ray traversal.

Valid Usage (Implicit)

VUID-vkCreateAccelerationStructureKHR-pAllocator-parameter

If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure