VkAccelerationStructureInstanceKHR

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:

typedef struct VkAccelerationStructureInstanceKHR {
    // The bitfields in this structure are non-normative since bitfield ordering is implementation-defined in C. The specification defines the normative layout.;
    VkTransformMatrixKHR transform;
    uint32_t instanceCustomIndex:24;
    uint32_t mask:8;
    uint32_t instanceShaderBindingTableRecordOffset:24;
    VkGeometryInstanceFlagsKHR flags:8;
    uint64_t accelerationStructureReference;
} VkAccelerationStructureInstanceKHR;

or the equivalent

typedef VkAccelerationStructureInstanceKHR VkAccelerationStructureInstanceNV;

• transform is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure.
• instanceCustomIndex is a 24-bit application-specified index value accessible to ray shaders in the InstanceCustomIndexKHR built-in.
• mask is an 8-bit visibility mask for the geometry. The instance may only be hit if Cull 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 device address containing a bottom level cluster acceleration structure built using vkCmdBuildClusterAccelerationStructureIndirectNV
  • a VkAccelerationStructureKHR object (used by host operations which reference acceleration structures).

The C language specification does not define the ordering of bit-fields, but in practice, this structure produces the correct layout with existing compilers. The intended bit pattern is for the following:

• instanceCustomIndex and mask occupy the same memory as if a single uint32_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 and flags occupy the same memory as if a single uint32_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.