359 lines
13 KiB
Plaintext
359 lines
13 KiB
Plaintext
// This section is included inside the Resources chapter (resources.txt)
|
|
|
|
[[resources-acceleration-structures]]
|
|
== Acceleration Structures
|
|
|
|
[open,refpage='VkAccelerationStructureNVX',desc='Opaque handle to an acceleration structure object',type='handles']
|
|
--
|
|
|
|
Acceleration structures are an opaque structure that can be built by the
|
|
implementation to more efficiently perform spatial queries on the provided
|
|
geometric data.
|
|
For this extension, an acceleration structure is either a top-level
|
|
acceleration structure containing a set of bottom-level acceleration
|
|
structures or a bottom-level acceleration structure containing either a set
|
|
of axis-aligned bounding boxes for custom geometry or a set of triangles.
|
|
|
|
Each instance in the top-level acceleration structure contains a reference
|
|
to a bottom-level acceleration structure as well as an instance transform
|
|
plus information required to index into the shader bindings.
|
|
The top-level acceleration structure is what is bound to the acceleration
|
|
descriptor to trace inside the shader in the raytracing pipeline.
|
|
|
|
Acceleration structures are represented by sname:VkAccelerationStructureNVX
|
|
handles:
|
|
|
|
include::../../api/handles/VkAccelerationStructureNVX.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateAccelerationStructureNVX',desc='Create a new acceleration structure object',type='protos']
|
|
--
|
|
|
|
To create acceleration structures, call:
|
|
|
|
include::../../api/protos/vkCreateAccelerationStructureNVX.txt[]
|
|
|
|
* pname:device is the logical device that creates the buffer object.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname:VkAccelerationStructureCreateInfoNVX structure containing
|
|
parameters affecting creation of the acceleration structure.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pAccelerationStructure points to a
|
|
sname:VkAccelerationStructureNVX handle in which the resulting
|
|
acceleration structure object is returned.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/protos/vkCreateAccelerationStructureNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkAccelerationStructureCreateInfoNVX',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs']
|
|
--
|
|
|
|
The sname:VkAccelerationStructureCreateInfoNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkAccelerationStructureCreateInfoNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:type is a ename:VkAccelerationStructureTypeBitsNVX value that
|
|
specifies the type of acceleration structure that will be created.
|
|
* pname:flags is a set of ename:VkBuildAccelerationStructureFlagBitsNVX
|
|
values that specify additional parameters of the acceleration structure.
|
|
* pname:compactedSize is the size from the result of
|
|
flink:vkCmdWriteAccelerationStructurePropertiesNVX, if this acceleration
|
|
structure is going to be the target of compacting copy.
|
|
* pname:instanceCount specifies the number of instances that will be in
|
|
the new acceleration structure
|
|
* pname:geometryCount specifies the number of geometries that will be in
|
|
the new acceleration structure
|
|
* pname:pGeometries is an array of ename:VkGeometryNVX structures which
|
|
contain the scene data being passed into the acceleration structure.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkAccelerationStructureCreateInfoNVX-geometryCount-02239]]
|
|
pname:geometryCount must: be less than or equal to
|
|
sname:VkPhysicalDeviceRaytracingPropertiesNVX::pname:maxGeometryCount
|
|
****
|
|
|
|
include::../../validity/structs/VkAccelerationStructureCreateInfoNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGeometryNVX',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs']
|
|
--
|
|
|
|
The sname:VkGeometryNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkGeometryNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:geometryType describes which type of geometry this VkGeometryNVX
|
|
refers to.
|
|
* pname:geometry contains the geometry data.
|
|
* pname:flags has flags describing options for this geometry.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkGeometryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGeometryTypeNVX',desc='Enum specifying which type of geometry is provided',type='enums']
|
|
--
|
|
|
|
Geometry types are specified by elink:VkGeometryTypeNVX, which takes values:
|
|
|
|
include::../../api/enums/VkGeometryTypeNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGeometryFlagBitsNVX',desc='Bitmask specifying additional parameters for a geometry',type='enums']
|
|
--
|
|
|
|
Bits which can: be set in slink:VkGeometryNVX::pname:flags, specifying
|
|
additional parameters for acceleration structure builds, are:
|
|
|
|
include::../../api/enums/VkGeometryFlagBitsNVX.txt[]
|
|
|
|
--
|
|
|
|
|
|
[open,refpage='VkGeometryDataNVX',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs']
|
|
--
|
|
|
|
The sname:VkGeometryDataNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkGeometryDataNVX.txt[]
|
|
|
|
* pname:triangles contains triangle data if pname:geometryType is
|
|
ename:VK_GEOMETRY_TYPE_TRIANGLES_NVX.
|
|
* pname:aabbs contains axis-aligned bounding box data if
|
|
pname:geometryType is ename:VK_GEOMETRY_TYPE_AABBS_NVX.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkGeometryDataNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGeometryTrianglesNVX',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs']
|
|
--
|
|
|
|
The sname:VkGeometryTrianglesNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkGeometryTrianglesNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:vertexData is the buffer containing vertex data.
|
|
* pname:vertexOffset is the offset within pname:vertexData containing
|
|
vertex data.
|
|
* pname:vertexCount is the number of valid vertices.
|
|
* pname:vertexStride is the stride in bytes between each vertex.
|
|
* pname:vertexFormat is the format of each vertex element.
|
|
* pname:indexData is the buffer containing index data.
|
|
* pname:indexOffset is the offset within pname:indexData containing index
|
|
data.
|
|
* pname:indexCount is the number of indices to include in this geometry.
|
|
* pname:indexType is the format of each index.
|
|
* pname:transformData is a buffer containing optional reference to an
|
|
array of floats representing a 3x4 row major affine transformation
|
|
matrix.
|
|
* pname:transformOffset is the offset in pname:transformData
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkGeometryTrianglesNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGeometryAABBNVX',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs']
|
|
--
|
|
|
|
The sname:VkGeometryAABBNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkGeometryAABBNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:aabbData is the buffer containing axis-aligned bounding box data
|
|
* pname:numAABBs is the number of AABBs in this geometry.
|
|
* pname:stride is the stride in bytes between AABBs in pname:aabbData.
|
|
* pname:offset is the offset in bytes of the first AABB in pname:aabbData.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkGeometryAABBNVX.txt[]
|
|
--
|
|
|
|
|
|
[open,refpage='vkDestroyAccelerationStructureNVX',desc='Destroy an acceleration structure object',type='protos']
|
|
--
|
|
|
|
To destroy an acceleration structure, call:
|
|
|
|
include::../../api/protos/vkDestroyAccelerationStructureNVX.txt[]
|
|
|
|
* pname:device is the logical device that destroys the buffer.
|
|
* pname:accelerationStructure is the acceleration structure to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/protos/vkDestroyAccelerationStructureNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetAccelerationStructureMemoryRequirementsNVX',desc='Get acceleration structure memory requirements',type='protos']
|
|
--
|
|
|
|
An acceleration structure has both its own memory use and the scratch memory
|
|
use required when building it.
|
|
|
|
To query the basic memory requirements call:
|
|
|
|
include::../../api/protos/vkGetAccelerationStructureMemoryRequirementsNVX.txt[]
|
|
|
|
* pname:device is the logical device on which the acceleration structure
|
|
was created.
|
|
* pname:pInfo specifies the acceleration structure to get memory
|
|
requirements for.
|
|
* pname:pMemoryRequirements returns the memory requirements.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/protos/vkGetAccelerationStructureMemoryRequirementsNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetAccelerationStructureScratchMemoryRequirementsNVX',desc='Get acceleration structure scratch memory requirements',type='protos']
|
|
--
|
|
|
|
To query the scratch memory requirements call:
|
|
|
|
include::../../api/protos/vkGetAccelerationStructureScratchMemoryRequirementsNVX.txt[]
|
|
|
|
* pname:device is the logical device on which the acceleration structure
|
|
was created.
|
|
* pname:pInfo specifies the acceleration structure to get scratch memory
|
|
requirements for.
|
|
* pname:pMemoryRequirements returns the memory requirements.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/protos/vkGetAccelerationStructureScratchMemoryRequirementsNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkAccelerationStructureMemoryRequirementsInfoNVX',desc='Structure specifying acceleration to query for memory requirements',type='structs']
|
|
--
|
|
The sname:VkAccelerationStructureMemoryRequirementsInfoNVX structure is
|
|
defined as:
|
|
|
|
include::../../api/structs/VkAccelerationStructureMemoryRequirementsInfoNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:accelerationStructure is the acceleration structure to be queried
|
|
for memory requirements.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkAccelerationStructureMemoryRequirementsInfoNVX.txt[]
|
|
--
|
|
|
|
|
|
[open,refpage='vkBindAccelerationStructureMemoryNVX',desc='Bind acceleration structure memory',type='protos']
|
|
--
|
|
|
|
To attach memory to one or more acceleration structures at a time, call:
|
|
|
|
include::../../api/protos/vkBindAccelerationStructureMemoryNVX.txt[]
|
|
|
|
* pname:device is the logical device that owns the acceleration structures
|
|
and memory.
|
|
* pname:bindInfoCount is the number of elements in pBindInfos.
|
|
* pname:pBindInfos is a pointer to an array of structures of type
|
|
slink:VkBindAccelerationStructureMemoryInfoNVX, describing images and
|
|
memory to bind.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/protos/vkBindAccelerationStructureMemoryNVX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindAccelerationStructureMemoryInfoNVX',desc='Structure specifying acceleration structure memory binding',type='structs']
|
|
--
|
|
The sname:VkBindAccelerationStructureMemoryInfoNVX structure is defined as:
|
|
|
|
include::../../api/structs/VkBindAccelerationStructureMemoryInfoNVX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:accelerationStructure is the acceleration structure to be attached
|
|
to memory.
|
|
* pname:memory is a VkDeviceMemory object describing the device memory to
|
|
attach.
|
|
* pname:memoryOffset is the start offset of the region of memory which is
|
|
to be bound to the acceleration structure.
|
|
The number of bytes returned in the slink:VkMemoryRequirements::size
|
|
member in memory, starting from pname:memoryOffset bytes, will be bound
|
|
to the specified acceleration structure.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
|
|
.Valid Usage
|
|
****
|
|
****
|
|
|
|
include::../../validity/structs/VkBindAccelerationStructureMemoryInfoNVX.txt[]
|
|
--
|
|
|
|
|
|
[open,refpage='vkGetAccelerationStructureHandleNVX',desc='Get opaque acceleration structure handle',type='protos']
|
|
--
|
|
|
|
To allow constructing geometry instances with device code if desired, we
|
|
need to be able to query a opaque handle for an acceleration structure.
|
|
This handle is a value of 8 bytes.
|
|
To get this handle, call:
|
|
|
|
include::../../api/protos/vkGetAccelerationStructureHandleNVX.txt[]
|
|
|
|
* pname:device is the logical device that owns the acceleration
|
|
structures.
|
|
* pname:accelerationStructure is the acceleration structur.
|
|
* pname:dataSize is the size in bytes of the buffer pointed to by
|
|
pname:pData.
|
|
* pname:pData is a pointer to a user-allocated buffer where the results
|
|
will be written
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetAccelerationStructureHandleNVX-dataSize-02240]]
|
|
pname:dataSize must: be large enough to contain the result of the query,
|
|
as described above
|
|
****
|
|
|
|
include::../../validity/protos/vkGetAccelerationStructureHandleNVX.txt[]
|
|
--
|