Structures

VkAccelerationStructureBuildGeometryInfoKHR

Structure specifying the geometry data used to build an acceleration structure

The VkAccelerationStructureBuildGeometryInfoKHR structure is defined as:

typedef struct VkAccelerationStructureBuildGeometryInfoKHR {
    VkStructureType sType;
    const void* pNext;
    VkAccelerationStructureTypeKHR type;
    VkBuildAccelerationStructureFlagsKHR flags;
    VkBuildAccelerationStructureModeKHR mode;
    VkAccelerationStructureKHR srcAccelerationStructure;
    VkAccelerationStructureKHR dstAccelerationStructure;
    uint32_t geometryCount;
    const VkAccelerationStructureGeometryKHR* pGeometries;
    const VkAccelerationStructureGeometryKHR* const* ppGeometries;
    VkDeviceOrHostAddressKHR scratchData;
} VkAccelerationStructureBuildGeometryInfoKHR;

pub struct AccelerationStructureBuildGeometryInfoKHR {
    s_type: vk::StructureType,
    p_next: *const c_void,
    type: vk::AccelerationStructureTypeKHR,
    flags: vk::BuildAccelerationStructureFlagsKHR,
    mode: vk::BuildAccelerationStructureModeKHR,
    src_acceleration_structure: vk::AccelerationStructureKHR,
    dst_acceleration_structure: vk::AccelerationStructureKHR,
    geometry_count: u32,
    p_geometries: *const vk::AccelerationStructureGeometryKHR,
    pp_geometries: *const *const vk::AccelerationStructureGeometryKHR,
    scratch_data: vk::DeviceOrHostAddressKHR,
}

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
type is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built.
flags is a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure.
mode is a VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform.
srcAccelerationStructure is a pointer to an existing acceleration structure that is to be used to update the dstAccelerationStructure acceleration structure when mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR.
dstAccelerationStructure is a pointer to the target acceleration structure for the build.
geometryCount specifies the number of geometries that will be built into dstAccelerationStructure.
pGeometries is a pointer to an array of VkAccelerationStructureGeometryKHR structures.
ppGeometries is a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures.
scratchData is the device or host address of memory that will be used as scratch memory for the build.

Only one of pGeometries or ppGeometries can be a valid pointer, the other must be NULL. Each element of the non-NULL array describes the data used to build each acceleration structure geometry.

For bottom-level acceleration structures, the index of each element of the pGeometries or ppGeometries members of VkAccelerationStructureBuildGeometryInfoKHR is used as the geometry index during ray traversal. The geometry index is available in ray shaders via the RayGeometryIndexKHR built-in, and is used to determine hit and intersection shaders executed during traversal. The geometry index is available to ray queries via the OpRayQueryGetIntersectionGeometryIndexKHR instruction.

Setting VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in flags indicates that this build is a motion top level acceleration structure. A motion top level uses instances of format VkAccelerationStructureMotionInstanceNV if VkAccelerationStructureGeometryInstancesDataKHR::arrayOfPointers is VK_FALSE.

If VkAccelerationStructureGeometryInstancesDataKHR::arrayOfPointers is VK_TRUE, the pointer for each element of the array of instance pointers consists of 4 bits of VkAccelerationStructureMotionInstanceTypeNV in the low 4 bits of the pointer identifying the type of structure at the pointer. The device address accessed is the value in the array with the low 4 bits set to zero. The structure at the pointer is one of VkAccelerationStructureInstanceKHR, VkAccelerationStructureMatrixMotionInstanceNV or VkAccelerationStructureSRTMotionInstanceNV, depending on the type value encoded in the low 4 bits.

A top level acceleration structure with either motion instances or vertex motion in its instances must set VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in flags.

Members srcAccelerationStructure and dstAccelerationStructuremay be the same or different for an update operation (when mode is VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR). If they are the same, the update happens in-place. Otherwise, the target acceleration structure is updated and the source is not modified.

Valid Usage

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03654

type must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788

If geometryCount is not 0, exactly one of pGeometries or ppGeometries must be a valid pointer, the other must be NULL

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03789

If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, the geometryType member of elements of either pGeometries or ppGeometries must be VK_GEOMETRY_TYPE_INSTANCES_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03790

If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, geometryCount must be 1

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03791

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR the geometryType member of elements of either pGeometries or ppGeometries must not be VK_GEOMETRY_TYPE_INSTANCES_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03792

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then the geometryType member of each geometry in either pGeometries or ppGeometries must be the same

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03793

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then geometryCount must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxGeometryCount

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-10884

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the geometryType member of either pGeometries or ppGeometries is VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX, then geometryCount must be 1

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03794

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the geometryType member of either pGeometries or ppGeometries is VK_GEOMETRY_TYPE_AABBS_KHR, the total number of AABBs in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxPrimitiveCount

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03795

If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the geometryType member of either pGeometries or ppGeometries is VK_GEOMETRY_TYPE_TRIANGLES_KHR, the total number of triangles in all geometries must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxPrimitiveCount

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-03796

If flags has the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR bit set, then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR bit set

VUID-VkAccelerationStructureBuildGeometryInfoKHR-dstAccelerationStructure-04927

If dstAccelerationStructure was created with VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in VkAccelerationStructureCreateInfoKHR::createFlags, VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV must be set in flags

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04928

If VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in flags, dstAccelerationStructure must have been created with VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in VkAccelerationStructureCreateInfoKHR::createFlags

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04929

If VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in flags, type must not be VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11558

If flags has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR bit set then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT bit set

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11709

If flags has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT bit set, the VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromap feature must be enabled

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11710

If flags has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR bit set, the VkPhysicalDeviceOpacityMicromapFeaturesKHR::micromap or VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromap feature must be enabled

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11711

If flags has the VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_KHR bit set, the VkPhysicalDeviceOpacityMicromapFeaturesKHR::micromap or VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromap feature must be enabled

VUID-VkAccelerationStructureBuildGeometryInfoKHR-micromap-11559

If type is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the VkPhysicalDeviceOpacityMicromapFeaturesKHR::micromap feature must be enabled

VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryCount-11560

If type is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, geometryCount must be 1

VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryType-11561

If type is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the geometryType member of elements of either pGeometries or ppGeometries must be VK_GEOMETRY_TYPE_MICROMAP_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-geometryType-11707

If type is not VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, the geometryType member of elements of either pGeometries or ppGeometries must not be VK_GEOMETRY_TYPE_MICROMAP_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-11562

If type is VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR, flagsmust only include the following bits:

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR
VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-11563

If flags includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, typemust be VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-format-11712

If flags includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, each element of its pUsageCounts or ppUsageCounts members must have its format member equal to VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11564

If flags does not include VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, for each element of its pUsageCounts or ppUsageCounts members, if its format member is VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR, its subdivisionLevel member must be less than or equal to maxOpacity4StateSubdivisionLevel

VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11565

If flags includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, for each element of its pUsageCounts or ppUsageCounts members, its subdivisionLevel member must be less than or equal to maxOpacityLossy4StateSubdivisionLevel

VUID-VkAccelerationStructureBuildGeometryInfoKHR-format-11713

If flags includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, each element of its triangleArray member must have its format member equal to VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR

VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11566

If flags does not include VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, for each element of its triangleArray member, if its format member is VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR, its subdivisionLevel member must be less than or equal to maxOpacity4StateSubdivisionLevel

VUID-VkAccelerationStructureBuildGeometryInfoKHR-subdivisionLevel-11567

If flags includes VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR, for each element of pGeometries or ppGeometries, if it includes a VkAccelerationStructureGeometryMicromapDataKHR structure in its pNext chain, for each element of its triangleArray member, its subdivisionLevel member must be less than or equal to maxOpacityLossy4StateSubdivisionLevel

VK_KHR_acceleration_structure

Type