Acceleration Structures
Acceleration Structures
Acceleration structures are data structures used by the implementation to efficiently manage scene geometry as it is traversed during a ray tracing query. The application is responsible for managing acceleration structure objects (see Acceleration Structures), including allocation, destruction, executing builds or updates, and synchronizing resources used during ray tracing queries.
There are two types of acceleration structures, top level acceleration structures and bottom level acceleration structures.
An acceleration structure is considered to be constructed if an acceleration structure build command or copy command has been executed with the given acceleration structure as the destination.
Geometry
Geometries refer to a triangle, sphere, linear swept sphere (LSS), or axis-aligned bounding box.
A triangle is a fundamental geometric primitive defined by three vertices in 3D space, forming a flat, planar surface.
An axis-aligned bounding box (AABB) is a rectangular box defined by two points (minimum and maximum corners) that encloses a 3D object or scene. Its faces are aligned with the coordinate axes, making intersection tests efficient for spatial partitioning and acceleration structures.
A sphere primitive is defined by a position and a radius.
The linear swept sphere (LSS) primitive is comprised of two sphere endcaps and a truncated cone midsection. The midsection is constructed so that it tangentially intersects with the endcaps. Two points, P0 and P1, and two radii, r0 and r1, fully describe the primitive.
The following figure shows an example of the LSS primitive composed of two sphere endcaps connected by a midsection. The solid non-dotted outline indicates the intersectable portion of the primitive.
Endcaps on LSS primitives are optional and are controlled by
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::endCapsMode.
The following figure shows an example of the LSS primitive without the
endcaps with only the midsection present.
A LSS geometry can be defined in multiple ways. If only the vertex and radius data are specified in VkAccelerationStructureGeometryLinearSweptSpheresDataNV without specifying the index data, LSS primitives are drawn in pairs of vertices. Each primitive i is defined by entries (i × 2, i × 2 + 1) in the vertex and radius buffers. For example, if a vertex buffer contains vertices A, B, C, D, E, F and G, (assuming each character represents a position vector) with corresponding radii as rA, rB, rC, rD, rE, rF and rG respectively, the LSS primitives drawn will be as shown below with G skipped because it does not have a corresponding vertex pair.
LSS primitives can be chained together by specifying an index buffer and indexing mode in the VkAccelerationStructureGeometryLinearSweptSpheresDataNV structure.
If the VkRayTracingLssIndexingModeNV::indexingMode is set to
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NV, then the consecutive pair of
indices in the index buffer select the vertices that define the LSS chain.
For example, assuming the same vertex buffer as before, if the index buffer
contains indices [6, 5, 5, 4, 4, 3, 2, 1], the LSS primitives will be
chained as shown:
Note that due to the lack of a [3, 2] pair, there is a break in the chain and D is not connected to C.
If the VkRayTracingLssIndexingModeNV::indexingMode is set to
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NV, then each LSS
primitive is defined by two successive positions and radii, (k, k
1), where k is a single index in the index buffer.
For example, if the index buffer contains indices [0, 1, 2, 4], the
LSS primitives will be chained as shown below.
Note that due to the absence of index 3 in the index buffer, there is a
break in the chain and D is not connected to E.
Top Level Acceleration Structures
Opaque acceleration structure for an array of instances. The descriptor or device address referencing this is the starting point for traversal.
The top level acceleration structure takes a reference to any bottom level acceleration structure referenced by its instances. Those bottom level acceleration structure objects must be valid when the top level acceleration structure is accessed.
Acceleration Structure Update Rules
The API defines two types of operations to produce acceleration structures from geometry:
-
A build operation is used to construct an acceleration structure.
-
An update operation is used to modify an existing acceleration structure.
An update operation imposes certain constraints on the input, in exchange for considerably faster execution. When performing an update, the application is required to provide a full description of the acceleration structure, but is prohibited from changing anything other than instance definitions, transform matrices, and vertex or AABB positions. All other aspects of the description must exactly match the one from the original build.
More precisely, the application must not use an update operation to do any of the following:
-
Change primitives or instances from active to inactive, or vice versa (as defined in Inactive Primitives and Instances).
-
Change the index or vertex formats of triangle geometry.
-
Change triangle geometry transform pointers from null to non-null or vice versa.
-
Change the number of geometries or instances in the structure.
-
Change the geometry flags for any geometry in the structure.
-
Change the number of vertices or primitives for any geometry in the structure.
If the original acceleration structure was built using opacity micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT
was set in flags, the application must provide the corresponding
micromap information to the update operation.
The application is prohibited from changing anything other than the specific
opacity values assigned to the triangles.
More precisely, the application must not use an update operation to do any of the following:
-
Remove micromaps or VkOpacityMicromapSpecialIndexEXT values from a geometry which previously had them, or vice versa.
-
Change between use of VkOpacityMicromapSpecialIndexEXT values and explicit micro-map triangles.
-
Change the subdivision level or format of the micromap triangle associated with any acceleration-structure triangle.
If the original acceleration structure was built using opacity micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT was
set in flags, the application must provide a micromap to the update
operation.
If the original acceleration structure was built using opacity micromaps and neither opacity micromap update flag is set the application must provide the original micromap to the update operation.
If the original acceleration structure was built using displacement
micromaps and
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV
was set in flags, the application must provide a displacement
micromap to the update operation.
If the original acceleration structure was built using displacement micromaps and the displacement micromap update flag is not set the application must provide the original micromap to the update operation.
Inactive Primitives and Instances
Acceleration structures allow the use of particular input values to signal inactive primitives or instances.
An inactive triangle is one for which the first (X) component of any vertex is NaN. If any other vertex component is NaN, and the first is not, the behavior is undefined. If the vertex format does not have a NaN representation, then all triangles are considered active.
An inactive instance is one whose acceleration structure reference is 0.
An inactive AABB is one for which the minimum X coordinate is NaN. If any other component is NaN, and the first is not, the behavior is undefined.
An inactive LSS or sphere is one where any of the radius or position component is NaN.
In the above definitions, “NaN” refers to any type of NaN. Signaling, non-signaling, quiet, loud, or otherwise.
An inactive object is considered invisible to all rays, and should not be represented in the acceleration structure. Implementations should ensure that the presence of inactive objects does not seriously degrade traversal performance.
Inactive objects are counted in the auto-generated index sequences which are
provided to shaders via InstanceId and PrimitiveId SPIR-V
decorations.
This allows objects in the scene to change freely between the active and
inactive states, without affecting the layout of any arrays which are being
indexed using the ID values.
Any transition between the active and inactive states requires a full acceleration structure rebuild. Applications must not perform an acceleration structure update where an object is active in the source acceleration structure but would be inactive in the destination, or vice versa.
The active/inactive state of primitives must not be changed with
acceleration structure updates.
For chained LSS, using the
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NV mode, entire
chains must be either active or inactive.
If any chain contains both active and inactive primitives, the behavior is
undefined.
Degenerate Primitives and Instances
Degenerate primitives and instances behave differently to inactive primitives and instances, and are defined as:
-
triangles that have one or more vertices whose respective (X), (Y), (Z) components are identical, or have three vertices that have at least two of the (X), (Y), or (Z) components identical, therefore forming a line or point. Degenerate triangles do not generate any intersections.
-
AABBs whose
minX=maxX,minY=maxY, andminZ=maxZ. Degenerate AABBs may invoke the intersection shader. -
LSS primitives where both the radii are set to
0. -
sphere primitives whose radius is set to
0. -
instances that reference bottom level acceleration structures that contain no active primitives. When building an acceleration structure, implementations should treat degenerate instances as though they are a point at the instance origin, specified by VkAccelerationStructureInstanceKHR::
transform.
Unlike inactive primitives and instances, degenerate primitives and instances may transition from the degenerate to the non-degenerate state, or vice versa, when performing an acceleration structure update.
If an acceleration structure is built without
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR set in
VkAccelerationStructureInfoNV::flags
or
VkAccelerationStructureBuildGeometryInfoKHR::flags
, degenerate primitives may be discarded.
Primitives that are defined with the same index value for more than one
vertex can always be discarded.
Building Acceleration Structures
To build an acceleration structure call:
// Provided by VK_NV_ray_tracing
void vkCmdBuildAccelerationStructureNV(
VkCommandBuffer commandBuffer,
const VkAccelerationStructureInfoNV* pInfo,
VkBuffer instanceData,
VkDeviceSize instanceOffset,
VkBool32 update,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkBuffer scratch,
VkDeviceSize scratchOffset);-
commandBufferis the command buffer into which the command will be recorded. -
pInfocontains the shared information for the acceleration structure’s structure. -
instanceDatais the buffer containing an array of VkAccelerationStructureInstanceKHR structures defining acceleration structures. This parameter must beNULLfor bottom level acceleration structures. -
instanceOffsetis the offset in bytes (relative to the start ofinstanceData) at which the instance data is located. -
updatespecifies whether to update thedstacceleration structure with the data insrc. -
dstis a pointer to the target acceleration structure for the build. -
srcis a pointer to an existing acceleration structure that is to be used to update thedstacceleration structure. -
scratchis the VkBuffer that will be used as scratch memory for the build. -
scratchOffsetis the offset in bytes relative to the start ofscratchthat will be used as a scratch memory.
Accesses to dst, src, and scratch must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
To build acceleration structures call:
// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresKHR(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppBuildRangeInfospointers that must be provided. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppBuildRangeInfosis a pointer to an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. EachppBuildRangeInfos[i] is a pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
The vkCmdBuildAccelerationStructuresKHR command provides the ability
to initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
This means that an application cannot build a top-level acceleration structure in the same vkCmdBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
Accesses to the acceleration structure scratch buffers as identified by the
VkAccelerationStructureBuildGeometryInfoKHR::scratchData buffer
device addresses must be synchronized with
the VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
(VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkAccelerationStructureBuildGeometryInfoKHR::srcAccelerationStructure
and
VkAccelerationStructureBuildGeometryInfoKHR::dstAccelerationStructure
must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, as appropriate.
Accesses to other input buffers as identified by any used values of
VkAccelerationStructureGeometryMotionTrianglesDataNV::vertexData,
VkAccelerationStructureGeometryTrianglesDataKHR::vertexData,
VkAccelerationStructureGeometryTrianglesDataKHR::indexData,
VkAccelerationStructureGeometryTrianglesDataKHR::transformData,
VkAccelerationStructureGeometryAabbsDataKHR::data, and
VkAccelerationStructureGeometryInstancesDataKHR::data must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_SHADER_READ_BIT.
To build acceleration structures with some parameters sourced on the device call:
// Provided by VK_KHR_acceleration_structure
void vkCmdBuildAccelerationStructuresIndirectKHR(
VkCommandBuffer commandBuffer,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkDeviceAddress* pIndirectDeviceAddresses,
const uint32_t* pIndirectStrides,
const uint32_t* const* ppMaxPrimitiveCounts);-
commandBufferis the command buffer into which the command will be recorded. -
infoCountis the number of acceleration structures to build. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
pIndirectDeviceAddressesis a pointer to an array ofinfoCountbuffer device addresses which point topInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i]. -
pIndirectStridesis a pointer to an array ofinfoCountbyte strides between elements ofpIndirectDeviceAddresses. -
ppMaxPrimitiveCountsis a pointer to an array ofinfoCountpointers to arrays ofpInfos[i].geometryCountvalues indicating the maximum number of primitives that will be built by this command for each geometry.
Accesses to acceleration structures, scratch buffers, vertex buffers, index buffers, and instance buffers must be synchronized as with vkCmdBuildAccelerationStructuresKHR.
Accesses to any element of pIndirectDeviceAddresses must be
synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_INDIRECT_COMMAND_READ_BIT.
The VkAccelerationStructureBuildGeometryInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
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;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built. -
flagsis a bitmask of VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure. -
modeis a VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform. -
srcAccelerationStructureis a pointer to an existing acceleration structure that is to be used to update thedstAccelerationStructureacceleration structure whenmodeisVK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR. -
dstAccelerationStructureis a pointer to the target acceleration structure for the build. -
geometryCountspecifies the number of geometries that will be built intodstAccelerationStructure. -
pGeometriesis a pointer to an array of VkAccelerationStructureGeometryKHR structures. -
ppGeometriesis a pointer to an array of pointers to VkAccelerationStructureGeometryKHR structures. -
scratchDatais the device or host address to 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.
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 dstAccelerationStructure
may 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.
The VkBuildAccelerationStructureModeKHR enumeration is defined as:
// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureModeKHR {
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR = 0,
VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR = 1,
} VkBuildAccelerationStructureModeKHR;-
VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHRspecifies that the destination acceleration structure will be built using the specified geometries. -
VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHRspecifies that the destination acceleration structure will be built using data in a source acceleration structure, updated by the specified geometries.
The VkDeviceOrHostAddressKHR union is defined as:
// Provided by VK_KHR_acceleration_structure, VK_NV_cooperative_vector
typedef union VkDeviceOrHostAddressKHR {
VkDeviceAddress deviceAddress;
void* hostAddress;
} VkDeviceOrHostAddressKHR;-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a host memory address.
The VkDeviceOrHostAddressConstKHR union is defined as:
// Provided by VK_KHR_acceleration_structure, VK_NV_cooperative_vector
typedef union VkDeviceOrHostAddressConstKHR {
VkDeviceAddress deviceAddress;
const void* hostAddress;
} VkDeviceOrHostAddressConstKHR;-
deviceAddressis a buffer device address as returned by the vkGetBufferDeviceAddressKHR command. -
hostAddressis a const host memory address.
The VkAccelerationStructureGeometryKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryKHR {
VkStructureType sType;
const void* pNext;
VkGeometryTypeKHR geometryType;
VkAccelerationStructureGeometryDataKHR geometry;
VkGeometryFlagsKHR flags;
} VkAccelerationStructureGeometryKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
geometryTypedescribes which type of geometry thisVkAccelerationStructureGeometryKHRrefers to. -
geometryis a VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type. -
flagsis a bitmask of VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built.
The VkAccelerationStructureGeometryDataKHR union is defined as:
// Provided by VK_KHR_acceleration_structure
typedef union VkAccelerationStructureGeometryDataKHR {
VkAccelerationStructureGeometryTrianglesDataKHR triangles;
VkAccelerationStructureGeometryAabbsDataKHR aabbs;
VkAccelerationStructureGeometryInstancesDataKHR instances;
} VkAccelerationStructureGeometryDataKHR;-
trianglesis a VkAccelerationStructureGeometryTrianglesDataKHR structure. -
aabbsis a VkAccelerationStructureGeometryAabbsDataKHR structure. -
instancesis a VkAccelerationStructureGeometryInstancesDataKHR structure.
The VkAccelerationStructureGeometryTrianglesDataKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryTrianglesDataKHR {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
uint32_t maxVertex;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceOrHostAddressConstKHR transformData;
} VkAccelerationStructureGeometryTrianglesDataKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each vertex element. -
vertexDatais a device or host address to memory containing vertex data for this geometry. -
vertexStrideis the stride in bytes between each vertex. -
maxVertexis the number of vertices invertexDataminus one. -
indexTypeis the VkIndexType of each index element. -
indexDatais a device or host address to memory containing index data for this geometry. -
transformDatais a device or host address to memory containing an optional reference to a VkTransformMatrixKHR structure describing a transformation from the space in which the vertices in this geometry are described to the space in which the acceleration structure is defined.
|
Unlike the stride for vertex buffers in
VkVertexInputBindingDescription for graphics pipelines which must not
exceed |
The VkAccelerationStructureGeometryMotionTrianglesDataNV structure is
defined as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureGeometryMotionTrianglesDataNV {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR vertexData;
} VkAccelerationStructureGeometryMotionTrianglesDataNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexDatais a pointer to vertex data for this geometry at time 1.0
If VkAccelerationStructureGeometryMotionTrianglesDataNV is included in
the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, the basic
vertex positions are used for the position of the triangles in the geometry
at time 0.0 and the vertexData in
VkAccelerationStructureGeometryMotionTrianglesDataNV is used for the
vertex positions at time 1.0, with positions linearly interpolated at
intermediate times.
Indexing for VkAccelerationStructureGeometryMotionTrianglesDataNV
vertexData is equivalent to the basic vertex position data.
The VkAccelerationStructureTrianglesOpacityMicromapEXT structure is
defined as:
// Provided by VK_EXT_opacity_micromap
typedef struct VkAccelerationStructureTrianglesOpacityMicromapEXT {
VkStructureType sType;
void* pNext;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexBuffer;
VkDeviceSize indexStride;
uint32_t baseTriangle;
uint32_t usageCountsCount;
const VkMicromapUsageEXT* pUsageCounts;
const VkMicromapUsageEXT* const* ppUsageCounts;
VkMicromapEXT micromap;
} VkAccelerationStructureTrianglesOpacityMicromapEXT;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
indexTypeis the type of triangle indices used when indexing this micromap -
indexBufferis the address containing the triangle indices -
indexStrideis the byte stride between triangle indices -
baseTriangleis the base value added to the non-negative triangle indices -
usageCountsCountspecifies the number of usage counts structures that will be used to determine the size of this micromap. -
pUsageCountsis a pointer to an array of VkMicromapUsageEXT structures. -
ppUsageCountsis a pointer to an array of pointers to VkMicromapUsageEXT structures. -
micromapis the handle to the micromap object to include in this geometry
If VkAccelerationStructureTrianglesOpacityMicromapEXT is included in
the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, that
geometry will reference that micromap.
For each triangle in the geometry, the acceleration structure build fetches
an index from indexBuffer using indexType and indexStride.
If that value is the unsigned cast of one of the values from
VkOpacityMicromapSpecialIndexEXT then that triangle behaves as
described for that special value in Ray Opacity Micromap.
Otherwise that triangle uses the opacity micromap information from
micromap at that index plus baseTriangle.
Only one of pUsageCounts or ppUsageCounts can be a valid
pointer, the other must be NULL.
The elements of the non-NULL array describe the total count used to build
this geometry.
For a given format and subdivisionLevel the number of triangles
in this geometry matching those values after indirection and special index
handling must be equal to the sum of matching count provided.
If micromap is VK_NULL_HANDLE, then every value read from
indexBuffer must be one of the values in
VkOpacityMicromapSpecialIndexEXT.
The VkOpacityMicromapSpecialIndexEXT enumeration is defined as:
// Provided by VK_EXT_opacity_micromap
typedef enum VkOpacityMicromapSpecialIndexEXT {
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXT = -1,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXT = -2,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXT = -3,
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXT = -4,
// Provided by VK_EXT_opacity_micromap with VK_NV_cluster_acceleration_structure
VK_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_GEOMETRY_DISABLE_OPACITY_MICROMAP_NV = -5,
} VkOpacityMicromapSpecialIndexEXT;-
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXTspecifies that the entire triangle is fully transparent. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXTspecifies that the entire triangle is fully opaque. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXTspecifies that the entire triangle is unknown-transparent. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXTspecifies that the entire triangle is unknown-opaque. -
VK_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_GEOMETRY_DISABLE_OPACITY_MICROMAP_NVspecifies that Opacity Micromap will be disabled for this triangle and opacity value will be picked from VkClusterAccelerationStructureBuildTriangleClusterInfoNV::baseGeometryIndexAndGeometryFlagsinstead. Note that this special index is only valid for Cluster Geometry.
The VkAccelerationStructureTrianglesDisplacementMicromapNV structure
is defined as:
// Provided by VK_NV_displacement_micromap
typedef struct VkAccelerationStructureTrianglesDisplacementMicromapNV {
VkStructureType sType;
void* pNext;
VkFormat displacementBiasAndScaleFormat;
VkFormat displacementVectorFormat;
VkDeviceOrHostAddressConstKHR displacementBiasAndScaleBuffer;
VkDeviceSize displacementBiasAndScaleStride;
VkDeviceOrHostAddressConstKHR displacementVectorBuffer;
VkDeviceSize displacementVectorStride;
VkDeviceOrHostAddressConstKHR displacedMicromapPrimitiveFlags;
VkDeviceSize displacedMicromapPrimitiveFlagsStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexBuffer;
VkDeviceSize indexStride;
uint32_t baseTriangle;
uint32_t usageCountsCount;
const VkMicromapUsageEXT* pUsageCounts;
const VkMicromapUsageEXT* const* ppUsageCounts;
VkMicromapEXT micromap;
} VkAccelerationStructureTrianglesDisplacementMicromapNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
displacementBiasAndScaleFormatis the format of displacement bias and scale used in this displacement micromap reference. -
displacementVectorFormatis the format of displacement vector used in this displacement micromap reference. -
displacementBiasAndScaleBufferis the address containing the bias and scale. -
displacementBiasAndScaleStrideis the byte stride between bias and scale values. -
displacementVectorBufferis the address containing the displacement vector values. -
displacementVectorStrideis the byte stride between displacement vector values. -
displacedMicromapPrimitiveFlagsis the address containing the primitive flags. -
displacedMicromapPrimitiveFlagsStrideis the byte stride between primitive flag values. -
indexTypeis the type of triangle indices used when indexing this micromap. -
indexBufferis the address containing the triangle indices. -
indexStrideis the byte stride between triangle indices. -
baseTriangleis the base value added to the non-negative triangle indices. -
usageCountsCountspecifies the number of usage counts structures that will be used to determine the size of this micromap. -
pUsageCountsis a pointer to an array of VkMicromapUsageEXT structures. -
ppUsageCountsis a pointer to an array of pointers to VkMicromapUsageEXT structures. -
micromapis the handle to the micromap object to include in this geometry.
If VkAccelerationStructureTrianglesDisplacementMicromapNV is included
in the pNext chain of a
VkAccelerationStructureGeometryTrianglesDataKHR structure, that
geometry will reference that micromap.
For each triangle in the geometry, the acceleration structure build fetches
an index from indexBuffer using indexType and indexStride.
That triangle uses the displacement micromap information from micromap
at that index plus baseTriangle.
Only one of pUsageCounts or ppUsageCounts can be a valid
pointer, the other must be NULL.
The elements of the non-NULL array describe the total count used to build
this geometry.
For a given format and subdivisionLevel the number of triangles
in this geometry matching those values after indirection must be equal to
the sum of matching count provided.
The VkTransformMatrixKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkTransformMatrixKHR {
float matrix[3][4];
} VkTransformMatrixKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkTransformMatrixKHR VkTransformMatrixNV;-
matrixis a 3x4 row-major affine transformation matrix.
The VkAccelerationStructureGeometryAabbsDataKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryAabbsDataKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR data;
VkDeviceSize stride;
} VkAccelerationStructureGeometryAabbsDataKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
datais a device or host address to memory containing VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry. -
strideis the stride in bytes between each entry indata. The stride must be a multiple of8.
The VkAabbPositionsKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAabbPositionsKHR {
float minX;
float minY;
float minZ;
float maxX;
float maxY;
float maxZ;
} VkAabbPositionsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkAabbPositionsKHR VkAabbPositionsNV;-
minXis the x position of one opposing corner of a bounding box. -
minYis the y position of one opposing corner of a bounding box. -
minZis the z position of one opposing corner of a bounding box. -
maxXis the x position of the other opposing corner of a bounding box. -
maxYis the y position of the other opposing corner of a bounding box. -
maxZis the z position of the other opposing corner of a bounding box.
The VkAccelerationStructureGeometryInstancesDataKHR structure is
defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureGeometryInstancesDataKHR {
VkStructureType sType;
const void* pNext;
VkBool32 arrayOfPointers;
VkDeviceOrHostAddressConstKHR data;
} VkAccelerationStructureGeometryInstancesDataKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
arrayOfPointersspecifies whetherdatais used as an array of addresses or just an array. -
datais either the address of an array of device or host addresses referencing individual VkAccelerationStructureInstanceKHR structures or packed motion instance information as described in motion instances ifarrayOfPointersisVK_TRUE, or the address of an array of VkAccelerationStructureInstanceKHR or VkAccelerationStructureMotionInstanceNV structures. Addresses and VkAccelerationStructureInstanceKHR structures are tightly packed. VkAccelerationStructureMotionInstanceNV structures have a stride of 160 bytes.
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;-
transformis a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure. -
instanceCustomIndexis a 24-bit application-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis 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:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies 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.
Possible values of flags in the instance modifying the behavior of
that instance are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryInstanceFlagBitsKHR {
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR = 0x00000001,
VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR = 0x00000002,
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR = 0x00000004,
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR = 0x00000008,
// Provided by VK_EXT_opacity_micromap
VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_EXT = 0x00000010,
// Provided by VK_EXT_opacity_micromap
VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT = 0x00000020,
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR = VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV = VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR,
// Provided by VK_NV_ray_tracing
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV = VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR,
} VkGeometryInstanceFlagBitsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagBitsKHR VkGeometryInstanceFlagBitsNV;-
VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHRdisables face culling for this instance. -
VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHRspecifies that the facing determination for geometry in this instance is inverted. Because the facing is determined in object space, an instance transform does not change the winding, but a geometry transform does. -
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VNoOpaqueKHRray flag. -
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHRcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere not specified on all geometries referenced by this instance. This behavior can be overridden by the SPIR-VOpaqueKHRray flag.
VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and
VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must not be used in the
same flag.
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryInstanceFlagsKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkGeometryInstanceFlagsKHR VkGeometryInstanceFlagsNV;VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of
zero or more VkGeometryInstanceFlagBitsKHR.
Acceleration structure motion 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 including a type of motion and parameters to determine the motion of the instance over time.
An acceleration structure motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMotionInstanceNV {
VkAccelerationStructureMotionInstanceTypeNV type;
VkAccelerationStructureMotionInstanceFlagsNV flags;
VkAccelerationStructureMotionInstanceDataNV data;
} VkAccelerationStructureMotionInstanceNV;-
typeis a VkAccelerationStructureMotionInstanceTypeNV enumerant identifying which type of motion instance this is and which type of the union is valid. -
flagsis currently unused, but is required to keep natural alignment ofdata. -
datais a VkAccelerationStructureMotionInstanceDataNV containing motion instance data for this instance.
|
If writing this other than with a standard C compiler, note that the final structure should be 152 bytes in size. |
Acceleration structure motion instance is defined by the union:
// Provided by VK_NV_ray_tracing_motion_blur
typedef union VkAccelerationStructureMotionInstanceDataNV {
VkAccelerationStructureInstanceKHR staticInstance;
VkAccelerationStructureMatrixMotionInstanceNV matrixMotionInstance;
VkAccelerationStructureSRTMotionInstanceNV srtMotionInstance;
} VkAccelerationStructureMotionInstanceDataNV;-
staticInstanceis a VkAccelerationStructureInstanceKHR structure containing data for a static instance. -
matrixMotionInstanceis a VkAccelerationStructureMatrixMotionInstanceNV structure containing data for a matrix motion instance. -
srtMotionInstanceis a VkAccelerationStructureSRTMotionInstanceNV structure containing data for an SRT motion instance.
// Provided by VK_NV_ray_tracing_motion_blur
typedef VkFlags VkAccelerationStructureMotionInstanceFlagsNV;VkAccelerationStructureMotionInstanceFlagsNV is a bitmask type for
setting a mask, but is currently reserved for future use.
The VkAccelerationStructureMotionInstanceTypeNV enumeration is defined
as:
// Provided by VK_NV_ray_tracing_motion_blur
typedef enum VkAccelerationStructureMotionInstanceTypeNV {
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NV = 0,
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NV = 1,
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NV = 2,
} VkAccelerationStructureMotionInstanceTypeNV;-
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NVspecifies that the instance is a static instance with no instance motion. -
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NVspecifies that the instance is a motion instance with motion specified by interpolation between two matrices. -
VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NVspecifies that the instance is a motion instance with motion specified by interpolation in the SRT decomposition.
An acceleration structure matrix motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMatrixMotionInstanceNV {
VkTransformMatrixKHR transformT0;
VkTransformMatrixKHR transformT1;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureMatrixMotionInstanceNV;-
transformT0is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 0. -
transformT1is a VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 1. -
instanceCustomIndexis a 24-bit application-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis 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).
-
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:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies 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.
The transform for a matrix motion instance at a point in time is derived by
component-wise linear interpolation of the two transforms.
That is, for a time in [0,1] the resulting transform is
-
transformT0× (1 -time) +transformT1×time
An acceleration structure SRT motion instance is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureSRTMotionInstanceNV {
VkSRTDataNV transformT0;
VkSRTDataNV transformT1;
uint32_t instanceCustomIndex:24;
uint32_t mask:8;
uint32_t instanceShaderBindingTableRecordOffset:24;
VkGeometryInstanceFlagsKHR flags:8;
uint64_t accelerationStructureReference;
} VkAccelerationStructureSRTMotionInstanceNV;-
transformT0is a VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 0. -
transformT1is a VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 1. -
instanceCustomIndexis a 24-bit application-specified index value accessible to ray shaders in theInstanceCustomIndexKHRbuilt-in. -
maskis an 8-bit visibility mask for the geometry. The instance may only be hit ifCull Mask & instance.mask != 0 -
instanceShaderBindingTableRecordOffsetis a 24-bit offset used in calculating the hit shader binding table index. -
flagsis an 8-bit mask of VkGeometryInstanceFlagBitsKHR values to apply to this instance. -
accelerationStructureReferenceis 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).
-
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:
-
instanceCustomIndexandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
instanceCustomIndexoccupies the 24 least significant bits of that memory -
maskoccupies the 8 most significant bits of that memory
-
-
instanceShaderBindingTableRecordOffsetandflagsoccupy the same memory as if a singleuint32_twas specified in their place-
instanceShaderBindingTableRecordOffsetoccupies the 24 least significant bits of that memory -
flagsoccupies 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.
The transform for a SRT motion instance at a point in time is derived from
component-wise linear interpolation of the two SRT transforms.
That is, for a time in [0,1] the resulting transform is
-
transformT0× (1 -time) +transformT1×time
An acceleration structure SRT transform is defined by the structure:
// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkSRTDataNV {
float sx;
float a;
float b;
float pvx;
float sy;
float c;
float pvy;
float sz;
float pvz;
float qx;
float qy;
float qz;
float qw;
float tx;
float ty;
float tz;
} VkSRTDataNV;-
sxis the x component of the scale of the transform -
ais one component of the shear for the transform -
bis one component of the shear for the transform -
pvxis the x component of the pivot point of the transform -
syis the y component of the scale of the transform -
cis one component of the shear for the transform -
pvyis the y component of the pivot point of the transform -
szis the z component of the scale of the transform -
pvzis the z component of the pivot point of the transform -
qxis the x component of the rotation quaternion -
qyis the y component of the rotation quaternion -
qzis the z component of the rotation quaternion -
qwis the w component of the rotation quaternion -
txis the x component of the post-rotation translation -
tyis the y component of the post-rotation translation -
tzis the z component of the post-rotation translation
This transform decomposition consists of three elements. The first is a matrix S, consisting of a scale, shear, and translation, usually used to define the pivot point of the following rotation. This matrix is constructed from the parameters above by:
The rotation quaternion is defined as:
-
R= [qx,qy,qz,qw]
This is a rotation around a conceptual normalized axis [ ax, ay, az ]
of amount theta such that:
-
[
qx,qy,qz] = sin(theta/2) × [ax,ay,az]
and
-
qw= cos(theta/2)
Finally, the transform has a translation T constructed from the parameters above by:
The effective derived transform is then given by
-
T×R×S
VkAccelerationStructureBuildRangeInfoKHR is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildRangeInfoKHR {
uint32_t primitiveCount;
uint32_t primitiveOffset;
uint32_t firstVertex;
uint32_t transformOffset;
} VkAccelerationStructureBuildRangeInfoKHR;-
primitiveCountdefines the number of primitives for a corresponding acceleration structure geometry. -
primitiveOffsetdefines an offset in bytes into the memory where primitive data is defined. -
firstVertexis the index of the first vertex to build from for triangle geometry. -
transformOffsetdefines an offset in bytes into the memory where a transform matrix is defined.
The primitive count and primitive offset are interpreted differently depending on the VkGeometryTypeKHR used:
-
For geometries of type
VK_GEOMETRY_TYPE_TRIANGLES_KHR,primitiveCountis the number of triangles to be built, where each triangle is treated as 3 vertices.-
If the geometry uses indices,
primitiveCount× 3 indices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices. -
If the geometry does not use indices,
primitiveCount× 3 vertices are consumed from VkAccelerationStructureGeometryTrianglesDataKHR::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryTrianglesDataKHR::vertexStride×firstVertex. -
If VkAccelerationStructureGeometryTrianglesDataKHR::
transformDatais notNULL, a single VkTransformMatrixKHR structure is consumed from VkAccelerationStructureGeometryTrianglesDataKHR::transformData, at an offset oftransformOffset. This matrix describes a transformation from the space in which the vertices for all triangles in this geometry are described to the space in which the acceleration structure is defined.
-
-
For geometries of type
VK_GEOMETRY_TYPE_AABBS_KHR,primitiveCountis the number of axis-aligned bounding boxes.primitiveCountVkAabbPositionsKHR structures are consumed from VkAccelerationStructureGeometryAabbsDataKHR::data, starting at an offset ofprimitiveOffset. -
For geometries of type
VK_GEOMETRY_TYPE_SPHERES_NV,primitiveCountis the number of spheres to be built, where each sphere is treated as 1 vertex.-
If the geometry uses indices,
primitiveCountindices are consumed from VkAccelerationStructureGeometrySpheresDataNV::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices and radii. -
If the geometry does not use indices,
primitiveCountvertices and radii are consumed from VkAccelerationStructureGeometrySpheresDataNV::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometrySpheresDataNV::vertexStride×firstVertexand VkAccelerationStructureGeometrySpheresDataNV::radiusData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometrySpheresDataNV::radiusStride×firstVertexrespectively.
-
-
For geometries of type
VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV,primitiveCountis the number of LSS primitives to be built, where each LSS primitive is treated as 2 vertices.-
If the geometry uses indices,
primitiveCount× 2 indices are consumed from VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexData, starting at an offset ofprimitiveOffset. The value offirstVertexis added to the index values before fetching vertices and radii. -
If the geometry does not use indices,
primitiveCount× 2 vertices and radii are consumed from VkAccelerationStructureGeometryLinearSweptSpheresDataNV::vertexData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryLinearSweptSpheresDataNV::vertexStride×firstVertexand VkAccelerationStructureGeometryLinearSweptSpheresDataNV::radiusData, starting at an offset ofprimitiveOffset+ VkAccelerationStructureGeometryLinearSweptSpheresDataNV::radiusStride×firstVertexrespectively.
-
-
For geometries of type
VK_GEOMETRY_TYPE_INSTANCES_KHR,primitiveCountis the number of acceleration structures.primitiveCountVkAccelerationStructureInstanceKHR or VkAccelerationStructureMotionInstanceNV structures are consumed from VkAccelerationStructureGeometryInstancesDataKHR::data, starting at an offset ofprimitiveOffset.
If VkAccelerationStructureGeometryLinearSweptSpheresDataNV is included
in the pNext chain of a VkAccelerationStructureGeometryKHR
structure, then that structures defines the linear swept sphere’s (LSS)
geometry data.
The VkAccelerationStructureGeometryLinearSweptSpheresDataNV structure
is defined as:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef struct VkAccelerationStructureGeometryLinearSweptSpheresDataNV {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
VkFormat radiusFormat;
VkDeviceOrHostAddressConstKHR radiusData;
VkDeviceSize radiusStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceSize indexStride;
VkRayTracingLssIndexingModeNV indexingMode;
VkRayTracingLssPrimitiveEndCapsModeNV endCapsMode;
} VkAccelerationStructureGeometryLinearSweptSpheresDataNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each LSS vertex element. -
vertexDatais a device or host address to memory containing vertex data for this geometry. -
vertexStrideis the stride in bytes between each vertex element. -
radiusFormatis the VkFormat of each LSS radius. -
radiusDatais a device or host address to memory containing LSS radius data value. -
radiusStrideis the stride in bytes between each radius value. -
indexTypeis the VkIndexType of each index element. -
indexDataisNULLor a device or host address to memory containing index data for vertex and radius buffers for this geometry. -
indexStrideis the stride in bytes between each index element. -
indexingModeis a VkRayTracingLssIndexingModeNV value specifying the mode of indexing. -
endCapsModeis a VkRayTracingLssPrimitiveEndCapsModeNV value specifying the endcaps mode for LSS primitives.
If an index buffer is not specified in indexData, LSS primitives are
rendered individually using subsequent pairs of vertices similar to
VK_PRIMITIVE_TOPOLOGY_LINE_LIST.
Chaining LSS primitives can be achieved by specifying an index buffer in
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexData
and setting
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::indexingMode
to one of VkRayTracingLssIndexingModeNV values:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef enum VkRayTracingLssIndexingModeNV {
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NV = 0,
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NV = 1,
} VkRayTracingLssIndexingModeNV;-
VK_RAY_TRACING_LSS_INDEXING_MODE_LIST_NVspecifies that a list of indices is provided where each consecutive pair of indices define a LSS primitive. -
VK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NVspecifies a successive implicit indexing format, in which each LSS primitive is defined by two successive positions and radii, (k, k + 1), where k is a single index provided in the index buffer. In this indexing scheme, there is a 1:1 mapping between the index buffer and primitive index within the geometry.
The default behavior with endcaps in a LSS chain is that both endcaps will
be enabled for all beginning and end points.
To change the LSS chain’s endcaps mode use
VkAccelerationStructureGeometryLinearSweptSpheresDataNV::endCapsMode.
The possible values for endCapsMode are:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef enum VkRayTracingLssPrimitiveEndCapsModeNV {
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_NONE_NV = 0,
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NV = 1,
} VkRayTracingLssPrimitiveEndCapsModeNV;-
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_NONE_NVdisables all endcaps and the chain boundaries have no influence. -
VK_RAY_TRACING_LSS_PRIMITIVE_END_CAPS_MODE_CHAINED_NVspecifies that whenVK_RAY_TRACING_LSS_INDEXING_MODE_SUCCESSIVE_NVis used as indexing mode for the LSS primitive, the first primitive in each chain will have both endcaps enabled, and every following primitive in the chain only has endcaps at the trailing position enabled.
In addition to LSS primitives, simple sphere geometry is also supported. Spheres do not have an endcap mode. If an index buffer is present, each entry represents a single position and radius describing one sphere primitive. If no index buffer is provided, the vertex position and radius values are sequentially read from the corresponding buffers.
If VkAccelerationStructureGeometrySpheresDataNV is included in the
pNext chain of a VkAccelerationStructureGeometryKHR structure,
then that structures defines the sphere’s geometry data.
The VkAccelerationStructureGeometrySpheresDataNV structure is defined
as:
// Provided by VK_NV_ray_tracing_linear_swept_spheres
typedef struct VkAccelerationStructureGeometrySpheresDataNV {
VkStructureType sType;
const void* pNext;
VkFormat vertexFormat;
VkDeviceOrHostAddressConstKHR vertexData;
VkDeviceSize vertexStride;
VkFormat radiusFormat;
VkDeviceOrHostAddressConstKHR radiusData;
VkDeviceSize radiusStride;
VkIndexType indexType;
VkDeviceOrHostAddressConstKHR indexData;
VkDeviceSize indexStride;
} VkAccelerationStructureGeometrySpheresDataNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each sphere’s vertex element. -
vertexDatais a device or host address to memory containing vertex data in form of pairs of centers of spheres that define all sphere geometry. -
vertexStrideis the stride in bytes between each vertex element. -
radiusFormatis the VkFormat of each sphere’s radius. -
radiusDatais a device or host address to memory containing sphere’s radius data value. -
radiusStrideis the stride in bytes between each radius value. -
indexTypeis the VkIndexType of each index element. -
indexDataisNULLor a device or host address to memory containing index data for vertex and radius buffers for this geometry. -
indexStrideis the stride in bytes between each index element.
Copying Acceleration Structures
An additional command exists for copying acceleration structures without updating their contents. The acceleration structure object can be compacted in order to improve performance. Before copying, an application must query the size of the resulting acceleration structure.
To query acceleration structure size parameters call:
// Provided by VK_KHR_acceleration_structure
void vkCmdWriteAccelerationStructuresPropertiesKHR(
VkCommandBuffer commandBuffer,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);-
commandBufferis the command buffer into which the command will be recorded. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryPoolis the query pool that will manage the results of the query. -
firstQueryis the first query index within the query pool that will contain theaccelerationStructureCountnumber of results.
Accesses to any of the acceleration structures listed in
pAccelerationStructures must be synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
-
If
queryTypeisVK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the value written out is the number of bytes required by a compacted acceleration structure. -
If
queryTypeisVK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then the value written out is the number of bytes required by a serialized acceleration structure.
To query acceleration structure size parameters call:
// Provided by VK_NV_ray_tracing
void vkCmdWriteAccelerationStructuresPropertiesNV(
VkCommandBuffer commandBuffer,
uint32_t accelerationStructureCount,
const VkAccelerationStructureNV* pAccelerationStructures,
VkQueryType queryType,
VkQueryPool queryPool,
uint32_t firstQuery);-
commandBufferis the command buffer into which the command will be recorded. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the type of queries managed by the pool. -
queryPoolis the query pool that will manage the results of the query. -
firstQueryis the first query index within the query pool that will contain theaccelerationStructureCountnumber of results.
Accesses to any of the acceleration structures listed in
pAccelerationStructures must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
To copy an acceleration structure call:
// Provided by VK_NV_ray_tracing
void vkCmdCopyAccelerationStructureNV(
VkCommandBuffer commandBuffer,
VkAccelerationStructureNV dst,
VkAccelerationStructureNV src,
VkCopyAccelerationStructureModeKHR mode);-
commandBufferis the command buffer into which the command will be recorded. -
dstis the target acceleration structure for the copy. -
srcis the source acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
Accesses to src and dst must be synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.
To copy an acceleration structure call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureInfoKHR* pInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
This command copies the pInfo->src acceleration structure to the
pInfo->dst acceleration structure in the manner specified by
pInfo->mode.
Accesses to pInfo->src and pInfo->dst must be
synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate.
The VkCopyAccelerationStructureInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source acceleration structure for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
Possible values of mode specifying additional operations to perform
during the copy, are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkCopyAccelerationStructureModeKHR {
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR = 0,
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR = 1,
// Provided by VK_KHR_acceleration_structure
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR = 2,
// Provided by VK_KHR_acceleration_structure
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR = 3,
// Provided by VK_NV_ray_tracing
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR,
// Provided by VK_NV_ray_tracing
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV = VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR,
} VkCopyAccelerationStructureModeKHR;or the equivalent
// Provided by VK_NV_ray_tracing
typedef VkCopyAccelerationStructureModeKHR VkCopyAccelerationStructureModeNV;-
VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHRcreates a direct copy of the acceleration structure specified insrcinto the one specified bydst. Thedstacceleration structure must have been created with the same parameters assrc. Ifsrccontains references to other acceleration structures,dstwill reference the same acceleration structures. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHRcreates a more compact version of an acceleration structuresrcintodst. The acceleration structuredstmust have been created with a size at least as large as that returned by vkCmdWriteAccelerationStructuresPropertiesNV , vkCmdWriteAccelerationStructuresPropertiesKHR, or vkWriteAccelerationStructuresPropertiesKHR after the build of the acceleration structure specified bysrc. Ifsrccontains references to other acceleration structures,dstwill reference the same acceleration structures. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHRserializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation. -
VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHRdeserializes the semi-opaque serialization format in the buffer to the acceleration structure.
To copy an acceleration structure to device memory call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyAccelerationStructureToMemoryKHR(
VkCommandBuffer commandBuffer,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pInfois an a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
Accesses to pInfo->src must be synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR.
Accesses to the buffer indicated by pInfo->dst.deviceAddress must be
synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an and an access
type of VK_ACCESS_TRANSFER_WRITE_BIT.
This command produces the same results as vkCopyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
The defined header structure for the serialized data consists of:
-
VK_UUID_SIZEbytes of data matchingVkPhysicalDeviceIDProperties::driverUUID -
VK_UUID_SIZEbytes of data identifying the compatibility for comparison using vkGetDeviceAccelerationStructureCompatibilityKHR -
A 64-bit integer of the total size matching the value queried using
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR -
A 64-bit integer of the deserialized size to be passed in to
VkAccelerationStructureCreateInfoKHR::size -
A 64-bit integer of the count of the number of acceleration structure handles following. This value matches the value queried using
VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. This will be zero for a bottom-level acceleration structure. For top-level acceleration structures this number is implementation-dependent; the number of and ordering of the handles may not match the instance descriptions which were used to build the acceleration structure.
The corresponding handles matching the values returned by vkGetAccelerationStructureDeviceAddressKHR or vkGetAccelerationStructureHandleNV are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing. The serialized data is written to the buffer (or read from the buffer) according to the host endianness.
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyAccelerationStructureToMemoryInfoKHR {
VkStructureType sType;
const void* pNext;
VkAccelerationStructureKHR src;
VkDeviceOrHostAddressKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyAccelerationStructureToMemoryInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the source acceleration structure for the copy -
dstis the device or host address to memory which is the target for the copy -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
To copy device memory to an acceleration structure call:
// Provided by VK_KHR_acceleration_structure
void vkCmdCopyMemoryToAccelerationStructureKHR(
VkCommandBuffer commandBuffer,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);-
commandBufferis the command buffer into which the command will be recorded. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
Accesses to pInfo->dst must be synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
Accesses to the buffer indicated by pInfo->src.deviceAddress must be
synchronized with the
VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR
pipeline stage or the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage, and an access type of
VK_ACCESS_TRANSFER_READ_BIT.
This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
The structure provided as input to deserialize is as described in vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration structure handles filled in with the newly-queried handles to bottom level acceleration structures created before deserialization. These do not need to be built at deserialize time, but must be created.
The VkCopyMemoryToAccelerationStructureInfoKHR structure is defined
as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkCopyMemoryToAccelerationStructureInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceOrHostAddressConstKHR src;
VkAccelerationStructureKHR dst;
VkCopyAccelerationStructureModeKHR mode;
} VkCopyMemoryToAccelerationStructureInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
srcis the device or host address to memory containing the source data for the copy. -
dstis the target acceleration structure for the copy. -
modeis a VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy.
To check if a serialized acceleration structure is compatible with the current device call:
// Provided by VK_KHR_acceleration_structure
void vkGetDeviceAccelerationStructureCompatibilityKHR(
VkDevice device,
const VkAccelerationStructureVersionInfoKHR* pVersionInfo,
VkAccelerationStructureCompatibilityKHR* pCompatibility);-
deviceis the device to check the version against. -
pVersionInfois a pointer to a VkAccelerationStructureVersionInfoKHR structure specifying version information to check against the device. -
pCompatibilityis a pointer to a VkAccelerationStructureCompatibilityKHR value in which compatibility information is returned.
The VkAccelerationStructureVersionInfoKHR structure is defined as:
// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureVersionInfoKHR {
VkStructureType sType;
const void* pNext;
const uint8_t* pVersionData;
} VkAccelerationStructureVersionInfoKHR;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
pVersionDatais a pointer to the version header of an acceleration structure as defined in vkCmdCopyAccelerationStructureToMemoryKHR
|
|
Possible values of pCompatibility returned by
vkGetDeviceAccelerationStructureCompatibilityKHR are:
// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCompatibilityKHR {
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR = 0,
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR = 1,
} VkAccelerationStructureCompatibilityKHR;-
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHRif thepVersionDataversion acceleration structure is compatible withdevice. -
VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHRif thepVersionDataversion acceleration structure is not compatible withdevice.
Cluster Level Acceleration Structures
Acceleration structure build times in ray tracing applications with extensive geometry can be reduced by introducing alternative acceleration structure types that facilitate bottom-level acceleration structure construction using pre-generated primitive clusters, improving geometry reuse. This can be achieved by incorporating additional acceleration structure types:
Cluster Level Acceleration Structure (CLAS) is an intermediate acceleration structure constructed from triangles, which serves as a building block for Cluster Level Bottom Level Acceleration Structure. A CLAS shares similarities with a traditional bottom level acceleration structure but has several key distinctions. A CLAS can only contain a limited number of triangles and vertices. CLAS objects cannot be directly referenced in a top level acceleration structure, instead, they must be part of a Cluster Level Bottom Level Acceleration Structure. The geometry indices within a CLAS are local to it, potentially non-consecutive, and customizable per primitive. Each CLAS can also have a user-defined 32-bit ClusterID, which is accessible in the hit shaders. The vertex positions within a CLAS can be quantized by zeroing specific floating-point mantissa bits to optimize storage.
Cluster Template Acceleration Structure is a partially constructed CLAS designed for efficient instantiation into multiple CLAS objects. During a cluster template build, some pre-computation is performed independent of vertex positions, allowing reuse across multiple CLAS objects with different vertex data. A cluster template itself does not require vertex positions but it retains non-positional properties similar to a CLAS, which are then inherited during instantiation. A cluster template must be instantiated into a CLAS object to be usable.
Cluster Level Bottom Level Acceleration Structure is a new alternative to the existing bottom level acceleration structures, which is constructed using references to already built CLAS objects and is the only cluster acceleration structure that can be referenced in a top level acceleration structure.
These cluster acceleration structures can be built or moved by a single versatile multi-indirect function vkCmdBuildClusterAccelerationStructureIndirectNV. To determine the memory requirements for executing this function, call:
// Provided by VK_NV_cluster_acceleration_structure
void vkGetClusterAccelerationStructureBuildSizesNV(
VkDevice device,
const VkClusterAccelerationStructureInputInfoNV* pInfo,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);-
deviceis the logical device that owns the acceleration structure. -
pInfois a pointer to a VkClusterAccelerationStructureInputInfoNV structure containing parameters required for the memory requirements query. -
pSizeInfois a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and scratch buffer, given the build parameters.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV,
acceleration structure and scratch memory sizes are returned for all
VkClusterAccelerationStructureInputInfoNV::maxAccelerationStructureCount
acceleration structures.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV,
scratch memory size for all
VkClusterAccelerationStructureInputInfoNV::maxAccelerationStructureCount
acceleration structures and the acceleration structure memory size for a
single acceleration structure is returned.
If VkClusterAccelerationStructureInputInfoNV::opMode is
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, only
scratch memory size is returned for the requested acceleration structures.
The VkClusterAccelerationStructureInputInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureInputInfoNV {
VkStructureType sType;
void* pNext;
uint32_t maxAccelerationStructureCount;
VkBuildAccelerationStructureFlagsKHR flags;
VkClusterAccelerationStructureOpTypeNV opType;
VkClusterAccelerationStructureOpModeNV opMode;
VkClusterAccelerationStructureOpInputNV opInput;
} VkClusterAccelerationStructureInputInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxAccelerationStructureCountis the maximum number of acceleration structures that will be provided to the multi indirect operation. -
flagsis a bitmask of VkBuildAccelerationStructureFlagsKHR specifying flags for the multi indirect operation. -
opTypeis a VkClusterAccelerationStructureOpTypeNV value specifying the type of operation to perform. -
opModeis a VkClusterAccelerationStructureOpModeNV value specifying the mode of operation. -
opInputis a VkClusterAccelerationStructureOpInputNV value specifying the descriptions of the operation.
Values which can be set in VkClusterAccelerationStructureOpTypeNV
are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureOpTypeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NV = 2,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NV = 3,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NV = 4,
} VkClusterAccelerationStructureOpTypeNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_MOVE_OBJECTS_NVspecifies that a cluster acceleration structure, cluster acceleration structure template or a bottom level acceleration structure built from cluster acceleration structures will be moved. If a cluster acceleration structure is moved, the bottom level cluster acceleration structures containing it will have to be re-built. If used withVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, it returns the size of existing cluster acceleration structures. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_CLUSTERS_BOTTOM_LEVEL_NVindicates that bottom level cluster acceleration structures will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_NVindicates that cluster acceleration structures will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_BUILD_TRIANGLE_CLUSTER_TEMPLATE_NVindicates that a template for cluster acceleration structure will be built. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_TYPE_INSTANTIATE_TRIANGLE_CLUSTER_NVindicates that a template for a cluster acceleration structure will be instantiated, resulting in a built cluster acceleration structure.
Values which can be set in VkClusterAccelerationStructureOpModeNV
are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureOpModeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV = 2,
} VkClusterAccelerationStructureOpModeNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NVindicates that the build or move operation will implicitly distribute built or compacted cluster acceleration structures starting at the address provided in VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData. If a move operation is being performed, the acceleration structures will be tightly compacted. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NVindicates that the build or move operation will explicitly write built or compacted cluster acceleration structures in the array of addresses provided in VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NVindicates that computed cluster acceleration structure sizes will be written to VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray.
The VkClusterAccelerationStructureOpInputNV union is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef union VkClusterAccelerationStructureOpInputNV {
VkClusterAccelerationStructureClustersBottomLevelInputNV* pClustersBottomLevel;
VkClusterAccelerationStructureTriangleClusterInputNV* pTriangleClusters;
VkClusterAccelerationStructureMoveObjectsInputNV* pMoveObjects;
} VkClusterAccelerationStructureOpInputNV;-
pClustersBottomLevelis a VkClusterAccelerationStructureClustersBottomLevelInputNV structure specifying an upper threshold on parameters to build multiple bottom level acceleration structures from multiple cluster level acceleration structures. -
pTriangleClustersis a VkClusterAccelerationStructureTriangleClusterInputNV structure specifying an upper threshold on parameters to build a regular or templated cluster acceleration structure. -
pMoveObjectsis a VkClusterAccelerationStructureMoveObjectsInputNV structure specifying an upper threshold on the number of bytes moved and the type of acceleration structure being moved.
The VkClusterAccelerationStructureClustersBottomLevelInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureClustersBottomLevelInputNV {
VkStructureType sType;
void* pNext;
uint32_t maxTotalClusterCount;
uint32_t maxClusterCountPerAccelerationStructure;
} VkClusterAccelerationStructureClustersBottomLevelInputNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
maxTotalClusterCountis the total number of clusters acceleration structures that will be built or moved across all input arguments. -
maxClusterCountPerAccelerationStructureis the maximum number of clusters acceleration structures that will be built or moved per input argument.
The VkClusterAccelerationStructureTriangleClusterInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureTriangleClusterInputNV {
VkStructureType sType;
void* pNext;
VkFormat vertexFormat;
uint32_t maxGeometryIndexValue;
uint32_t maxClusterUniqueGeometryCount;
uint32_t maxClusterTriangleCount;
uint32_t maxClusterVertexCount;
uint32_t maxTotalTriangleCount;
uint32_t maxTotalVertexCount;
uint32_t minPositionTruncateBitCount;
} VkClusterAccelerationStructureTriangleClusterInputNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
vertexFormatis the VkFormat of each vertex element. -
maxGeometryIndexValueis the maximum geometry index value for any constructed geometry. -
maxClusterUniqueGeometryCountis the maximum number of unique values of the geometry index for each cluster or cluster template. -
maxClusterTriangleCountis the maximum number of triangles in a cluster or cluster template. -
maxClusterVertexCountis the maximum number of unique vertices in the cluster’s index buffer. -
maxTotalTriangleCountis the sum of all triangles across all clusters or cluster templates. -
maxTotalVertexCountis the maximum number of vertices across all clusters or cluster templates. -
minPositionTruncateBitCountis the least value specified in cluster build in VkClusterAccelerationStructureBuildTriangleClusterInfoNV::positionTruncateBitCountor cluster template build in VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::positionTruncateBitCount.
The VkClusterAccelerationStructureMoveObjectsInputNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureMoveObjectsInputNV {
VkStructureType sType;
void* pNext;
VkClusterAccelerationStructureTypeNV type;
VkBool32 noMoveOverlap;
VkDeviceSize maxMovedBytes;
} VkClusterAccelerationStructureMoveObjectsInputNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
typeis a VkClusterAccelerationStructureTypeNV value identifying the type of cluster acceleration structure. -
noMoveOverlapspecifies if the source and destination cluster acceleration structures overlap in memory for the move operation. If set toVK_TRUE, the source cluster acceleration structure remains valid after the move and move operation acts like a copy. -
maxMovedBytesis the maximum number of bytes that may be moved in this operation.
Values which can be set in VkClusterAccelerationStructureTypeNV are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureTypeNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_CLUSTERS_BOTTOM_LEVEL_NV = 0,
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_NV = 1,
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_TEMPLATE_NV = 2,
} VkClusterAccelerationStructureTypeNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_CLUSTERS_BOTTOM_LEVEL_NVindicates a bottom level cluster acceleration structure. -
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_NVspecifies a cluster acceleration structure. -
VK_CLUSTER_ACCELERATION_STRUCTURE_TYPE_TRIANGLE_CLUSTER_TEMPLATE_NVindicates a template cluster acceleration structure.
To build or move a cluster acceleration structure or a cluster acceleration structure template call:
// Provided by VK_NV_cluster_acceleration_structure
void vkCmdBuildClusterAccelerationStructureIndirectNV(
VkCommandBuffer commandBuffer,
const VkClusterAccelerationStructureCommandsInfoNV* pCommandInfos);-
commandBufferis the command buffer into which the command is recorded. -
pCommandInfosis a pointer to a VkClusterAccelerationStructureCommandsInfoNV structure containing parameters required for building or moving the cluster acceleration structure.
Similar to vkCmdBuildAccelerationStructuresKHR, this command may
initiate multiple acceleration structures builds and there is no ordering or
synchronization implied between any of the individual acceleration structure
builds.
Accesses to the acceleration structure scratch memory as identified by the
VkClusterAccelerationStructureCommandsInfoNV::scratchData must
be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
(VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData,
VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray
and VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray
must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR.
Accesses to memory with input data as identified by any used values of
VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray,
VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount and
VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags
must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_INDIRECT_COMMAND_READ_BIT.
The VkClusterAccelerationStructureCommandsInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureCommandsInfoNV {
VkStructureType sType;
void* pNext;
VkClusterAccelerationStructureInputInfoNV input;
VkDeviceAddress dstImplicitData;
VkDeviceAddress scratchData;
VkStridedDeviceAddressRegionKHR dstAddressesArray;
VkStridedDeviceAddressRegionKHR dstSizesArray;
VkStridedDeviceAddressRegionKHR srcInfosArray;
VkDeviceAddress srcInfosCount;
VkClusterAccelerationStructureAddressResolutionFlagsNV addressResolutionFlags;
} VkClusterAccelerationStructureCommandsInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inputis VkClusterAccelerationStructureInputInfoNV structure describing the build or move parameters for the cluster acceleration structure. -
dstImplicitDatais the device address for memory where the implicit build of cluster acceleration structure will be saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NVorVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, this value is ignored. -
scratchDatais the device address of scratch memory that will be used during cluster acceleration structure move or build. -
dstAddressesArrayis a VkStridedDeviceAddressRegionKHR where the individual addresses and stride of moved or built cluster acceleration structures will be saved or read from depending on VkClusterAccelerationStructureInputInfoNV::opMode. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NVand the address indstAddressesArrayis not0, then the addresses are saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, then the addresses are read from. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_COMPUTE_SIZES_NV, then this value is ignored and may be0. -
dstSizesArrayisNULLor a VkStridedDeviceAddressRegionKHR containing sizes of moved or built cluster acceleration structures. Similar todstAddressesArray, if VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_IMPLICIT_DESTINATIONS_NV, then the sizes are saved. If VkClusterAccelerationStructureInputInfoNV::opModeisVK_CLUSTER_ACCELERATION_STRUCTURE_OP_MODE_EXPLICIT_DESTINATIONS_NV, then the sizes are read from. -
srcInfosArrayis a VkStridedDeviceAddressRegionKHR where input data for the build or move operation is read from. If the stride is0, the structures are assumed to be packed tightly. Its format is dependent on VkClusterAccelerationStructureInputInfoNV::opTypeas per the table below.
|
Format of |
|
|
|
VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV |
|
|
|
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV |
|
-
srcInfosCountis the device address of memory containing the count of number of build or move operations to perform. The actual value is the minimum of this value and the value specified ininput::maxAccelerationStructureCount. If this value is0, the count is determined byinput::maxAccelerationStructureCountalone. -
addressResolutionFlagsis a bitmask of VkClusterAccelerationStructureAddressResolutionFlagBitsNV values specifying how an implementation will interpret the device addresses in this structure.
Bits which can be set in
VkClusterAccelerationStructureCommandsInfoNV::addressResolutionFlags,
specifying how the device address in
VkClusterAccelerationStructureCommandsInfoNV are interpreted, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureAddressResolutionFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NV = 0x00000004,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_SIZES_ARRAY_BIT_NV = 0x00000008,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NV = 0x00000010,
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_COUNT_BIT_NV = 0x00000020,
} VkClusterAccelerationStructureAddressResolutionFlagBitsNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_IMPLICIT_DATA_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstImplicitData. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SCRATCH_DATA_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::scratchData. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_ADDRESS_ARRAY_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstAddressesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_DST_SIZES_ARRAY_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::dstSizesArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_ARRAY_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::srcInfosArray. -
VK_CLUSTER_ACCELERATION_STRUCTURE_ADDRESS_RESOLUTION_INDIRECTED_SRC_INFOS_COUNT_BIT_NVindicates another level of indirection when reading VkClusterAccelerationStructureCommandsInfoNV::srcInfosCount.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureAddressResolutionFlagsNV;VkClusterAccelerationStructureAddressResolutionFlagsNV is a bitmask
type for setting a mask of zero or more
VkClusterAccelerationStructureAddressResolutionFlagBitsNV.
The VkClusterAccelerationStructureMoveObjectsInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureMoveObjectsInfoNV {
VkDeviceAddress srcAccelerationStructure;
} VkClusterAccelerationStructureMoveObjectsInfoNV;-
srcAccelerationStructureis the device address of the source cluster acceleration structure that will be moved.
The VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV {
uint32_t clusterReferencesCount;
uint32_t clusterReferencesStride;
VkDeviceAddress clusterReferences;
} VkClusterAccelerationStructureBuildClustersBottomLevelInfoNV;-
clusterReferencesCountis the number of clusters this bottom level acceleration structure will be built from. -
clusterReferencesStrideis the stride inclusterReferences. -
clusterReferencesis the device memory containing the address of the clusters.
Bits which can be set in
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV::geometryFlags,
specifying geometry flags for cluster acceleration structure, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureGeometryFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_CULL_DISABLE_BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_NO_DUPLICATE_ANYHIT_INVOCATION_BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_OPAQUE_BIT_NV = 0x00000004,
} VkClusterAccelerationStructureGeometryFlagBitsNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_CULL_DISABLE_BIT_NVdisables face culling for this geometry. -
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_NO_DUPLICATE_ANYHIT_INVOCATION_BIT_NVindicates that the implementation must only call the any-hit shader a single time for each primitive in this geometry. If this bit is absent an implementation may invoke the any-hit shader more than once for this geometry. -
VK_CLUSTER_ACCELERATION_STRUCTURE_GEOMETRY_OPAQUE_BIT_NVspecifies that this geometry does not invoke the any-hit shaders even if present in a hit group.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureGeometryFlagsNV;VkClusterAccelerationStructureGeometryFlagsNV is a bitmask type for
setting a mask of zero or more
VkClusterAccelerationStructureGeometryFlagBitsNV.
The VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV {
uint32_t geometryIndex:24;
uint32_t reserved:5;
uint32_t geometryFlags:3;
} VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV;-
geometryIndexspecifies the geometry index for all triangles in the cluster acceleration structure. -
reservedis reserved for future use. -
geometryFlagsis a bitmask of VkClusterAccelerationStructureGeometryFlagBitsNV values describing geometry flags for the cluster acceleration structure.
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 the following:
-
geometryIndex,reservedandmaskoccupy the same memory as if a singleuint32_twas specified in their place-
geometryIndexoccupies the 24 least significant bits of that memory -
geometryFlagsoccupies the 3 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.
Bits which can be set in
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::clusterFlags,
specifying flags for clusters in an acceleration structure, are:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureClusterFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_CLUSTER_ALLOW_DISABLE_OPACITY_MICROMAPS_NV = 0x00000001,
} VkClusterAccelerationStructureClusterFlagBitsNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_CLUSTER_ALLOW_DISABLE_OPACITY_MICROMAPS_NVindicates that the specified cluster acceleration structure may be referenced in an instance withVK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXTset.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureClusterFlagsNV;VkClusterAccelerationStructureClusterFlagsNV is a bitmask type for
setting a mask of zero or more
VkClusterAccelerationStructureClusterFlagBitsNV.
The VkClusterAccelerationStructureBuildTriangleClusterInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildTriangleClusterInfoNV {
uint32_t clusterID;
VkClusterAccelerationStructureClusterFlagsNV clusterFlags;
uint32_t triangleCount:9;
uint32_t vertexCount:9;
uint32_t positionTruncateBitCount:6;
uint32_t indexType:4;
uint32_t opacityMicromapIndexType:4;
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV baseGeometryIndexAndGeometryFlags;
uint16_t indexBufferStride;
uint16_t vertexBufferStride;
uint16_t geometryIndexAndFlagsBufferStride;
uint16_t opacityMicromapIndexBufferStride;
VkDeviceAddress indexBuffer;
VkDeviceAddress vertexBuffer;
VkDeviceAddress geometryIndexAndFlagsBuffer;
VkDeviceAddress opacityMicromapArray;
VkDeviceAddress opacityMicromapIndexBuffer;
} VkClusterAccelerationStructureBuildTriangleClusterInfoNV;-
clusterIDis a user specified identifier assigned to this cluster. -
clusterFlagsis a bitmask of VkClusterAccelerationStructureClusterFlagBitsNV values describing flags how the cluster should be built. -
triangleCountis the number of triangles in this cluster. -
vertexCountis the number of unique vertices in this cluster. -
positionTruncateBitCountis the number of bits starting at the lowest bit (i.e. the LSBs of the mantissa), of each vertex position that will be truncated to zero to improve floating-point compression. -
indexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inindexBuffer. -
opacityMicromapIndexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inopacityMicromapIndexBuffer. -
baseGeometryIndexAndGeometryFlagsis a VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV value specifying the base geometry index and flags for all triangles in the cluster. -
indexBufferStrideis the stride in bytes inindexBufferwith0meaning the values are tightly-packed. -
vertexBufferStrideis the stride in bytes invertexBufferwith0meaning the values are tightly-packed. -
geometryIndexAndFlagsBufferStrideis the stride in bytes ingeometryIndexAndFlagsBufferwith0meaning the values are tightly-packed. -
opacityMicromapIndexBufferStrideis the stride in bytes inopacityMicromapIndexBufferwith0meaning the values are tightly-packed. -
indexBuffercontains the indices of vertices in the cluster and is of typeindexType. -
vertexBufferspecifies the vertex data of the triangles in the cluster with format specified in VkClusterAccelerationStructureTriangleClusterInputNV::vertexFormat. -
geometryIndexAndFlagsBufferis eitherNULLor an address containing strided VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV values specifying the geometry index and flag for every triangle in the cluster. -
opacityMicromapArrayis eitherNULLor specifies the address of a valid opacity micromap array to reference from the cluster acceleration structure. If it isNULL, then opacity micromaps will be disabled for this cluster acceleration structure. -
opacityMicromapIndexBufferis eitherNULLor specifies the address of a strided array with size equal to the number of triangles or indices into the opacity micromap array.
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 the following:
-
triangleCount,vertexCount,positionTruncateBitCount,indexTypeandopacityMicromapIndexTypeoccupy the same memory as if a singleuint32_twas specified in their place-
triangleCountoccupies the 9 least significant bits of that memory -
vertexCountoccupies the next 9 least significant bits of that memory -
positionTruncateBitCountoccupies the next 6 least significant bits of that memory -
indexTypeoccupies the next 4 least significant bits of that memory -
opacityMicromapIndexTypeoccupies the 4 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.
Bits that can be set in
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::indexType,
VkClusterAccelerationStructureBuildTriangleClusterInfoNV::opacityMicromapIndexType,
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::indexType
and
VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV::opacityMicromapIndexType
specifying the index type is one of:
// Provided by VK_NV_cluster_acceleration_structure
typedef enum VkClusterAccelerationStructureIndexFormatFlagBitsNV {
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_8BIT_NV = 0x00000001,
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_16BIT_NV = 0x00000002,
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_32BIT_NV = 0x00000004,
} VkClusterAccelerationStructureIndexFormatFlagBitsNV;-
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_8BIT_NVspecifies that 8-bit indices will be used. -
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_16BIT_NVspecifies that 16-bit indices will be used. -
VK_CLUSTER_ACCELERATION_STRUCTURE_INDEX_FORMAT_32BIT_NVspecifies that 32-bit indices will be used.
// Provided by VK_NV_cluster_acceleration_structure
typedef VkFlags VkClusterAccelerationStructureIndexFormatFlagsNV;VkClusterAccelerationStructureIndexFormatFlagsNV is a bitmask type for
setting a single VkClusterAccelerationStructureIndexFormatFlagBitsNV.
The VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV {
uint32_t clusterID;
VkClusterAccelerationStructureClusterFlagsNV clusterFlags;
uint32_t triangleCount:9;
uint32_t vertexCount:9;
uint32_t positionTruncateBitCount:6;
uint32_t indexType:4;
uint32_t opacityMicromapIndexType:4;
VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV baseGeometryIndexAndGeometryFlags;
uint16_t indexBufferStride;
uint16_t vertexBufferStride;
uint16_t geometryIndexAndFlagsBufferStride;
uint16_t opacityMicromapIndexBufferStride;
VkDeviceAddress indexBuffer;
VkDeviceAddress vertexBuffer;
VkDeviceAddress geometryIndexAndFlagsBuffer;
VkDeviceAddress opacityMicromapArray;
VkDeviceAddress opacityMicromapIndexBuffer;
VkDeviceAddress instantiationBoundingBoxLimit;
} VkClusterAccelerationStructureBuildTriangleClusterTemplateInfoNV;-
clusterIDis a user specified identifier assigned to this cluster template. -
clusterFlagsis a bitmask of VkClusterAccelerationStructureClusterFlagBitsNV values describing flags how the cluster template should be built. -
triangleCountis the number of triangles in this cluster. -
vertexCountis the number of unique vertices in this cluster. -
positionTruncateBitCountis the number of bits starting at the lowest bit (i.e. the LSBs of the mantissa), of each vertex position that will be truncated to zero to improve floating-point compression. -
indexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inindexBuffer. -
opacityMicromapIndexTypeis a single VkClusterAccelerationStructureIndexFormatFlagBitsNV value specifying the index type inopacityMicromapIndexBuffer. -
baseGeometryIndexAndGeometryFlagsis a VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV value specifying the base geometry index and flags for all triangles in the cluster template. -
indexBufferStrideis the stride in bytes inindexBuffer. -
vertexBufferStrideis the stride in bytes invertexBuffer. -
geometryIndexAndFlagsBufferStrideis the stride in bytes ingeometryIndexAndFlagsBuffer. -
opacityMicromapIndexBufferStrideis the stride in bytes inopacityMicromapIndexBuffer. -
indexBuffercontains the indices of vertices in the cluster and is of typeindexType. -
vertexBufferis eitherNULLor specifies the vertex data of the triangles in the cluster template with format specified in VkClusterAccelerationStructureTriangleClusterInputNV::vertexFormat. -
geometryIndexAndFlagsBufferis eitherNULLor an address containing strided VkClusterAccelerationStructureGeometryIndexAndGeometryFlagsNV values specifying the geometry index and flag for every triangle in the cluster. -
opacityMicromapArrayis eitherNULLor specifies the address of a valid opacity micromap array to reference from the cluster acceleration structure. If it isNULL, then opacity micromaps will be disabled for this cluster acceleration structure. -
opacityMicromapIndexBufferis eitherNULLor specifies the address of a strided array with size equal to the number of triangles or indices into the opacity micromap array. -
instantiationBoundingBoxLimitis eitherNULLor specifies the address of a bounding box within which all instantiated clusters must lie. The bounding box is specified by six 32-bit floating-point values in the order MinX, MinY, MinZ, MaxX, MaxY, MaxZ.
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 the following:
-
triangleCount,vertexCount,positionTruncateBitCount,indexTypeandopacityMicromapIndexTypeoccupy the same memory as if a singleuint32_twas specified in their place-
triangleCountoccupies the 9 least significant bits of that memory -
vertexCountoccupies the next 9 least significant bits of that memory -
positionTruncateBitCountoccupies the next 6 least significant bits of that memory -
indexTypeoccupies the next 4 least significant bits of that memory -
opacityMicromapIndexTypeoccupies the 4 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.
Cluster templates cannot be directly used to build bottom level acceleration structures, instead, they must be instantiated into CLAS objects.
The VkClusterAccelerationStructureInstantiateClusterInfoNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkClusterAccelerationStructureInstantiateClusterInfoNV {
uint32_t clusterIdOffset;
uint32_t geometryIndexOffset:24;
uint32_t reserved:8;
VkDeviceAddress clusterTemplateAddress;
VkStridedDeviceAddressNV vertexBuffer;
} VkClusterAccelerationStructureInstantiateClusterInfoNV;-
clusterIdOffsetis an unsigned offset applied to theclusterIDvalue stored in the cluster template. -
geometryIndexOffsetis a signed offset applied to the geometry index of each triangle. -
reservedis reserved for future use. -
clusterTemplateAddressis the address of a previously built cluster template. -
vertexBufferis eitherNULLor a VkStridedDeviceAddressNV structure containing the vertex data for the indexed triangles stored in the cluster template.
The VkStridedDeviceAddressNV structure is defined as:
// Provided by VK_NV_cluster_acceleration_structure
typedef struct VkStridedDeviceAddressNV {
VkDeviceAddress startAddress;
VkDeviceSize strideInBytes;
} VkStridedDeviceAddressNV;-
startAddressis the device address (as returned by the vkGetBufferDeviceAddress command) at which the region starts, or zero if the region is unused. -
strideInBytesis the byte stride between consecutive elements. Only the bottom 32 bits are used. The field is 64 bits to ensure consistent alignment across all containing structures.
Partitioned Top Level Acceleration Structures
Partitioned Top Level Acceleration Structures (PTLAS) allow efficient reuse of previously constructed sections of the top level acceleration structure by eliminating a full rebuild when only a few instances are modified. This reduces build times and supports handling a higher number of instances, making it more suitable for large and complex scenes.
PTLAS organizes instances into partitions, enabling a two-stage build process: first, it constructs an acceleration structure for each partition by grouping the instances within it, and second, it combines these partition structures into a single acceleration structure, similar to the current top-level acceleration structure.
To maintain compatibility, PTLAS behaves identically to the current top-level acceleration structure from the perspective of ray tracing shaders and pipelines.
PTLAS includes a unique global partition that operates independently of other partitions. Instances can be assigned to this global partition just like they would to regular partitions. The global partition is well-suited for frequently updated instances, such as animated characters. During the build process, instances in the global partition are treated as if they belong to individual partitions, without increasing the maximum partition count. However, instances in the global partition may still impact build performance. Once these instances become stable, they should be moved to a spatially optimized, non-global partition to lower build costs and minimize trace performance issues.
To handle large worlds requiring more precision than 32-bit floating-point
numbers offer, PTLAS offers efficient partition translation.
Typically, applications maintain precision by placing the world center near
the camera.
Partition translation allows an additional translation of instances during
construction without changing their stored transforms.
This method stores instance transforms relative to partitions, applying a
translation to achieve accurate world positions.
Higher precision is maintained using smaller floating-point numbers until
the structure is built.
World space coordinates can also be updated efficiently without rebuilding
the entire PTLAS.
Partition translation requires extra memory for untranslated instance
transforms and must be explicitly enabled with
VkPartitionedAccelerationStructureFlagsNV::enablePartitionTranslation
flag.
To determine the memory requirements for a PTAS, call:
// Provided by VK_NV_partitioned_acceleration_structure
void vkGetPartitionedAccelerationStructuresBuildSizesNV(
VkDevice device,
const VkPartitionedAccelerationStructureInstancesInputNV* pInfo,
VkAccelerationStructureBuildSizesInfoKHR* pSizeInfo);-
deviceis the logical device that owns the acceleration structure. -
pInfois a pointer to a VkPartitionedAccelerationStructureInstancesInputNV structure containing parameters required for the memory requirements query. -
pSizeInfois a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and the sizes required for the scratch buffers, given the build parameters.
The VkPartitionedAccelerationStructureInstancesInputNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureInstancesInputNV {
VkStructureType sType;
void* pNext;
VkBuildAccelerationStructureFlagsKHR flags;
uint32_t instanceCount;
uint32_t maxInstancePerPartitionCount;
uint32_t partitionCount;
uint32_t maxInstanceInGlobalPartitionCount;
} VkPartitionedAccelerationStructureInstancesInputNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
flagsis a bitmask of VkBuildAccelerationStructureFlagsKHR specifying flags for the PTLAS build operation. -
instanceCountis the number of instances in this PTLAS. -
maxInstancePerPartitionCountis the maximum number of instances per partition in the PTLAS. -
partitionCountis the number of partitions in the PTLAS. -
maxInstanceInGlobalPartitionCountis maximum number of instances in the global partition.
If the pNext chain includes a
VkPartitionedAccelerationStructureFlagsNV structure, then that
structure specifies additional flags for the PTLAS.
The VkPartitionedAccelerationStructureFlagsNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureFlagsNV {
VkStructureType sType;
void* pNext;
VkBool32 enablePartitionTranslation;
} VkPartitionedAccelerationStructureFlagsNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
enablePartitionTranslationspecifies if a partition translation may be applied with VkPartitionedAccelerationStructureWritePartitionTranslationDataNV.
To build a partitioned top level acceleration structure, call:
// Provided by VK_NV_partitioned_acceleration_structure
void vkCmdBuildPartitionedAccelerationStructuresNV(
VkCommandBuffer commandBuffer,
const VkBuildPartitionedAccelerationStructureInfoNV* pBuildInfo);-
commandBufferis the command buffer into which the command is recorded. -
pBuildInfois a pointer to a VkBuildPartitionedAccelerationStructureInfoNV structure containing parameters required for building a PTLAS.
Accesses to the acceleration structure scratch memory as identified by the
VkBuildPartitionedAccelerationStructureInfoNV::scratchData must
be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
(VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR |
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR).
Accesses to each
VkBuildPartitionedAccelerationStructureInfoNV::srcAccelerationStructureData
and
VkBuildPartitionedAccelerationStructureInfoNV::dstAccelerationStructureData
must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or
VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, as appropriate.
Accesses to memory with input data as identified by any used values of
VkBuildPartitionedAccelerationStructureInfoNV::srcInfos and
VkBuildPartitionedAccelerationStructureInfoNV::srcInfosCount
must be synchronized with the
VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR
pipeline stage and an
access type of
VK_ACCESS_INDIRECT_COMMAND_READ_BIT.
The VkBuildPartitionedAccelerationStructureInfoNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkBuildPartitionedAccelerationStructureInfoNV {
VkStructureType sType;
void* pNext;
VkPartitionedAccelerationStructureInstancesInputNV input;
VkDeviceAddress srcAccelerationStructureData;
VkDeviceAddress dstAccelerationStructureData;
VkDeviceAddress scratchData;
VkDeviceAddress srcInfos;
VkDeviceAddress srcInfosCount;
} VkBuildPartitionedAccelerationStructureInfoNV;-
sTypeis a VkStructureType value identifying this structure. -
pNextisNULLor a pointer to a structure extending this structure. -
inputis a VkPartitionedAccelerationStructureInstancesInputNV structure describing the instance and partition count information in the PTLAS. -
srcAccelerationStructureDataisNULLor an address of a previously built PTLAS. If non-NULL, the PTLAS stored at this address is used as a basis to create new PTLAS. -
dstAccelerationStructureDatais the address to store the built PTLAS. -
scratchDatais the device address of scratch memory that will be used during PTLAS build. -
srcInfosis the device address of an array of VkBuildPartitionedAccelerationStructureIndirectCommandNV structures describing the type of operation to perform. -
srcInfosCountis a device address containing the size ofsrcInfosarray.
Members srcAccelerationStructureData and
dstAccelerationStructureData may be the same or different.
If they are the same, the update happens in-place.
Otherwise, the destination acceleration structure is updated and the source
is not modified.
The VkBuildPartitionedAccelerationStructureIndirectCommandNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkBuildPartitionedAccelerationStructureIndirectCommandNV {
VkPartitionedAccelerationStructureOpTypeNV opType;
uint32_t argCount;
VkStridedDeviceAddressNV argData;
} VkBuildPartitionedAccelerationStructureIndirectCommandNV;-
opTypeis a VkPartitionedAccelerationStructureOpTypeNV describing the type of operation. -
argCountthe number of structures inargDataarray. -
argDatais an array of VkStridedDeviceAddressNV structures containing the write or update data for instances and partitions in the PTLAS. The structure is dependent onopTypeas shown in the table below.
|
Format of |
|
|
|
|
|
VkPartitionedAccelerationStructureWritePartitionTranslationDataNV |
Values which can be set in VkPartitionedAccelerationStructureOpTypeNV are:
// Provided by VK_NV_partitioned_acceleration_structure
typedef enum VkPartitionedAccelerationStructureOpTypeNV {
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_INSTANCE_NV = 0,
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_UPDATE_INSTANCE_NV = 1,
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_PARTITION_TRANSLATION_NV = 2,
} VkPartitionedAccelerationStructureOpTypeNV;-
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_INSTANCE_NVis used to assign a transformed bottom level acceleration structure to an instance and partition. This is similar to VkAccelerationStructureInstanceKHR that defines the properties and transformations for a single instance in non-partitioned TLAS. Any partition that contains at least one of the affected instances will have their internal acceleration structure rebuilt. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_UPDATE_INSTANCE_NVindicates that an instance will be updated with a new bottom level acceleration structure. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_OP_TYPE_WRITE_PARTITION_TRANSLATION_NVindicates that a partition will be assigned a translation vector.
The VkPartitionedAccelerationStructureWriteInstanceDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureWriteInstanceDataNV {
VkTransformMatrixKHR transform;
float explicitAABB[6];
uint32_t instanceID;
uint32_t instanceMask;
uint32_t instanceContributionToHitGroupIndex;
VkPartitionedAccelerationStructureInstanceFlagsNV instanceFlags;
uint32_t instanceIndex;
uint32_t partitionIndex;
VkDeviceAddress accelerationStructure;
} VkPartitionedAccelerationStructureWriteInstanceDataNV;-
transformis a VkTransformMatrixKHR structure describing the transformation to be applied to the instance in PTLAS. -
explicitAABBspecifies an axis aligned bounding box representing the maximum extent of any vertex within the used acceleration structure after applying the instance-to-world transformation. The partition translation is not applied to the bounding box. -
instanceIDis a user specified constant assigned to an instance in the PTLAS. -
instanceMaskis a 8-bit mask assigned to the instance that may be used to include or reject group of instances. -
instanceContributionToHitGroupIndexis a 24-bit per application specified instance value added in the indexing into the shader binding table to fetch the hit group to use. -
instanceFlagis a bitmask of VkPartitionedAccelerationStructureInstanceFlagsNV specifying flags an instance in the PTLAS. -
instanceIndexis the index of the instance within the PTLAS. -
partitionIndexis the index of the partition to which this instance belongs. Global partitions are referred to byVK_PARTITIONED_ACCELERATION_STRUCTURE_PARTITION_INDEX_GLOBAL_NV. -
accelerationStructureis the device address of the bottom level acceleration structure or a clustered bottom level acceleration structure that is being instanced. This instance is disabled if the device address is0.
The VkPartitionedAccelerationStructureUpdateInstanceDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureUpdateInstanceDataNV {
uint32_t instanceIndex;
uint32_t instanceContributionToHitGroupIndex;
VkDeviceAddress accelerationStructure;
} VkPartitionedAccelerationStructureUpdateInstanceDataNV;-
instanceIndexis the index of the instance being updated. -
instanceContributionToHitGroupIndexis a 24-bit per instance value added in the indexing into the shader binding table to fetch the hit group to use. -
accelerationStructureis the device address of the bottom level acceleration structure or a clustered bottom level acceleration structure whose instance is being updated. The instance is disabled if the device address is0.
If the instance was originally disabled by specifying a 0 in
VkPartitionedAccelerationStructureWriteInstanceDataNV::accelerationStructure,
it can not be updated to a new acceleration structure as the instance may
have been permanently disabled by the implementation.
To avoid a refit, the new acceleration structure must be within the
bounding box specified by
VkPartitionedAccelerationStructureWriteInstanceDataNV::explicitAABB
when the instance was first created.
Bits which can be set in
VkPartitionedAccelerationStructureWriteInstanceDataNV::instanceFlags,
specifying flags for instances, are:
// Provided by VK_NV_partitioned_acceleration_structure
typedef enum VkPartitionedAccelerationStructureInstanceFlagBitsNV {
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FACING_CULL_DISABLE_BIT_NV = 0x00000001,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FLIP_FACING_BIT_NV = 0x00000002,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_OPAQUE_BIT_NV = 0x00000004,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_NO_OPAQUE_BIT_NV = 0x00000008,
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_ENABLE_EXPLICIT_BOUNDING_BOX_NV = 0x00000010,
} VkPartitionedAccelerationStructureInstanceFlagBitsNV;-
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FACING_CULL_DISABLE_BIT_NVdisables face culling for this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_TRIANGLE_FLIP_FACING_BIT_NVindicates that the facing determination for geometry in this instance is inverted. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_OPAQUE_BIT_NVcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere specified on all geometries referenced by this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_FORCE_NO_OPAQUE_BIT_NVcauses this instance to act as thoughVK_GEOMETRY_OPAQUE_BIT_KHRwere not specified on all geometries referenced by this instance. -
VK_PARTITIONED_ACCELERATION_STRUCTURE_INSTANCE_FLAG_ENABLE_EXPLICIT_BOUNDING_BOX_NVenables use of an explicit bounding box for this instance.
// Provided by VK_NV_partitioned_acceleration_structure
typedef VkFlags VkPartitionedAccelerationStructureInstanceFlagsNV;VkPartitionedAccelerationStructureInstanceFlagsNV is a bitmask type
for setting a mask of zero or more
VkPartitionedAccelerationStructureInstanceFlagBitsNV.
The VkPartitionedAccelerationStructureWritePartitionTranslationDataNV structure is defined as:
// Provided by VK_NV_partitioned_acceleration_structure
typedef struct VkPartitionedAccelerationStructureWritePartitionTranslationDataNV {
uint32_t partitionIndex;
float partitionTranslation[3];
} VkPartitionedAccelerationStructureWritePartitionTranslationDataNV;-
partitionIndexis the index of partition to write. Global partition is referred to byVK_PARTITIONED_ACCELERATION_STRUCTURE_PARTITION_INDEX_GLOBAL_NV. -
partitionTranslationsets the translation vector for this partition. When tracing this partition, the contained instances will behave as if the partition translation was added to the translation component of the instance transform. This translation vector is also added to the instances in the partition that had their bounding box specified.
Host Acceleration Structure Operations
Implementations are also required to provide host implementations of the
acceleration structure operations if the
accelerationStructureHostCommands feature is enabled:
-
vkBuildAccelerationStructuresKHR corresponding to vkCmdBuildAccelerationStructuresKHR
-
vkCopyAccelerationStructureKHR corresponding to vkCmdCopyAccelerationStructureKHR
-
vkCopyAccelerationStructureToMemoryKHR corresponding to vkCmdCopyAccelerationStructureToMemoryKHR
-
vkCopyMemoryToAccelerationStructureKHR corresponding to vkCmdCopyMemoryToAccelerationStructureKHR
-
vkWriteAccelerationStructuresPropertiesKHR corresponding to vkCmdWriteAccelerationStructuresPropertiesKHR
These commands are functionally equivalent to their device counterparts, except that they are executed on the host timeline, rather than being enqueued into command buffers.
All acceleration structures used by the host commands must be bound to host-visible memory, and all input data for acceleration structure builds must be referenced using host addresses instead of device addresses. Applications are not required to map acceleration structure memory when using the host commands.
|
The vkBuildAccelerationStructuresKHR and vkCmdBuildAccelerationStructuresKHR may use different algorithms, and thus are not required to produce identical structures. The structures produced by these two commands may exhibit different memory footprints or traversal performance, but should strive to be similar where possible. Apart from these details, the host and device operations are interchangeable. For example, an application can use vkBuildAccelerationStructuresKHR to build a structure, compact it on the device using vkCmdCopyAccelerationStructureKHR, and serialize the result using vkCopyAccelerationStructureToMemoryKHR. |
|
For efficient execution, acceleration structures manipulated using these commands should always be bound to host cached memory, as the implementation may need to repeatedly read and write this memory during the execution of the command. |
To build acceleration structures on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkBuildAccelerationStructuresKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
uint32_t infoCount,
const VkAccelerationStructureBuildGeometryInfoKHR* pInfos,
const VkAccelerationStructureBuildRangeInfoKHR* const* ppBuildRangeInfos);-
deviceis theVkDevicefor which the acceleration structures are being built. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
infoCountis the number of acceleration structures to build. It specifies the number of thepInfosstructures andppBuildRangeInfospointers that must be provided. -
pInfosis a pointer to an array ofinfoCountVkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. -
ppBuildRangeInfosis a pointer to an array ofinfoCountpointers to arrays of VkAccelerationStructureBuildRangeInfoKHR structures. EachppBuildRangeInfos[i] is a pointer to an array ofpInfos[i].geometryCountVkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined bypInfos[i].
This command fulfills the same task as vkCmdBuildAccelerationStructuresKHR but is executed by the host.
The vkBuildAccelerationStructuresKHR command provides the ability to
initiate multiple acceleration structures builds, however there is no
ordering or synchronization implied between any of the individual
acceleration structure builds.
|
This means that an application cannot build a top-level acceleration structure in the same vkBuildAccelerationStructuresKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds. |
To copy or compact an acceleration structure on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyAccelerationStructureInfoKHR* pInfo);-
deviceis the device which owns the acceleration structures. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyAccelerationStructureInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyAccelerationStructureKHR but is executed by the host.
To copy host accessible memory to an acceleration structure, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyMemoryToAccelerationStructureKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyMemoryToAccelerationStructureInfoKHR* pInfo);-
deviceis the device which ownspInfo->dst. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host.
This command can accept acceleration structures produced by either vkCmdCopyAccelerationStructureToMemoryKHR or vkCopyAccelerationStructureToMemoryKHR.
To copy an acceleration structure to host accessible memory, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkCopyAccelerationStructureToMemoryKHR(
VkDevice device,
VkDeferredOperationKHR deferredOperation,
const VkCopyAccelerationStructureToMemoryInfoKHR* pInfo);-
deviceis the device which ownspInfo->src. -
deferredOperationis an optional VkDeferredOperationKHR to request deferral for this command. -
pInfois a pointer to a VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.
This command fulfills the same task as vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host.
This command produces the same results as vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either vkCmdCopyMemoryToAccelerationStructureKHR or vkCopyMemoryToAccelerationStructureKHR.
To query acceleration structure size parameters on the host, call:
// Provided by VK_KHR_acceleration_structure
VkResult vkWriteAccelerationStructuresPropertiesKHR(
VkDevice device,
uint32_t accelerationStructureCount,
const VkAccelerationStructureKHR* pAccelerationStructures,
VkQueryType queryType,
size_t dataSize,
void* pData,
size_t stride);-
deviceis the device which owns the acceleration structures inpAccelerationStructures. -
accelerationStructureCountis the count of acceleration structures for which to query the property. -
pAccelerationStructuresis a pointer to an array of existing previously built acceleration structures. -
queryTypeis a VkQueryType value specifying the property to be queried. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to an application-allocated buffer where the results will be written. -
strideis the stride in bytes between results for individual queries withinpData.
This command fulfills the same task as vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the host.