Vulkan-Docs/chapters/VK_NVX_raytracing/raytracing-resources.txt

// 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[]
--