VkAccelerationStructureInstanceKHR(3)

# VkAccelerationStructureInstanceKHR(3) Manual Page

## Name

VkAccelerationStructureInstanceKHR - Structure specifying a single acceleration structure instance for building into an acceleration structure geometry

Loading... please wait.

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

    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

    typedef VkAccelerationStructureInstanceKHR VkAccelerationStructureInstanceNV;

## Members

- `transform` is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure.

- `instanceCustomIndex` a 24-bit user-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 `rayMask & 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 spec 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` and `mask` occupy the same memory as if a single `int32_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 `int32_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.

Valid Usage
Valid Usage (Implicit)

- `flags` must be a valid combination of VkGeometryInstanceFlagBitsKHR values

## See Also

VkGeometryInstanceFlagsKHR, VkTransformMatrixKHR

## 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.