Structures

VkAccelerationStructureCreateInfoKHR

Structure specifying the parameters of a newly created acceleration structure object

The VkAccelerationStructureCreateInfoKHR structure is defined as:

typedef struct VkAccelerationStructureCreateInfoKHR {
    VkStructureType sType;
    const void* pNext;
    VkAccelerationStructureCreateFlagsKHR createFlags;
    VkBuffer buffer;
    VkDeviceSize offset;
    VkDeviceSize size;
    VkAccelerationStructureTypeKHR type;
    VkDeviceAddress deviceAddress;
} VkAccelerationStructureCreateInfoKHR;
  • sType is a VkStructureType value identifying this structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • createFlags is a bitmask of VkAccelerationStructureCreateFlagBitsKHR specifying additional creation parameters of the acceleration structure.
  • buffer is the buffer on which the acceleration structure will be stored.
  • offset is an offset in bytes from the base address of the buffer at which the acceleration structure will be stored, and must be a multiple of 256.
  • size is the size required for the acceleration structure.
  • type is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure that will be created.
  • deviceAddress is the device address requested for the acceleration structure if the accelerationStructureCaptureReplay feature is being used. If deviceAddress is zero, no specific address is requested.

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

The expected usage for this is that a trace capture/replay tool will add the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as storage for an acceleration structure where deviceAddress is not zero. This also means that the tool will need to add VK_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 VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.

Applications should create an acceleration structure with a specific VkAccelerationStructureTypeKHR other than VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.

VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is intended to be used by API translation layers. This can be used at acceleration structure creation time in cases where the actual acceleration structure type (top or bottom) is not yet known. The actual acceleration structure type must be specified as VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR when the build is performed.

If the acceleration structure will be the target of a build operation, the required size for an acceleration structure can be queried with vkGetAccelerationStructureBuildSizesKHR. If the acceleration structure is going to be the target of a compacting copy, vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR can be used to obtain the compacted size required.

If the acceleration structure will be the target of a build operation with VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must include VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in createFlags and include VkAccelerationStructureMotionInfoNV as an extension structure in pNext with the number of instances as metadata for the object.

Valid Usage

VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612

If deviceAddress is not zero, createFlags must include VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR

VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09488

If deviceAddress is not zero, it must have been retrieved from an identically created acceleration structure, except for buffer and deviceAddress

VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09489

If deviceAddress is not zero, buffer must have been created identically to the buffer used to create the acceleration structure from which deviceAddress was retrieved, except for VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress

VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09490

If deviceAddress is not zero, buffer must have been created with a VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress that was retrieved from vkGetBufferOpaqueCaptureAddress for the buffer that was used to create the acceleration structure from which deviceAddress was retrieved

VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613

If createFlags includes VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureCaptureReplaymust be VK_TRUE

VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614

buffer must have been created with a usage value containing VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR

VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615

buffer must not have been created with VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT

VUID-VkAccelerationStructureCreateInfoKHR-offset-03616

The sum of offset and size must be less than the size of buffer

VUID-VkAccelerationStructureCreateInfoKHR-offset-03734

offset must be a multiple of 256 bytes

VUID-VkAccelerationStructureCreateInfoKHR-createFlags-04954

If VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV is set in createFlags and type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, one member of the pNext chain must be a pointer to a valid instance of VkAccelerationStructureMotionInfoNV

VUID-VkAccelerationStructureCreateInfoKHR-createFlags-04955

If any geometry includes VkAccelerationStructureGeometryMotionTrianglesDataNV then createFlags must contain VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV

VUID-VkAccelerationStructureCreateInfoKHR-createFlags-08108

If createFlags includes VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled

VUID-VkAccelerationStructureCreateInfoKHR-pNext-08109

If the pNext chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, createFlags must contain VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

Valid Usage (Implicit)

VUID-VkAccelerationStructureCreateInfoKHR-sType-sType

sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR

VUID-VkAccelerationStructureCreateInfoKHR-pNext-pNext

Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkAccelerationStructureMotionInfoNV or VkOpaqueCaptureDescriptorDataCreateInfoEXT

VUID-VkAccelerationStructureCreateInfoKHR-sType-unique

The sType value of each struct in the pNext chain must be unique