C Specification
Acceleration structure instances can be built into top-level acceleration structures. Each acceleration structure instance is a separate entry in the top-level acceleration structure which includes all the geometry of a bottom-level acceleration structure at a transformed location. Multiple instances can point to the same bottom level acceleration structure.
An acceleration structure instance is defined by the structure:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureInstanceKHR {
VkTransformMatrixKHR transform;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureInstanceKHR;
or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAccelerationStructureInstanceKHR VkAccelerationStructureInstanceNV;
Members
-
transform
is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure. -
instanceCustomIndex
is a 24-bit user-specified index value accessible to ray shaders in theInstanceCustomIndexKHR
built-in. -
mask
is an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0
-
instanceShaderBindingTableRecordOffset
is a 24-bit offset used in calculating the hit shader binding table index. -
flags
is an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReference
is either:-
a device address containing the value obtained from vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV (used by device operations which reference acceleration structures) or,
-
a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).
-
Description
The C language specification does not define the ordering of bit-fields, but in practice, this struct produces the correct layout with existing compilers. The intended bit pattern is for the following:
-
instanceCustomIndex
andmask
occupy the same memory as if a singleuint32_t
was specified in their place-
instanceCustomIndex
occupies the 24 least significant bits of that memory -
mask
occupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffset
andflags
occupy the same memory as if a singleuint32_t
was specified in their place-
instanceShaderBindingTableRecordOffset
occupies the 24 least significant bits of that memory -
flags
occupies the 8 most significant bits of that memory
-
If a compiler produces code that diverges from that pattern, applications must employ another method to set values according to the correct bit pattern.
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.