// This section is included inside the Resources chapter (resources.txt) [[resources-acceleration-structures]] == Acceleration Structures [open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] -- Acceleration structures are an opaque structure that is 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 ray tracing pipeline. Acceleration structures are represented by sname:VkAccelerationStructureNV handles: include::{generated}/api/handles/VkAccelerationStructureNV.txt[] -- [open,refpage='vkCreateAccelerationStructureNV',desc='Create a new acceleration structure object',type='protos'] -- To create acceleration structures, call: include::{generated}/api/protos/vkCreateAccelerationStructureNV.txt[] * pname:device is the logical device that creates the buffer object. * pname:pCreateInfo is a pointer to an instance of the sname:VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pAccelerationStructure points to a sname:VkAccelerationStructureNV handle in which the resulting acceleration structure object is returned. Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific "`shape`" as specified by the information in slink:VkAccelerationStructureInfoNV and pname:compactedSize in pname:pCreateInfo. Populating the data in the object after allocating and binding memory is done with flink:vkCmdBuildAccelerationStructureNV and flink:vkCmdCopyAccelerationStructureNV. Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures. include::{generated}/validity/protos/vkCreateAccelerationStructureNV.txt[] -- [open,refpage='VkAccelerationStructureCreateInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] -- The sname:VkAccelerationStructureCreateInfoNV structure is defined as: include::{generated}/api/structs/VkAccelerationStructureCreateInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:compactedSize is the size from the result of flink:vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy. * pname:info is the slink:VkAccelerationStructureInfoNV structure that specifies further parameters of the created acceleration structure. .Valid Usage **** * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] If pname:compactedSize is not `0` then both pname:info.geometryCount and pname:info.instanceCount must: be `0` **** include::{generated}/validity/structs/VkAccelerationStructureCreateInfoNV.txt[] -- [open,refpage='VkAccelerationStructureInfoNV',desc='Structure specifying the parameters of acceleration structure object',type='structs'] -- The sname:VkAccelerationStructureInfoNV structure is defined as: include::{generated}/api/structs/VkAccelerationStructureInfoNV.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 elink:VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created. * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure. * 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 slink:VkGeometryNV structures, which contain the scene data being passed into the acceleration structure. sname:VkAccelerationStructureInfoNV contains information that is used both for acceleration structure creation with fname:vkCreateAccelerationStructureNV and in combination with the actual geometric data to build the acceleration structure with flink:vkCmdBuildAccelerationStructureNV. .Valid Usage **** * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] pname:geometryCount must: be less than or equal to slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] pname:instanceCount must: be less than or equal to slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] The total number of triangles in all geometries must: be less than or equal to slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount * [[VUID-VkAccelerationStructureInfoNV-type-02425]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then pname:geometryCount must: be `0` * [[VUID-VkAccelerationStructureInfoNV-type-02426]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV then pname:instanceCount must: be `0` * [[VUID-VkAccelerationStructureInfoNV-flags-02592]] If pname:flags has the ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, then it must: not have the ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set **** include::{generated}/validity/structs/VkAccelerationStructureInfoNV.txt[] -- [open,refpage='VkAccelerationStructureTypeNV',desc='Type of acceleration structure',type='enums'] -- Values which can: be set in slink:VkAccelerationStructureInfoNV::pname:type, specifying the type of acceleration structure, are: include::{generated}/api/enums/VkAccelerationStructureTypeNV.txt[] * ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV is a top-level acceleration structure containing instance data referring to bottom-level level acceleration structures. * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV is a bottom-level acceleration structure containing the AABBs or geometry to be intersected. -- [open,refpage='VkBuildAccelerationStructureFlagBitsNV',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums'] -- Bits which can: be set in slink:VkAccelerationStructureInfoNV::pname:flags, specifying additional parameters for acceleration structure builds, are: include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsNV.txt[] * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV indicates that the specified acceleration structure can: be updated with pname:update of ename:VK_TRUE in flink:vkCmdBuildAccelerationStructureNV. * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV indicates that the specified acceleration structure can: act as the source for flink:vkCmdCopyAccelerationStructureNV with pname:mode of ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV to produce a compacted acceleration structure. * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV indicates that the given acceleration structure build should: prioritize trace performance over build time. * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV indicates that the given acceleration structure build should: prioritize build time over trace performance. * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV indicates that this acceleration structure should: minimize the size of the scratch memory and the final result build, potentially at the expense of build time or trace performance. [NOTE] .Note ==== ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV and ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV may: take more time and memory than a normal build, and so should: only be used when those features are used. ==== -- [open,refpage='VkBuildAccelerationStructureFlagsNV',desc='Bitmask of VkBuildAccelerationStructureFlagBitsNV',type='flags'] -- include::{generated}/api/flags/VkBuildAccelerationStructureFlagsNV.txt[] tname:VkBuildAccelerationStructureFlagsNV is a bitmask type for setting a mask of zero or more elink:VkBuildAccelerationStructureFlagBitsNV. -- [open,refpage='VkGeometryNV',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] -- The sname:VkGeometryNV structure is defined as: include::{generated}/api/structs/VkGeometryNV.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 sname:VkGeometryNV refers to. * pname:geometry contains the geometry data as described in slink:VkGeometryDataNV. * pname:flags has flags describing options for this geometry. include::{generated}/validity/structs/VkGeometryNV.txt[] -- [open,refpage='VkGeometryTypeNV',desc='Enum specifying which type of geometry is provided',type='enums'] -- Geometry types are specified by elink:VkGeometryTypeNV, which takes values: include::{generated}/api/enums/VkGeometryTypeNV.txt[] * ename:VK_GEOMETRY_TYPE_TRIANGLES_NV indicates that the pname:triangles of slink:VkGeometryDataNV contains valid data. * ename:VK_GEOMETRY_TYPE_AABBS_NV indicates that the pname:aabbs of slink:VkGeometryDataNV contains valid data. -- [open,refpage='VkGeometryFlagBitsNV',desc='Bitmask specifying additional parameters for a geometry',type='enums'] -- Bits which can: be set in slink:VkGeometryNV::pname:flags, specifying additional parameters for acceleration structure builds, are: include::{generated}/api/enums/VkGeometryFlagBitsNV.txt[] * ename:VK_GEOMETRY_OPAQUE_BIT_NV indicates that this geometry does not invoke the any-hit shaders even if present in a hit group. * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV indicates 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. -- [open,refpage='VkGeometryFlagsNV',desc='Bitmask of VkGeometryFlagBitsNV',type='flags'] -- include::{generated}/api/flags/VkGeometryFlagsNV.txt[] tname:VkGeometryFlagsNV is a bitmask type for setting a mask of zero or more elink:VkGeometryFlagBitsNV. -- [open,refpage='VkGeometryDataNV',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] -- The sname:VkGeometryDataNV structure is defined as: include::{generated}/api/structs/VkGeometryDataNV.txt[] * pname:triangles contains triangle data if sname:VkGeometryNV::pname:geometryType is ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. * pname:aabbs contains axis-aligned bounding box data if sname:VkGeometryNV::pname:geometryType is ename:VK_GEOMETRY_TYPE_AABBS_NV. include::{generated}/validity/structs/VkGeometryDataNV.txt[] -- [open,refpage='VkGeometryTrianglesNV',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] -- The sname:VkGeometryTrianglesNV structure is defined as: include::{generated}/api/structs/VkGeometryTrianglesNV.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 for this geometry. * pname:vertexOffset is the offset in bytes within pname:vertexData containing vertex data for this geometry. * 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 for this geometry. * pname:indexOffset is the offset in bytes within pname:indexData containing index data for this geometry. * 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 32-bit floats representing a 3x4 row major affine transformation matrix for this geometry. * pname:transformOffset is the offset in bytes in pname:transformData of the transform information described above. If pname:indexType is ename:VK_INDEX_TYPE_NONE_NV, then this structure describes a set of triangles determined by pname:vertexCount. Otherwise, this structure describes a set of indexed triangles determined by pname:indexCount. .Valid Usage **** * [[VUID-VkGeometryTrianglesNV-vertexOffset-02428]] pname:vertexOffset must: be less than the size of pname:vertexData * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] pname:vertexOffset must: be a multiple of the component size of pname:vertexFormat * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, ename:VK_FORMAT_R16G16_SFLOAT, ename:VK_FORMAT_R16G16_SNORM, or ename:VK_FORMAT_R16G16B16_SNORM * [[VUID-VkGeometryTrianglesNV-indexOffset-02431]] pname:indexOffset must: be less than the size of pname:indexData * [[VUID-VkGeometryTrianglesNV-indexOffset-02432]] pname:indexOffset must: be a multiple of the element size of pname:indexType * [[VUID-VkGeometryTrianglesNV-indexType-02433]] pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-indexData-02434]] pname:indexData must: be dlink:VK_NULL_HANDLE if pname:indexType is ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-indexData-02435]] pname:indexData must: be a valid sname:VkBuffer handle if pname:indexType is not ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] pname:indexCount must: be `0` if pname:indexType is ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] pname:transformOffset must: be less than the size of pname:transformData * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] pname:transformOffset must: be a multiple of `16` **** include::{generated}/validity/structs/VkGeometryTrianglesNV.txt[] -- [open,refpage='VkGeometryAABBNV',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] -- The sname:VkGeometryAABBNV structure is defined as: include::{generated}/api/structs/VkGeometryAABBNV.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. The AABB data in memory is six 32-bit floats consisting of the minimum x, y, and z values followed by the maximum x, y, and z values. .Valid Usage **** * [[VUID-VkGeometryAABBNV-offset-02439]] pname:offset must: be less than the size of pname:aabbData * [[VUID-VkGeometryAABBNV-offset-02440]] pname:offset must: be a multiple of `8` * [[VUID-VkGeometryAABBNV-stride-02441]] pname:stride must: be a multiple of `8` **** include::{generated}/validity/structs/VkGeometryAABBNV.txt[] -- [open,refpage='vkDestroyAccelerationStructureNV',desc='Destroy an acceleration structure object',type='protos'] -- To destroy an acceleration structure, call: include::{generated}/api/protos/vkDestroyAccelerationStructureNV.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 <> chapter. .Valid Usage **** * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02442]] All submitted commands that refer to pname:accelerationStructure must: have completed execution * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02443]] If sname:VkAllocationCallbacks were provided when pname:accelerationStructure was created, a compatible set of callbacks must: be provided here * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-02444]] If no sname:VkAllocationCallbacks were provided when pname:accelerationStructure was created, pname:pAllocator must: be `NULL` **** include::{generated}/validity/protos/vkDestroyAccelerationStructureNV.txt[] -- [open,refpage='vkGetAccelerationStructureMemoryRequirementsNV',desc='Get acceleration structure memory requirements',type='protos'] -- An acceleration structure has memory requirements for the structure object itself, scratch space for the build, and scratch space for the update. To query the memory requirements call: include::{generated}/api/protos/vkGetAccelerationStructureMemoryRequirementsNV.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 requested acceleration structure memory requirements. include::{generated}/validity/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] -- [open,refpage='VkAccelerationStructureMemoryRequirementsInfoNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] -- The sname:VkAccelerationStructureMemoryRequirementsInfoNV structure is defined as: include::{generated}/api/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:type selects the type of memory requirement being queried. ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV returns the memory requirements for the object itself. ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV returns the memory requirements for the scratch memory when doing a build. ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV returns the memory requirements for the scratch memory when doing an update. * pname:accelerationStructure is the acceleration structure to be queried for memory requirements. include::{generated}/validity/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] -- [open,refpage='VkAccelerationStructureMemoryRequirementsTypeNV',desc='Acceleration structure memory requirement type',type='enums'] -- Possible values of pname:type in sname:VkAccelerationStructureMemoryRequirementsInfoNV are:, include::{generated}/api/enums/VkAccelerationStructureMemoryRequirementsTypeNV.txt[] * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV requests the memory requirement for the sname:VkAccelerationStructureNV backing store. * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV requests the memory requirement for scratch space during the initial build. * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV requests the memory requirement for scratch space during an update. -- [open,refpage='vkBindAccelerationStructureMemoryNV',desc='Bind acceleration structure memory',type='protos'] -- To attach memory to one or more acceleration structures at a time, call: include::{generated}/api/protos/vkBindAccelerationStructureMemoryNV.txt[] * pname:device is the logical device that owns the acceleration structures and memory. * pname:bindInfoCount is the number of elements in pname:pBindInfos. * pname:pBindInfos is a pointer to an array of structures of type slink:VkBindAccelerationStructureMemoryInfoNV, describing images and memory to bind. include::{generated}/validity/protos/vkBindAccelerationStructureMemoryNV.txt[] -- [open,refpage='VkBindAccelerationStructureMemoryInfoNV',desc='Structure specifying acceleration structure memory binding',type='structs'] -- The sname:VkBindAccelerationStructureMemoryInfoNV structure is defined as: include::{generated}/api/structs/VkBindAccelerationStructureMemoryInfoNV.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 sname:VkDeviceMemory object describing the device memory to attach. * pname:memoryOffset is the start offset of the region of memory that is to be bound to the acceleration structure. The number of bytes returned in the slink:VkMemoryRequirements::pname:size member in pname: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 **** * [[VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-02450]] pname:accelerationStructure must: not already be backed by a memory object * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02451]] pname:memoryOffset must: be less than the size of pname:memory * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-02593]] pname:memory must: have been allocated using one of the memory types allowed in the pname:memoryTypeBits member of the slink:VkMemoryRequirements structure returned from a call to flink:vkGetAccelerationStructureMemoryRequirementsNV with pname:accelerationStructure and pname:type of ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02594]] pname:memoryOffset must: be an integer multiple of the pname:alignment member of the slink:VkMemoryRequirements structure returned from a call to flink:vkGetAccelerationStructureMemoryRequirementsNV with pname:accelerationStructure and pname:type of ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-02595]] The pname:size member of the sname:VkMemoryRequirements structure returned from a call to flink:vkGetAccelerationStructureMemoryRequirementsNV with pname:accelerationStructure and pname:type of ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: be less than or equal to the size of pname:memory minus pname:memoryOffset **** include::{generated}/validity/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] -- [open,refpage='vkGetAccelerationStructureHandleNV',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::{generated}/api/protos/vkGetAccelerationStructureHandleNV.txt[] * pname:device is the logical device that owns the acceleration structures. * pname:accelerationStructure is the acceleration structure. * 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-vkGetAccelerationStructureHandleNV-dataSize-02240]] pname:dataSize must: be large enough to contain the result of the query, as described above **** include::{generated}/validity/protos/vkGetAccelerationStructureHandleNV.txt[] --