// Copyright 2020-2022 The Khronos Group Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[acceleration-structure]] = Acceleration Structures [[acceleration-structure-def]] == Acceleration Structures _Acceleration structures_ are data structures used by the implementation to efficiently manage scene geometry as it is <>. The application is responsible for managing acceleration structure objects (see <>), 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 <> or <> has been executed with the given acceleration structure as the destination. [[fig-accelstruct]] image::{images}/accelstruct.svg[align="center",title="Acceleration Structure",opts="{imageopts}"] .Caption **** The diagram shows the relationship between top and bottom level acceleration structures. **** [[acceleration-structure-geometry]] === Geometry _Geometries_ refer to a triangle or axis-aligned bounding box. [[acceleration-structure-top-level]] === 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-bottom-level]] === Bottom Level Acceleration Structures Opaque acceleration structure for an array of geometries. [[acceleration-structure-update]] === 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 <>). * 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. ifdef::VK_EXT_opacity_micromap[] If the original acceleration structure was built using opacity micromaps and ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT was set in pname: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 elink:VkOpacityMicromapSpecialIndexEXT values from a geometry which previously had them, or vice versa. * Change between use of elink: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 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT was set in pname: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. endif::VK_EXT_opacity_micromap[] [[acceleration-structure-inactive-prims]] === 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 handle is dlink:VK_NULL_HANDLE. 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:. 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 code:InstanceId and code: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. [[acceleration-structure-building]] === Building Acceleration Structures ifdef::VK_NV_ray_tracing[] [open,refpage='vkCmdBuildAccelerationStructureNV',desc='Build an acceleration structure',type='protos'] -- :refpage: vkCmdBuildAccelerationStructureNV To build an acceleration structure call: include::{generated}/api/protos/vkCmdBuildAccelerationStructureNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:pInfo contains the shared information for the acceleration structure's structure. * pname:instanceData is the buffer containing an array of slink:VkAccelerationStructureInstanceKHR structures defining acceleration structures. This parameter must: be `NULL` for bottom level acceleration structures. * pname:instanceOffset is the offset in bytes (relative to the start of pname:instanceData) at which the instance data is located. * pname:update specifies whether to update the pname:dst acceleration structure with the data in pname:src. * pname:dst is a pointer to the target acceleration structure for the build. * pname:src is a pointer to an existing acceleration structure that is to be used to update the pname:dst acceleration structure. * pname:scratch is the slink:VkBuffer that will be used as scratch memory for the build. * pname:scratchOffset is the offset in bytes relative to the start of pname:scratch that will be used as a scratch memory. Accesses to pname:dst, pname:src, and pname:scratch must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. .Valid Usage **** * [[VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241]] pname:geometryCount must: be less than or equal to slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount * [[VUID-vkCmdBuildAccelerationStructureNV-dst-02488]] pname:dst must: have been created with compatible slink:VkAccelerationStructureInfoNV where slink:VkAccelerationStructureInfoNV::pname:type and slink:VkAccelerationStructureInfoNV::pname:flags are identical, slink:VkAccelerationStructureInfoNV::pname:instanceCount and slink:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst are greater than or equal to the build size and each geometry in slink:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has greater than or equal to the number of vertices, indices, and AABBs * [[VUID-vkCmdBuildAccelerationStructureNV-update-02489]] If pname:update is ename:VK_TRUE, pname:src must: not be dlink:VK_NULL_HANDLE * [[VUID-vkCmdBuildAccelerationStructureNV-update-02490]] If pname:update is ename:VK_TRUE, pname:src must: have previously been constructed with ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in slink:VkAccelerationStructureInfoNV::pname:flags in the original build * [[VUID-vkCmdBuildAccelerationStructureNV-update-02491]] If pname:update is ename:VK_FALSE, the pname:size member of the slink:VkMemoryRequirements structure returned from a call to flink:vkGetAccelerationStructureMemoryRequirementsNV with slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure set to pname:dst and slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV must: be less than or equal to the size of pname:scratch minus pname:scratchOffset * [[VUID-vkCmdBuildAccelerationStructureNV-update-02492]] If pname:update is ename:VK_TRUE, the pname:size member of the slink:VkMemoryRequirements structure returned from a call to flink:vkGetAccelerationStructureMemoryRequirementsNV with slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure set to pname:dst and slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV must: be less than or equal to the size of pname:scratch minus pname:scratchOffset * [[VUID-vkCmdBuildAccelerationStructureNV-scratch-03522]] pname:scratch must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag * [[VUID-vkCmdBuildAccelerationStructureNV-instanceData-03523]] If pname:instanceData is not dlink:VK_NULL_HANDLE, pname:instanceData must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag * [[VUID-vkCmdBuildAccelerationStructureNV-accelerationStructureReference-03786]] Each slink:VkAccelerationStructureInstanceKHR::pname:accelerationStructureReference value in pname:instanceData must: be a valid device address containing a value obtained from flink:vkGetAccelerationStructureHandleNV * [[VUID-vkCmdBuildAccelerationStructureNV-update-03524]] If pname:update is ename:VK_TRUE, then objects that were previously active must: not be made inactive as per <> * [[VUID-vkCmdBuildAccelerationStructureNV-update-03525]] If pname:update is ename:VK_TRUE, then objects that were previously inactive must: not be made active as per <> * [[VUID-vkCmdBuildAccelerationStructureNV-update-03526]] If pname:update is ename:VK_TRUE, the pname:src and pname:dst objects must: either be the same object or not have any <> * [[VUID-vkCmdBuildAccelerationStructureNV-dst-07787]] pname:dst must: be bound completely and contiguously to a single sname:VkDeviceMemory object via flink:vkBindAccelerationStructureMemoryNV **** include::{generated}/validity/protos/vkCmdBuildAccelerationStructureNV.adoc[] -- endif::VK_NV_ray_tracing[] ifdef::VK_KHR_acceleration_structure[] [open,refpage='vkCmdBuildAccelerationStructuresKHR',desc='Build an acceleration structure',type='protos'] -- :refpage: vkCmdBuildAccelerationStructuresKHR To build acceleration structures call: include::{generated}/api/protos/vkCmdBuildAccelerationStructuresKHR.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:infoCount is the number of acceleration structures to build. It specifies the number of the pname:pInfos structures and pname:ppBuildRangeInfos pointers that must: be provided. * pname:pInfos is a pointer to an array of pname:infoCount slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. * pname:ppBuildRangeInfos is a pointer to an array of pname:infoCount pointers to arrays of slink:VkAccelerationStructureBuildRangeInfoKHR structures. Each pname:ppBuildRangeInfos[i] is a pointer to an array of pname:pInfos[i].pname:geometryCount slink:VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pname:pInfos[i]. The fname: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. [NOTE] .Note ==== This means that an application cannot: build a top-level acceleration structure in the same flink: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. ==== [[acceleration-structure-scratch]] Accesses to the acceleration structure scratch buffers as identified by the slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:scratchData buffer device addresses must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of (ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR). Accesses to each slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:srcAccelerationStructure and slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:dstAccelerationStructure must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, as appropriate. Accesses to other input buffers as identified by any used values of ifdef::VK_NV_ray_tracing_motion_blur[] slink:VkAccelerationStructureGeometryMotionTrianglesDataNV::pname:vertexData, endif::VK_NV_ray_tracing_motion_blur[] slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData, slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData, slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData, slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data, and slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_SHADER_READ_BIT. .Valid Usage **** :maxinstancecheck: pname:ppBuildRangeInfos[i][j].pname:primitiveCount include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] include::{chapters}/commonvalidity/build_acceleration_structure_device_common.adoc[] include::{chapters}/commonvalidity/build_acceleration_structure_nonindirect_common.adoc[] **** include::{generated}/validity/protos/vkCmdBuildAccelerationStructuresKHR.adoc[] -- [open,refpage='vkCmdBuildAccelerationStructuresIndirectKHR',desc='Build an acceleration structure with some parameters provided on the device',type='protos'] -- :refpage: vkCmdBuildAccelerationStructuresIndirectKHR To build acceleration structures with some parameters sourced on the device call: include::{generated}/api/protos/vkCmdBuildAccelerationStructuresIndirectKHR.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:infoCount is the number of acceleration structures to build. * pname:pInfos is a pointer to an array of pname:infoCount slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. * pname:pIndirectDeviceAddresses is a pointer to an array of pname:infoCount buffer device addresses which point to pname:pInfos[i].pname:geometryCount slink:VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pname:pInfos[i]. * pname:pIndirectStrides is a pointer to an array of pname:infoCount byte strides between elements of pname:pIndirectDeviceAddresses. * pname:ppMaxPrimitiveCounts is a pointer to an array of pname:infoCount pointers to arrays of pname:pInfos[i].pname:geometryCount values 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 <>. Accesses to any element of pname:pIndirectDeviceAddresses must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT. .Valid Usage **** :maxinstancecheck: pname:ppMaxPrimitiveCounts[i][j] include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] include::{chapters}/commonvalidity/build_acceleration_structure_device_common.adoc[] * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03645]] For any element of pname:pIndirectDeviceAddresses, if the buffer from which it was queried is non-sparse then it must: be bound completely and contiguously to a single slink:VkDeviceMemory object * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03646]] For any element of pname:pIndirectDeviceAddresses[i], all device addresses between pname:pIndirectDeviceAddresses[i] and [eq]#pname:pIndirectDeviceAddresses[i] {plus} (pname:pInfos[i].pname:geometryCount {times} pname:pIndirectStrides[i]) - 1# must: be in the buffer device address range of the same buffer * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03647]] For any element of pname:pIndirectDeviceAddresses, the buffer from which it was queried must: have been created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03648]] Each element of pname:pIndirectDeviceAddresses must: be a multiple of `4` * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectStrides-03787]] Each element of pname:pIndirectStrides must: be a multiple of `4` * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-03649]] pname:commandBuffer must: not be a protected command buffer * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-accelerationStructureIndirectBuild-03650]] The <> feature must: be enabled * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03651]] Each slink:VkAccelerationStructureBuildRangeInfoKHR structure referenced by any element of pname:pIndirectDeviceAddresses must: be a valid slink:VkAccelerationStructureBuildRangeInfoKHR structure * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03652]] pname:pInfos[i].pname:dstAccelerationStructure must: have been created with a value of slink:VkAccelerationStructureCreateInfoKHR::pname:size greater than or equal to the memory size required by the build operation, as returned by flink:vkGetAccelerationStructureBuildSizesKHR with [eq]#pname:pBuildInfo = pname:pInfos[i]# and [eq]#pname:pMaxPrimitiveCounts = pname:ppMaxPrimitiveCounts[i]# * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-ppMaxPrimitiveCounts-03653]] Each pname:ppMaxPrimitiveCounts[i][j] must: be greater than or equal to the the pname:primitiveCount value specified by the slink:VkAccelerationStructureBuildRangeInfoKHR structure located at [eq]#pname:pIndirectDeviceAddresses[i] {plus} (code:j {times} pname:pIndirectStrides[i])# **** include::{generated}/validity/protos/vkCmdBuildAccelerationStructuresIndirectKHR.adoc[] -- [open,refpage='VkAccelerationStructureBuildGeometryInfoKHR',desc='Structure specifying the geometry data used to build an acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureBuildGeometryInfoKHR The sname:VkAccelerationStructureBuildGeometryInfoKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureBuildGeometryInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:type is a elink:VkAccelerationStructureTypeKHR value specifying the type of acceleration structure being built. * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsKHR specifying additional parameters of the acceleration structure. * pname:mode is a elink:VkBuildAccelerationStructureModeKHR value specifying the type of operation to perform. * pname:srcAccelerationStructure is a pointer to an existing acceleration structure that is to be used to update the pname:dst acceleration structure when pname:mode is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR. * pname:dstAccelerationStructure is a pointer to the target acceleration structure for the build. * pname:geometryCount specifies the number of geometries that will be built into pname:dstAccelerationStructure. * pname:pGeometries is a pointer to an array of slink:VkAccelerationStructureGeometryKHR structures. * pname:ppGeometries is a pointer to an array of pointers to slink:VkAccelerationStructureGeometryKHR structures. * pname:scratchData is the device or host address to memory that will be used as scratch memory for the build. Only one of pname:pGeometries or pname: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. ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] [[acceleration-structure-geometry-index]] The index of each element of the pname:pGeometries or pname:ppGeometries members of slink:VkAccelerationStructureBuildGeometryInfoKHR is used as the _geometry index_ during ray traversal. ifdef::VK_KHR_ray_tracing_pipeline[] The geometry index is available in ray shaders via the <>, and is <>. endif::VK_KHR_ray_tracing_pipeline[] ifdef::VK_KHR_ray_query[] The geometry index is available to ray queries via the code:OpRayQueryGetIntersectionGeometryIndexKHR instruction. endif::VK_KHR_ray_query[] endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] ifdef::VK_NV_ray_tracing_motion_blur[] [[acceleration-structure-motion-instances]] Setting ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in pname:flags indicates that this build is a motion top level acceleration structure. A motion top level uses instances of format slink:VkAccelerationStructureMotionInstanceNV if slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:arrayOfPointers is ename:VK_FALSE. If slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:arrayOfPointers is ename:VK_TRUE, the pointer for any given element of the array of instance pointers consists of 4 bits of ename: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 slink:VkAccelerationStructureInstanceKHR, slink:VkAccelerationStructureMatrixMotionInstanceNV or slink: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 ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in pname:flags. endif::VK_NV_ray_tracing_motion_blur[] Members pname:srcAccelerationStructure and pname:dstAccelerationStructure may: be the same or different for an update operation (when pname:mode is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR). If they are the same, the update happens in-place. Otherwise, the target acceleration structure is updated and the source is not modified. .Valid Usage **** * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03654]] pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788]] Only one of pname:pGeometries or pname:ppGeometries can: be a valid pointer, the other must: be `NULL` * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03789]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, the pname:geometryType member of elements of either pname:pGeometries or pname:ppGeometries must: be ename:VK_GEOMETRY_TYPE_INSTANCES_KHR * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03790]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, pname:geometryCount must: be `1` * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03791]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR the pname:geometryType member of elements of either pname:pGeometries or pname:ppGeometries must: not be ename:VK_GEOMETRY_TYPE_INSTANCES_KHR * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03792]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then the pname:geometryType member of each geometry in either pname:pGeometries or pname:ppGeometries must: be the same * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03793]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR then pname:geometryCount must: be less than or equal to slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxGeometryCount * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03794]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the pname:geometryType member of either pname:pGeometries or pname:ppGeometries is ename:VK_GEOMETRY_TYPE_AABBS_KHR, the total number of AABBs in all geometries must: be less than or equal to slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPrimitiveCount * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03795]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR and the pname:geometryType member of either pname:pGeometries or pname:ppGeometries is ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the total number of triangles in all geometries must: be less than or equal to slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPrimitiveCount * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-03796]] If pname:flags has the ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR bit set, then it must: not have the ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR bit set ifdef::VK_NV_ray_tracing_motion_blur[] * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-dstAccelerationStructure-04927]] If pname:dstAccelerationStructure was created with ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in slink:VkAccelerationStructureCreateInfoKHR::pname:flags, ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV must: be set in pname:flags * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04928]] If ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in pname:flags, pname:dstAccelerationStructure must: have been created with ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in slink:VkAccelerationStructureCreateInfoKHR::pname:flags * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04929]] If ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in pname:flags, pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR endif::VK_NV_ray_tracing_motion_blur[] ifdef::VK_EXT_opacity_micromap[] * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-07334]] If pname:flags has the ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT bit set then it must: not have the ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT bit set endif::VK_EXT_opacity_micromap[] **** include::{generated}/validity/structs/VkAccelerationStructureBuildGeometryInfoKHR.adoc[] -- [open,refpage='VkBuildAccelerationStructureModeKHR',desc='Enum specifying the type of build operation to perform',type='enums'] -- :refpage: VkBuildAccelerationStructureModeKHR The ename:VkBuildAccelerationStructureModeKHR enumeration is defined as: include::{generated}/api/enums/VkBuildAccelerationStructureModeKHR.adoc[] * ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR specifies that the destination acceleration structure will be built using the specified geometries. * ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR specifies that the destination acceleration structure will be built using data in a source acceleration structure, updated by the specified geometries. -- [open,refpage='VkDeviceOrHostAddressKHR',desc='Union specifying a device or host address',type='structs'] -- :refpage: VkDeviceOrHostAddressKHR The sname:VkDeviceOrHostAddressKHR union is defined as: include::{generated}/api/structs/VkDeviceOrHostAddressKHR.adoc[] * pname:deviceAddress is a buffer device address as returned by the flink:vkGetBufferDeviceAddressKHR command. * pname:hostAddress is a host memory address. include::{generated}/validity/structs/VkDeviceOrHostAddressKHR.adoc[] -- [open,refpage='VkDeviceOrHostAddressConstKHR',desc='Union specifying a const device or host address',type='structs'] -- :refpage: VkDeviceOrHostAddressConstKHR The sname:VkDeviceOrHostAddressConstKHR union is defined as: include::{generated}/api/structs/VkDeviceOrHostAddressConstKHR.adoc[] * pname:deviceAddress is a buffer device address as returned by the flink:vkGetBufferDeviceAddressKHR command. * pname:hostAddress is a const host memory address. include::{generated}/validity/structs/VkDeviceOrHostAddressConstKHR.adoc[] -- [open,refpage='VkAccelerationStructureGeometryKHR',desc='Structure specifying geometries to be built into an acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureGeometryKHR The sname:VkAccelerationStructureGeometryKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:geometryType describes which type of geometry this sname:VkAccelerationStructureGeometryKHR refers to. * pname:geometry is a slink:VkAccelerationStructureGeometryDataKHR union describing the geometry data for the relevant geometry type. * pname:flags is a bitmask of elink:VkGeometryFlagBitsKHR values describing additional properties of how the geometry should be built. include::{generated}/validity/structs/VkAccelerationStructureGeometryKHR.adoc[] -- [open,refpage='VkAccelerationStructureGeometryDataKHR',desc='Union specifying acceleration structure geometry data',type='structs'] -- :refpage: VkAccelerationStructureGeometryDataKHR The sname:VkAccelerationStructureGeometryDataKHR union is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryDataKHR.adoc[] * pname:triangles is a slink:VkAccelerationStructureGeometryTrianglesDataKHR structure. * pname:aabbs is a slink:VkAccelerationStructureGeometryAabbsDataKHR structure. * pname:instances is a slink:VkAccelerationStructureGeometryInstancesDataKHR structure. include::{generated}/validity/structs/VkAccelerationStructureGeometryDataKHR.adoc[] -- [open,refpage='VkAccelerationStructureGeometryTrianglesDataKHR',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureGeometryTrianglesDataKHR The sname:VkAccelerationStructureGeometryTrianglesDataKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryTrianglesDataKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:vertexFormat is the elink:VkFormat of each vertex element. * pname:vertexData is a device or host address to memory containing vertex data for this geometry. * pname:maxVertex is the highest index of a vertex that will be addressed by a build command using this structure. * pname:vertexStride is the stride in bytes between each vertex. * pname:indexType is the elink:VkIndexType of each index element. * pname:indexData is a device or host address to memory containing index data for this geometry. * pname:transformData is a device or host address to memory containing an optional reference to a slink: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. [NOTE] .Note ==== Unlike the stride for vertex buffers in slink:VkVertexInputBindingDescription for graphics pipelines which must not exceed pname:maxVertexInputBindingStride, pname:vertexStride for acceleration structure geometry is instead restricted to being a 32-bit value. ==== .Valid Usage **** * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03735]] pname:vertexStride must: be a multiple of the size in bytes of the smallest component of pname:vertexFormat * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03819]] pname:vertexStride must: be less than or equal to [eq]#2^32^-1# * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexFormat-03797]] pname:vertexFormat must: support the ename:VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR in slink:VkFormatProperties::pname:bufferFeatures as returned by flink:vkGetPhysicalDeviceFormatProperties2 * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexType-03798]] pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_KHR **** include::{generated}/validity/structs/VkAccelerationStructureGeometryTrianglesDataKHR.adoc[] -- ifdef::VK_NV_ray_tracing_motion_blur[] [open,refpage='VkAccelerationStructureGeometryMotionTrianglesDataNV',desc='Structure specifying vertex motion in a bottom-level acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureGeometryMotionTrianglesDataNV The sname:VkAccelerationStructureGeometryMotionTrianglesDataNV structure is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryMotionTrianglesDataNV.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:vertexData is a pointer to vertex data for this geometry at time 1.0 If sname:VkAccelerationStructureGeometryMotionTrianglesDataNV is included in the pname:pNext chain of a slink:VkAccelerationStructureGeometryTrianglesDataKHR structure, the basic vertex positions are used for the position of the triangles in the geometry at time 0.0 and the pname:vertexData in sname:VkAccelerationStructureGeometryMotionTrianglesDataNV is used for the vertex positions at time 1.0, with positions linearly interpolated at intermediate times. Indexing for sname:VkAccelerationStructureGeometryMotionTrianglesDataNV pname:vertexData is equivalent to the basic vertex position data. include::{generated}/validity/structs/VkAccelerationStructureGeometryMotionTrianglesDataNV.adoc[] -- endif::VK_NV_ray_tracing_motion_blur[] ifdef::VK_EXT_opacity_micromap[] [open,refpage='VkAccelerationStructureTrianglesOpacityMicromapEXT',desc='Structure specifying an opacity micromap in a bottom-level acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureTrianglesOpacityMicromapEXT The sname:VkAccelerationStructureTrianglesOpacityMicromapEXT structure is defined as: include::{generated}/api/structs/VkAccelerationStructureTrianglesOpacityMicromapEXT.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:indexType is the type of triangle indices used when indexing this micromap * pname:indexBuffer is the address containing the triangle indices * pname:indexStride is the byte stride between triangle indices * pname:baseTriangle is the base value added to the non-negative triangle indices * pname:usageCountsCount specifies the number of usage counts structures that will be used to determine the size of this micromap. * pname:pUsageCounts is a pointer to an array of slink:VkMicromapUsageEXT structures. * pname:ppUsageCounts is a pointer to an array of pointers to slink:VkMicromapUsageEXT structures. * pname:micromap is the handle to the micromap object to include in this geometry If sname:VkAccelerationStructureTrianglesOpacityMicromapEXT is included in the pname:pNext chain of a slink:VkAccelerationStructureGeometryTrianglesDataKHR structure, that geometry will reference that micromap. For each triangle in the geometry, the acceleration structure build fetches an index from pname:indexBuffer using pname:indexType and pname:indexStride. If that value is the unsigned cast of one of the values from elink:VkOpacityMicromapSpecialIndexEXT then that triangle behaves as described for that special value in <>. Otherwise that triangle uses the opacity micromap information from pname:micromap at that index plus pname:baseTriangle. Only one of pname:pUsageCounts or pname: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 pname:format and pname: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 pname:count provided. If pname:micromap is dlink:VK_NULL_HANDLE, then every value read from pname:indexBuffer must: be one of the values in ename:VkOpacityMicromapSpecialIndexEXT. .Valid Usage **** * [[VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-pUsageCounts-07335]] Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid pointer, the other must: be `NULL` **** include::{generated}/validity/structs/VkAccelerationStructureTrianglesOpacityMicromapEXT.adoc[] -- [open,refpage='VkOpacityMicromapSpecialIndexEXT',desc='Enum for special indices in the opacity micromap',type='enums'] -- :refpage: VkOpacityMicromapSpecialIndexEXT The ename:VkOpacityMicromapSpecialIndexEXT enumeration is defined as: include::{generated}/api/enums/VkOpacityMicromapSpecialIndexEXT.adoc[] * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXT specifies that the entire triangle is fully transparent. * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXT specifies that the entire triangle is fully opaque. * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXT specifies that the entire triangle is unknown-transparent. * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXT specifies that the entire triangle is unknown-opaque. -- endif::VK_EXT_opacity_micromap[] endif::VK_KHR_acceleration_structure[] [open,refpage='VkTransformMatrixKHR',desc='Structure specifying a 3x4 affine transformation matrix',type='structs',alias='VkTransformMatrixNV'] -- :refpage: VkTransformMatrixKHR The sname:VkTransformMatrixKHR structure is defined as: include::{generated}/api/structs/VkTransformMatrixKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/structs/VkTransformMatrixNV.adoc[] endif::VK_NV_ray_tracing[] * pname:matrix is a 3x4 row-major affine transformation matrix. include::{generated}/validity/structs/VkTransformMatrixKHR.adoc[] .Valid Usage **** * [[VUID-VkTransformMatrixKHR-matrix-03799]] The first three columns of pname:matrix must: define an invertible 3x3 matrix **** -- ifdef::VK_KHR_acceleration_structure[] [open,refpage='VkAccelerationStructureGeometryAabbsDataKHR',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] -- :refpage: VkAccelerationStructureGeometryAabbsDataKHR The sname:VkAccelerationStructureGeometryAabbsDataKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryAabbsDataKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:data is a device or host address to memory containing slink:VkAabbPositionsKHR structures containing position data for each axis-aligned bounding box in the geometry. * pname:stride is the stride in bytes between each entry in pname:data. The stride must: be a multiple of `8`. .Valid Usage **** * [[VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03545]] pname:stride must: be a multiple of `8` * [[VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03820]] pname:stride must: be less than or equal to [eq]#2^32^-1# **** include::{generated}/validity/structs/VkAccelerationStructureGeometryAabbsDataKHR.adoc[] -- endif::VK_KHR_acceleration_structure[] [open,refpage='VkAabbPositionsKHR',desc='Structure specifying two opposing corners of an axis-aligned bounding box',type='structs',alias='VkAabbPositionsNV'] -- :refpage: VkAabbPositionsKHR The sname:VkAabbPositionsKHR structure is defined as: include::{generated}/api/structs/VkAabbPositionsKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/structs/VkAabbPositionsNV.adoc[] endif::VK_NV_ray_tracing[] * pname:minX is the x position of one opposing corner of a bounding box. * pname:minY is the y position of one opposing corner of a bounding box. * pname:minZ is the z position of one opposing corner of a bounding box. * pname:maxX is the x position of the other opposing corner of a bounding box. * pname:maxY is the y position of the other opposing corner of a bounding box. * pname:maxZ is the z position of the other opposing corner of a bounding box. .Valid Usage **** * [[VUID-VkAabbPositionsKHR-minX-03546]] pname:minX must: be less than or equal to pname:maxX * [[VUID-VkAabbPositionsKHR-minY-03547]] pname:minY must: be less than or equal to pname:maxY * [[VUID-VkAabbPositionsKHR-minZ-03548]] pname:minZ must: be less than or equal to pname:maxZ **** include::{generated}/validity/structs/VkAabbPositionsKHR.adoc[] -- ifdef::VK_KHR_acceleration_structure[] [open,refpage='VkAccelerationStructureGeometryInstancesDataKHR',desc='Structure specifying a geometry consisting of instances of other acceleration structures',type='structs'] -- :refpage: VkAccelerationStructureGeometryInstancesDataKHR The sname:VkAccelerationStructureGeometryInstancesDataKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:arrayOfPointers specifies whether pname:data is used as an array of addresses or just an array. * pname:data is either the address of an array of device or host addresses referencing individual slink:VkAccelerationStructureInstanceKHR structures ifdef::VK_NV_ray_tracing_motion_blur[] or packed motion instance information as described in <> endif::VK_NV_ray_tracing_motion_blur[] if pname:arrayOfPointers is ename:VK_TRUE, or the address of an array of slink:VkAccelerationStructureInstanceKHR ifdef::VK_NV_ray_tracing_motion_blur[] or slink:VkAccelerationStructureMotionInstanceNV endif::VK_NV_ray_tracing_motion_blur[] structures. Addresses and slink:VkAccelerationStructureInstanceKHR structures are tightly packed. ifdef::VK_NV_ray_tracing_motion_blur[] slink:VkAccelerationStructureMotionInstanceNV structures have a stride of 160 bytes. endif::VK_NV_ray_tracing_motion_blur[] include::{generated}/validity/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] -- endif::VK_KHR_acceleration_structure[] [open,refpage='VkAccelerationStructureInstanceKHR',desc='Structure specifying a single acceleration structure instance for building into an acceleration structure geometry',type='structs',alias='VkAccelerationStructureInstanceNV'] -- :refpage: VkAccelerationStructureInstanceKHR _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: include::{generated}/api/structs/VkAccelerationStructureInstanceKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/structs/VkAccelerationStructureInstanceNV.adoc[] endif::VK_NV_ray_tracing[] * pname:transform is a slink:VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure. * pname:instanceCustomIndex is a 24-bit user-specified index value accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. * pname:mask is an 8-bit visibility mask for the geometry. The instance may: only be hit if `Cull Mask & instance.mask != 0` * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in calculating the hit shader binding table index. * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR values to apply to this instance. * pname:accelerationStructureReference is either: ** a device address containing the value obtained from ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] (used by device operations which reference acceleration structures) or, ** a slink: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 struct produces the correct layout with existing compilers. The intended bit pattern is for the following: * pname:instanceCustomIndex and pname:mask occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceCustomIndex occupies the 24 least significant bits of that memory ** pname:mask occupies the 8 most significant bits of that memory * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least significant bits of that memory ** pname:flags occupies 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. include::{generated}/validity/structs/VkAccelerationStructureInstanceKHR.adoc[] -- [open,refpage='VkGeometryInstanceFlagBitsKHR',desc='Instance flag bits',type='enums',alias='VkGeometryInstanceFlagBitsNV'] -- :refpage: VkGeometryInstanceFlagBitsKHR Possible values of pname:flags in the instance modifying the behavior of that instance are: include::{generated}/api/enums/VkGeometryInstanceFlagBitsKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/enums/VkGeometryInstanceFlagBitsNV.adoc[] endif::VK_NV_ray_tracing[] * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR disables face culling for this instance. * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR indicates that the <> 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. * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR causes this instance to act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were specified on all geometries referenced by this instance. This behavior can: be overridden by the SPIR-V code:NoOpaqueKHR ray flag. * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR causes this instance to act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were not specified on all geometries referenced by this instance. This behavior can: be overridden by the SPIR-V code:OpaqueKHR ray flag. ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must: not be used in the same flag. -- [open,refpage='VkGeometryInstanceFlagsKHR',desc='Bitmask of VkGeometryInstanceFlagBitsKHR',type='flags',alias='VkGeometryInstanceFlagsNV'] -- :refpage: VkGeometryInstanceFlagsKHR include::{generated}/api/flags/VkGeometryInstanceFlagsKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/flags/VkGeometryInstanceFlagsNV.adoc[] endif::VK_NV_ray_tracing[] tname:VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of zero or more elink:VkGeometryInstanceFlagBitsKHR. -- ifdef::VK_NV_ray_tracing_motion_blur[] [open,refpage='VkAccelerationStructureMotionInstanceNV',desc='Structure specifying a single acceleration structure motion instance for building into an acceleration structure geometry',type='structs'] -- :refpage: VkAccelerationStructureMotionInstanceNV _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: include::{generated}/api/structs/VkAccelerationStructureMotionInstanceNV.adoc[] * pname:type is a elink:VkAccelerationStructureMotionInstanceTypeNV enumerant identifying which type of motion instance this is and which type of the union is valid. * pname:flags is currently unused, but is required to keep natural alignment of pname:data. * pname:data is a slink:VkAccelerationStructureMotionInstanceDataNV containing motion instance data for this instance. [NOTE] .Note ==== If writing this other than with a standard C compiler, note that the final structure should be 152 bytes in size. ==== include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceNV.adoc[] -- [open,refpage='VkAccelerationStructureMotionInstanceDataNV',desc='Union specifying a acceleration structure motion instance data for building into an acceleration structure geometry',type='structs'] -- :refpage: VkAccelerationStructureMotionInstanceDataNV Acceleration structure motion instance is defined by the union: include::{generated}/api/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] * pname:staticInstance is a slink:VkAccelerationStructureInstanceKHR structure containing data for a static instance. * pname:matrixMotionInstance is a slink:VkAccelerationStructureMatrixMotionInstanceNV structure containing data for a matrix motion instance. * pname:srtMotionInstance is a slink:VkAccelerationStructureSRTMotionInstanceNV structure containing data for an SRT motion instance. include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] -- [open,refpage='VkAccelerationStructureMotionInstanceFlagsNV',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkAccelerationStructureMotionInstanceFlagsNV.adoc[] tname:VkAccelerationStructureMotionInstanceFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use. -- [open,refpage='VkAccelerationStructureMotionInstanceTypeNV',desc='Enum specifying a type of acceleration structure motion instance data for building into an acceleration structure geometry',type='enums'] -- :refpage: VkAccelerationStructureMotionInstanceTypeNV The ename:VkAccelerationStructureMotionInstanceTypeNV enumeration is defined as: include::{generated}/api/enums/VkAccelerationStructureMotionInstanceTypeNV.adoc[] * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NV specifies that the instance is a static instance with no instance motion. * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NV specifies that the instance is a motion instance with motion specified by interpolation between two matrices. * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NV specifies that the instance is a motion instance with motion specified by interpolation in the SRT decomposition. -- [open,refpage='VkAccelerationStructureMatrixMotionInstanceNV',desc='Structure specifying a single acceleration structure matrix motion instance for building into an acceleration structure geometry',type='structs'] -- :refpage: VkAccelerationStructureMatrixMotionInstanceNV An acceleration structure matrix motion instance is defined by the structure: include::{generated}/api/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] * pname:transformT0 is a slink:VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 0. * pname:transformT1 is a slink:VkTransformMatrixKHR structure describing a transformation to be applied to the acceleration structure at time 1. * pname:instanceCustomIndex is a 24-bit user-specified index value accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. * pname:mask is an 8-bit visibility mask for the geometry. The instance may: only be hit if `Cull Mask & instance.mask != 0` * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in calculating the hit shader binding table index. * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR values to apply to this instance. * pname:accelerationStructureReference is either: ** a device address containing the value obtained from ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] (used by device operations which reference acceleration structures) or, ** a slink: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 struct produces the correct layout with existing compilers. The intended bit pattern is for the following: * pname:instanceCustomIndex and pname:mask occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceCustomIndex occupies the 24 least significant bits of that memory ** pname:mask occupies the 8 most significant bits of that memory * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least significant bits of that memory ** pname:flags occupies 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 code:time in [0,1] the resulting transform is {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} pname:transformT1 {times} code:time# include::{generated}/validity/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] -- [open,refpage='VkAccelerationStructureSRTMotionInstanceNV',desc='Structure specifying a single acceleration structure SRT motion instance for building into an acceleration structure geometry',type='structs'] -- :refpage: VkAccelerationStructureSRTMotionInstanceNV An acceleration structure SRT motion instance is defined by the structure: include::{generated}/api/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] * pname:transformT0 is a slink:VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 0. * pname:transformT1 is a slink:VkSRTDataNV structure describing a transformation to be applied to the acceleration structure at time 1. * pname:instanceCustomIndex is a 24-bit user-specified index value accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. * pname:mask is an 8-bit visibility mask for the geometry. The instance may: only be hit if `Cull Mask & instance.mask != 0` * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in calculating the hit shader binding table index. * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR values to apply to this instance. * pname:accelerationStructureReference is either: ** a device address containing the value obtained from ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] (used by device operations which reference acceleration structures) or, ** a slink: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 struct produces the correct layout with existing compilers. The intended bit pattern is for the following: * pname:instanceCustomIndex and pname:mask occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceCustomIndex occupies the 24 least significant bits of that memory ** pname:mask occupies the 8 most significant bits of that memory * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the same memory as if a single code:uint32_t was specified in their place ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least significant bits of that memory ** pname:flags occupies 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 code:time in [0,1] the resulting transform is {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} pname:transformT1 {times} code:time# include::{generated}/validity/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] -- [open,refpage='VkSRTDataNV',desc='Structure specifying a transform in SRT decomposition',type='structs'] -- :refpage: VkSRTDataNV An acceleration structure SRT transform is defined by the structure: include::{generated}/api/structs/VkSRTDataNV.adoc[] * pname:sx is the x component of the scale of the transform * pname:a is one component of the shear for the transform * pname:b is one component of the shear for the transform * pname:pvx is the x component of the pivot point of the transform * pname:sy is the y component of the scale of the transform * pname:c is one component of the shear for the transform * pname:pvy is the y component of the pivot point of the transform * pname:sz is the z component of the scale of the transform * pname:pvz is the z component of the pivot point of the transform * pname:qx is the x component of the rotation quaternion * pname:qy is the y component of the rotation quaternion * pname:qz is the z component of the rotation quaternion * pname:qw is the w component of the rotation quaternion * pname:tx is the x component of the post-rotation translation * pname:ty is the y component of the post-rotation translation * pname:tz is 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: [latexmath] ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ S = \left( \begin{matrix} sx & a & b & pvx \\ 0 & sy & c & pvy \\ 0 & 0 & sz & pvz \end{matrix} \right) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The rotation quaternion is defined as: {empty}:: [eq]#code:R = [ pname:qx, pname:qy, pname:qz, pname:qw ]# This is a rotation around a conceptual normalized axis [eq]#[ ax, ay, az ]# of amount code:theta such that: {empty}:: [eq]#[ pname:qx, pname:qy, pname:qz ] = sin(code:theta/2) {times} [ code:ax, code:ay, code:az ]# and {empty}:: [eq]#pname:qw = cos(code:theta/2)# Finally, the transform has a translation T constructed from the parameters above by: [latexmath] ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ T = \left( \begin{matrix} 1 & 0 & 0 & tx \\ 0 & 1 & 0 & ty \\ 0 & 0 & 1 & tz \end{matrix} \right) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The effective derived transform is then given by {empty}:: [eq]#code:T {times} code:R {times} code:S# include::{generated}/validity/structs/VkSRTDataNV.adoc[] -- endif::VK_NV_ray_tracing_motion_blur[] ifdef::VK_KHR_acceleration_structure[] [open,refpage='VkAccelerationStructureBuildRangeInfoKHR',desc='Structure specifying build offsets and counts for acceleration structure builds',type='structs'] -- :refpage: VkAccelerationStructureBuildOffsetInfoKHR sname:VkAccelerationStructureBuildRangeInfoKHR is defined as: include::{generated}/api/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] * pname:primitiveCount defines the number of primitives for a corresponding acceleration structure geometry. * pname:primitiveOffset defines an offset in bytes into the memory where primitive data is defined. * pname:firstVertex is the index of the first vertex to build from for triangle geometry. * pname:transformOffset defines 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 elink:VkGeometryTypeKHR used: * For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, pname:primitiveCount is the number of triangles to be built, where each triangle is treated as 3 vertices. ** If the geometry uses indices, [eq]#pname:primitiveCount {times} 3# indices are consumed from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData, starting at an offset of pname:primitiveOffset. The value of pname:firstVertex is added to the index values before fetching vertices. ** If the geometry does not use indices, [eq]#pname:primitiveCount {times} 3# vertices are consumed from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData, starting at an offset of [eq]#pname:primitiveOffset {plus} slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexStride {times} pname:firstVertex#. ** If slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData is not `NULL`, a single slink:VkTransformMatrixKHR structure is consumed from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData, at an offset of pname:transformOffset. 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 ename:VK_GEOMETRY_TYPE_AABBS_KHR, pname:primitiveCount is the number of axis-aligned bounding boxes. pname:primitiveCount slink:VkAabbPositionsKHR structures are consumed from slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data, starting at an offset of pname:primitiveOffset. * For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, pname:primitiveCount is the number of acceleration structures. pname:primitiveCount slink:VkAccelerationStructureInstanceKHR ifdef::VK_NV_ray_tracing_motion_blur[] or slink:VkAccelerationStructureMotionInstanceNV endif::VK_NV_ray_tracing_motion_blur[] structures are consumed from slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data, starting at an offset of pname:primitiveOffset. .Valid Usage **** * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03656]] For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the geometry uses indices, the offset pname:primitiveOffset from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData must: be a multiple of the element size of slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexType * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03657]] For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the geometry does not use indices, the offset pname:primitiveOffset from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData must: be a multiple of the component size of slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexFormat * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-transformOffset-03658]] For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the offset pname:transformOffset from slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData must: be a multiple of 16 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03659]] For geometries of type ename:VK_GEOMETRY_TYPE_AABBS_KHR, the offset pname:primitiveOffset from slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data must: be a multiple of 8 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03660]] For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, the offset pname:primitiveOffset from slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data must: be a multiple of 16 **** include::{generated}/validity/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] -- endif::VK_KHR_acceleration_structure[] [[acceleration-structure-copying]] === 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. [open,refpage='vkCmdWriteAccelerationStructuresPropertiesKHR',desc='Write acceleration structure result parameters to query results.',type='protos'] -- :refpage: vkCmdWriteAccelerationStructuresPropertiesKHR To query acceleration structure size parameters call: ifdef::VK_KHR_acceleration_structure[] include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] endif::VK_KHR_acceleration_structure[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:accelerationStructureCount is the count of acceleration structures for which to query the property. * pname:pAccelerationStructures is a pointer to an array of existing previously built acceleration structures. * pname:queryType is a elink:VkQueryType value specifying the type of queries managed by the pool. * pname:queryPool is the query pool that will manage the results of the query. * pname:firstQuery is the first query index within the query pool that will contain the pname:accelerationStructureCount number of results. Accesses to any of the acceleration structures listed in pname:pAccelerationStructures must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. * If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the value written out is the number of bytes required by a compacted acceleration structure. * If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then the value written out is the number of bytes required by a serialized acceleration structure. .Valid Usage **** * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493]] pname:queryPool must: have been created with a pname:queryType matching pname:queryType * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494]] The queries identified by pname:queryPool and pname:firstQuery must: be _unavailable_ * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-buffer-03736]] The pname:buffer used to create each acceleration structure in pname:pAccelerationStructures must: be bound to device memory * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-query-04880]] The sum of pname:query plus pname:accelerationStructureCount must: be less than or equal to the number of queries in pname:queryPool include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] **** include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] -- ifdef::VK_NV_ray_tracing[] [open,refpage='vkCmdWriteAccelerationStructuresPropertiesNV',desc='Write acceleration structure result parameters to query results.',type='protos'] -- :refpage: vkCmdWriteAccelerationStructuresPropertiesNV To query acceleration structure size parameters call: include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:accelerationStructureCount is the count of acceleration structures for which to query the property. * pname:pAccelerationStructures is a pointer to an array of existing previously built acceleration structures. * pname:queryType is a elink:VkQueryType value specifying the type of queries managed by the pool. * pname:queryPool is the query pool that will manage the results of the query. * pname:firstQuery is the first query index within the query pool that will contain the pname:accelerationStructureCount number of results. Accesses to any of the acceleration structures listed in pname:pAccelerationStructures must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. .Valid Usage **** * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03755]] pname:queryPool must: have been created with a pname:queryType matching pname:queryType * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03756]] The queries identified by pname:queryPool and pname:firstQuery must: be _unavailable_ * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructure-03757]] pname:accelerationStructure must: be bound completely and contiguously to a single sname:VkDeviceMemory object via flink:vkBindAccelerationStructureMemoryNV * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-04958]] All acceleration structures in pname:pAccelerationStructures must: have been built prior to the execution of this command * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-06215]] All acceleration structures in pname:pAccelerationStructures must: have been built with ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-06216]] pname:queryType must: be ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV **** include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] -- [open,refpage='vkCmdCopyAccelerationStructureNV',desc='Copy an acceleration structure',type='protos'] -- :refpage: vkCmdCopyAccelerationStructureNV To copy an acceleration structure call: include::{generated}/api/protos/vkCmdCopyAccelerationStructureNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:dst is the target acceleration structure for the copy. * pname:src is the source acceleration structure for the copy. * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy. Accesses to pname:src and pname:dst must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. .Valid Usage **** include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] **** include::{generated}/validity/protos/vkCmdCopyAccelerationStructureNV.adoc[] -- endif::VK_NV_ray_tracing[] ifdef::VK_KHR_acceleration_structure[] [open,refpage='vkCmdCopyAccelerationStructureKHR',desc='Copy an acceleration structure',type='protos'] -- :refpage: vkCmdCopyAccelerationStructureKHR To copy an acceleration structure call: include::{generated}/api/protos/vkCmdCopyAccelerationStructureKHR.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR structure defining the copy operation. This command copies the pname:pInfo->src acceleration structure to the pname:pInfo->dst acceleration structure in the manner specified by pname:pInfo->mode. Accesses to pname:pInfo->src and pname:pInfo->dst must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. .Valid Usage **** * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03737]] The pname:buffer used to create pname:pInfo->src must: be bound to device memory * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03738]] The pname:buffer used to create pname:pInfo->dst must: be bound to device memory **** include::{generated}/validity/protos/vkCmdCopyAccelerationStructureKHR.adoc[] -- [open,refpage='VkCopyAccelerationStructureInfoKHR',desc='Parameters for copying an acceleration structure',type='structs'] -- :refpage: VkCopyAccelerationStructureInfoKHR The sname:VkCopyAccelerationStructureInfoKHR structure is defined as: include::{generated}/api/structs/VkCopyAccelerationStructureInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:src is the source acceleration structure for the copy. * pname:dst is the target acceleration structure for the copy. * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy. .Valid Usage **** include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] **** include::{generated}/validity/structs/VkCopyAccelerationStructureInfoKHR.adoc[] -- endif::VK_KHR_acceleration_structure[] [open,refpage='VkCopyAccelerationStructureModeKHR',desc='Acceleration structure copy mode',type='enums',alias='VkCopyAccelerationStructureModeNV'] -- :refpage: VkCopyAccelerationStructureModeKHR Possible values of pname:mode specifying additional operations to perform during the copy, are: include::{generated}/api/enums/VkCopyAccelerationStructureModeKHR.adoc[] ifdef::VK_NV_ray_tracing[] or the equivalent include::{generated}/api/enums/VkCopyAccelerationStructureModeNV.adoc[] endif::VK_NV_ray_tracing[] * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR creates a direct copy of the acceleration structure specified in pname:src into the one specified by pname:dst. The pname:dst acceleration structure must: have been created with the same parameters as pname:src. If pname:src contains references to other acceleration structures, pname:dst will reference the same acceleration structures. * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR creates a more compact version of an acceleration structure pname:src into pname:dst. The acceleration structure pname:dst must: have been created with a size at least as large as that returned by flink:vkCmdWriteAccelerationStructuresPropertiesKHR ifdef::VK_KHR_acceleration_structure[] or flink:vkWriteAccelerationStructuresPropertiesKHR endif::VK_KHR_acceleration_structure[] after the build of the acceleration structure specified by pname:src. If pname:src contains references to other acceleration structures, pname:dst will reference the same acceleration structures. * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR serializes the acceleration structure to a semi-opaque format which can be reloaded on a compatible implementation. * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR deserializes the semi-opaque serialization format in the buffer to the acceleration structure. -- [open,refpage='vkCmdCopyAccelerationStructureToMemoryKHR',desc='Copy an acceleration structure to device memory',type='protos'] -- :refpage: vkCmdCopyAccelerationStructureToMemoryKHR To copy an acceleration structure to device memory call: include::{generated}/api/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:pInfo is an a pointer to a slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation. Accesses to pname:pInfo->src must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. Accesses to the buffer indicated by pname:pInfo->dst.deviceAddress must: be synchronized with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of ename:VK_ACCESS_TRANSFER_WRITE_BIT. This command produces the same results as flink: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 flink:vkCmdCopyMemoryToAccelerationStructureKHR or flink:vkCopyMemoryToAccelerationStructureKHR. [[serialized-as-header]] The defined header structure for the serialized data consists of: * ename:VK_UUID_SIZE bytes of data matching sname:VkPhysicalDeviceIDProperties::pname:driverUUID * ename:VK_UUID_SIZE bytes of data identifying the compatibility for comparison using flink:vkGetDeviceAccelerationStructureCompatibilityKHR * A 64-bit integer of the total size matching the value queried using ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR * A 64-bit integer of the deserialized size to be passed in to sname:VkAccelerationStructureCreateInfoKHR::pname:size * A 64-bit integer of the count of the number of acceleration structure handles following. ifdef::VK_KHR_ray_tracing_maintenance1[] This value matches the value queried using ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. endif::VK_KHR_ray_tracing_maintenance1[] 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 ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] ifdef::VK_NV_ray_tracing[flink: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. .Valid Usage **** * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739]] pname:pInfo->dst.deviceAddress must: be a valid device address for a buffer bound to device memory * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03740]] pname:pInfo->dst.deviceAddress must: be aligned to `256` bytes * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03741]] If the buffer pointed to by pname:pInfo->dst.deviceAddress is non-sparse then it must: be bound completely and contiguously to a single slink:VkDeviceMemory object * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559]] The pname:buffer used to create pname:pInfo->src must: be bound to device memory **** include::{generated}/validity/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] -- [open,refpage='VkCopyAccelerationStructureToMemoryInfoKHR',desc='Parameters for serializing an acceleration structure',type='structs'] -- :refpage: VkCopyAccelerationStructureToMemoryInfoKHR include::{generated}/api/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:src is the source acceleration structure for the copy * pname:dst is the device or host address to memory which is the target for the copy * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy. .Valid Usage **** * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-src-04959]] The source acceleration structure pname:src must: have been constructed prior to the execution of this command * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-03561]] The memory pointed to by pname:dst must: be at least as large as the serialization size of pname:src, as reported by flink:vkWriteAccelerationStructuresPropertiesKHR or flink:vkCmdWriteAccelerationStructuresPropertiesKHR with a query type of ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-03412]] pname:mode must: be ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR **** include::{generated}/validity/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] -- [open,refpage='vkCmdCopyMemoryToAccelerationStructureKHR',desc='Copy device memory to an acceleration structure',type='protos'] -- :refpage: vkCmdCopyMemoryToAccelerationStructureKHR To copy device memory to an acceleration structure call: include::{generated}/api/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:pInfo is a pointer to a slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation. Accesses to pname:pInfo->dst must: be <> with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR <> and an <> of ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. Accesses to the buffer indicated by pname:pInfo->src.deviceAddress must: be synchronized with the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR pipeline stage and an access type of ename:VK_ACCESS_TRANSFER_READ_BIT. This command can accept acceleration structures produced by either flink:vkCmdCopyAccelerationStructureToMemoryKHR or flink:vkCopyAccelerationStructureToMemoryKHR. The structure provided as input to deserialize is as described in flink: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. .Valid Usage **** * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03742]] pname:pInfo->src.deviceAddress must: be a valid device address for a buffer bound to device memory * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03743]] pname:pInfo->src.deviceAddress must: be aligned to `256` bytes * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03744]] If the buffer pointed to by pname:pInfo->src.deviceAddress is non-sparse then it must: be bound completely and contiguously to a single slink:VkDeviceMemory object * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-buffer-03745]] The pname:buffer used to create pname:pInfo->dst must: be bound to device memory **** include::{generated}/validity/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] -- [open,refpage='VkCopyMemoryToAccelerationStructureInfoKHR',desc='Parameters for deserializing an acceleration structure',type='structs'] -- :refpage: VkCopyMemoryToAccelerationStructureInfoKHR The sname:VkCopyMemoryToAccelerationStructureInfoKHR structure is defined as: include::{generated}/api/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:src is the device or host address to memory containing the source data for the copy. * pname:dst is the target acceleration structure for the copy. * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value specifying additional operations to perform during the copy. .Valid Usage **** * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-src-04960]] The source memory pointed to by pname:src must: contain data previously serialized using flink:vkCmdCopyAccelerationStructureToMemoryKHR, potentially modified to relocate acceleration structure references as described in that command * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-03413]] pname:mode must: be ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pInfo-03414]] The data in pname:src must: have a format compatible with the destination physical device as returned by flink:vkGetDeviceAccelerationStructureCompatibilityKHR * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-03746]] pname:dst must: have been created with a pname:size greater than or equal to that used to serialize the data in pname:src **** include::{generated}/validity/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] -- [open,refpage='vkGetDeviceAccelerationStructureCompatibilityKHR',desc='Check if a serialized acceleration structure is compatible with the current device',type='protos'] -- :refpage: vkGetDeviceAccelerationStructureCompatibilityKHR To check if a serialized acceleration structure is compatible with the current device call: include::{generated}/api/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] * pname:device is the device to check the version against. * pname:pVersionInfo is a pointer to a slink:VkAccelerationStructureVersionInfoKHR structure specifying version information to check against the device. * pname:pCompatibility is a pointer to a elink:VkAccelerationStructureCompatibilityKHR value in which compatibility information is returned. .Valid Usage **** * [[VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-rayTracingPipeline-03661]] The <> or <> feature must: be enabled **** include::{generated}/validity/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] -- [open,refpage='VkAccelerationStructureVersionInfoKHR',desc='Acceleration structure version information',type='structs'] -- :refpage: VkAccelerationStructureVersionKHR The sname:VkAccelerationStructureVersionInfoKHR structure is defined as: include::{generated}/api/structs/VkAccelerationStructureVersionInfoKHR.adoc[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:pVersionData is a pointer to the version header of an acceleration structure as defined in flink:vkCmdCopyAccelerationStructureToMemoryKHR [NOTE] .Note ==== pname:pVersionData is a _pointer_ to an array of 2{times}ename:VK_UUID_SIZE code:uint8_t values instead of two ename:VK_UUID_SIZE arrays as the expected use case for this member is to be pointed at the header of a previously serialized acceleration structure (via flink:vkCmdCopyAccelerationStructureToMemoryKHR or flink:vkCopyAccelerationStructureToMemoryKHR) that is loaded in memory. Using arrays would necessitate extra memory copies of the UUIDs. ==== include::{generated}/validity/structs/VkAccelerationStructureVersionInfoKHR.adoc[] -- [open,refpage='VkAccelerationStructureCompatibilityKHR',desc='Acceleration structure compatibility',type='enums'] -- Possible values of pname:pCompatibility returned by flink:vkGetDeviceAccelerationStructureCompatibilityKHR are: include::{generated}/api/enums/VkAccelerationStructureCompatibilityKHR.adoc[] * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR if the pname:pVersionData version acceleration structure is compatible with pname:device. * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR if the pname:pVersionData version acceleration structure is not compatible with pname:device. -- [[host-acceleration-structure]] == Host Acceleration Structure Operations Implementations are also required to provide host implementations of the acceleration structure operations if the <> feature is enabled: * flink:vkBuildAccelerationStructuresKHR corresponding to flink:vkCmdBuildAccelerationStructuresKHR * flink:vkCopyAccelerationStructureKHR corresponding to flink:vkCmdCopyAccelerationStructureKHR * flink:vkCopyAccelerationStructureToMemoryKHR corresponding to flink:vkCmdCopyAccelerationStructureToMemoryKHR * flink:vkCopyMemoryToAccelerationStructureKHR corresponding to flink:vkCmdCopyMemoryToAccelerationStructureKHR * flink:vkWriteAccelerationStructuresPropertiesKHR corresponding to flink: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. [NOTE] .Note ==== The flink:vkBuildAccelerationStructuresKHR and flink: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 flink:vkBuildAccelerationStructuresKHR to build a structure, compact it on the device using flink:vkCmdCopyAccelerationStructureKHR, and serialize the result using flink:vkCopyAccelerationStructureToMemoryKHR. ==== [NOTE] .Note ==== 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. ==== [open,refpage='vkBuildAccelerationStructuresKHR',desc='Build an acceleration structure on the host',type='protos'] -- :refpage: vkBuildAccelerationStructuresKHR To build acceleration structures on the host, call: include::{generated}/api/protos/vkBuildAccelerationStructuresKHR.adoc[] * pname:device is the sname:VkDevice for which the acceleration structures are being built. * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to <> for this command. * pname:infoCount is the number of acceleration structures to build. It specifies the number of the pname:pInfos structures and pname:ppBuildRangeInfos pointers that must: be provided. * pname:pInfos is a pointer to an array of pname:infoCount slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure. * pname:ppBuildRangeInfos is a pointer to an array of pname:infoCount pointers to arrays of slink:VkAccelerationStructureBuildRangeInfoKHR structures. Each pname:ppBuildRangeInfos[i] is a pointer to an array of pname:pInfos[i].pname:geometryCount slink:VkAccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pname:pInfos[i]. This command fulfills the same task as flink:vkCmdBuildAccelerationStructuresKHR but is executed by the host. The fname: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. [NOTE] .Note ==== This means that an application cannot: build a top-level acceleration structure in the same flink: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. ==== .Valid Usage **** :maxinstancecheck: pname:ppBuildRangeInfos[i][j].pname:primitiveCount include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] include::{chapters}/commonvalidity/build_acceleration_structure_nonindirect_common.adoc[] include::{chapters}/commonvalidity/deferred_operations_common.adoc[] * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03722]] For each element of pname:pInfos, the pname:buffer used to create its pname:dstAccelerationStructure member must: be bound to host-visible device memory * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03723]] For each element of pname:pInfos, if its pname:mode member is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer used to create its pname:srcAccelerationStructure member must: be bound to host-visible device memory * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03724]] For each element of pname:pInfos, the pname:buffer used to create each acceleration structure referenced by the pname:geometry.instances.data member of any element of pname:pGeometries or pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be bound to host-visible device memory * [[VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581]] The <> feature must: be enabled * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03725]] If pname:pInfos[i].pname:mode is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses between pname:pInfos[i].pname:scratchData.hostAddress and pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid host memory, where N is given by the pname:buildScratchSize member of the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03726]] If pname:pInfos[i].pname:mode is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses between pname:pInfos[i].pname:scratchData.hostAddress and pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid host memory, where N is given by the pname:updateScratchSize member of the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure and primitive count * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03771]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, pname:geometry.triangles.vertexData.hostAddress must: be a valid host address * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03772]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if pname:geometry.triangles.indexType is not ename:VK_INDEX_TYPE_NONE_KHR, pname:geometry.triangles.indexData.hostAddress must: be a valid host address * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03773]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if pname:geometry.triangles.transformData.hostAddress is not `0`, it must: be a valid host address * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03774]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_AABBS_KHR, pname:geometry.aabbs.data.hostAddress must: be a valid host address ifdef::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03775]] For each element of pname:pInfos, the pname:buffer used to create its pname:dstAccelerationStructure member must: be bound to memory that was not allocated with multiple instances * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03776]] For each element of pname:pInfos, if its pname:mode member is ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer used to create its pname:srcAccelerationStructure member must: be bound to memory that was not allocated with multiple instances * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03777]] For each element of pname:pInfos, the pname:buffer used to create each acceleration structure referenced by the pname:geometry.instances.data member of any element of pname:pGeometries or pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be bound to memory that was not allocated with multiple instances endif::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03778]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, pname:geometry.instances.data.hostAddress must: be a valid host address * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03779]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each slink:VkAccelerationStructureInstanceKHR::pname:accelerationStructureReference value in pname:geometry.instances.data.hostAddress must be a valid slink:VkAccelerationStructureKHR object ifdef::VK_NV_ray_tracing_motion_blur[] * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-04930]] For any element of pname:pInfos[i].pname:pGeometries or pname:pInfos[i].pname:ppGeometries with a pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR with ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV set, each pname:accelerationStructureReference in any structure in slink:VkAccelerationStructureMotionInstanceNV value in pname:geometry.instances.data.hostAddress must be a valid slink:VkAccelerationStructureKHR object endif::VK_NV_ray_tracing_motion_blur[] **** include::{generated}/validity/protos/vkBuildAccelerationStructuresKHR.adoc[] -- [open,refpage='vkCopyAccelerationStructureKHR',desc='Copy an acceleration structure on the host',type='protos'] -- :refpage: vkCopyAccelerationStructureKHR To copy or compact an acceleration structure on the host, call: include::{generated}/api/protos/vkCopyAccelerationStructureKHR.adoc[] * pname:device is the device which owns the acceleration structures. * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to <> for this command. * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR structure defining the copy operation. This command fulfills the same task as flink:vkCmdCopyAccelerationStructureKHR but is executed by the host. .Valid Usage **** include::{chapters}/commonvalidity/deferred_operations_common.adoc[] * [[VUID-vkCopyAccelerationStructureKHR-buffer-03727]] The pname:buffer used to create pname:pInfo->src must: be bound to host-visible device memory * [[VUID-vkCopyAccelerationStructureKHR-buffer-03728]] The pname:buffer used to create pname:pInfo->dst must: be bound to host-visible device memory * [[VUID-vkCopyAccelerationStructureKHR-accelerationStructureHostCommands-03582]] The <> feature must: be enabled ifdef::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkCopyAccelerationStructureKHR-buffer-03780]] The pname:buffer used to create pname:pInfo->src must: be bound to memory that was not allocated with multiple instances * [[VUID-vkCopyAccelerationStructureKHR-buffer-03781]] The pname:buffer used to create pname:pInfo->dst must: be bound to memory that was not allocated with multiple instances endif::VK_KHR_device_group,VK_VERSION_1_1[] **** include::{generated}/validity/protos/vkCopyAccelerationStructureKHR.adoc[] -- [open,refpage='vkCopyMemoryToAccelerationStructureKHR',desc='Deserialize an acceleration structure on the host',type='protos'] -- :refpage: vkCopyMemoryToAccelerationStructureKHR To copy host accessible memory to an acceleration structure, call: include::{generated}/api/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] * pname:device is the device which owns pname:pInfo->dst. * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to <> for this command. * pname:pInfo is a pointer to a slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation. This command fulfills the same task as flink:vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host. This command can accept acceleration structures produced by either flink:vkCmdCopyAccelerationStructureToMemoryKHR or flink:vkCopyAccelerationStructureToMemoryKHR. .Valid Usage **** include::{chapters}/commonvalidity/deferred_operations_common.adoc[] * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03729]] pname:pInfo->src.hostAddress must: be a valid host pointer * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03750]] pname:pInfo->src.hostAddress must: be aligned to 16 bytes * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03730]] The pname:buffer used to create pname:pInfo->dst must: be bound to host-visible device memory * [[VUID-vkCopyMemoryToAccelerationStructureKHR-accelerationStructureHostCommands-03583]] The <> feature must: be enabled ifdef::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03782]] The pname:buffer used to create pname:pInfo->dst must: be bound to memory that was not allocated with multiple instances endif::VK_KHR_device_group,VK_VERSION_1_1[] **** include::{generated}/validity/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] -- [open,refpage='vkCopyAccelerationStructureToMemoryKHR',desc='Serialize an acceleration structure on the host',type='protos'] -- :refpage: vkCopyAccelerationStructureToMemoryKHR To copy an acceleration structure to host accessible memory, call: include::{generated}/api/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] * pname:device is the device which owns pname:pInfo->src. * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to <> for this command. * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation. This command fulfills the same task as flink:vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host. This command produces the same results as flink: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 flink:vkCmdCopyMemoryToAccelerationStructureKHR or flink:vkCopyMemoryToAccelerationStructureKHR. .Valid Usage **** include::{chapters}/commonvalidity/deferred_operations_common.adoc[] * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03731]] The pname:buffer used to create pname:pInfo->src must: be bound to host-visible device memory * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03732]] pname:pInfo->dst.hostAddress must: be a valid host pointer * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03751]] pname:pInfo->dst.hostAddress must: be aligned to 16 bytes * [[VUID-vkCopyAccelerationStructureToMemoryKHR-accelerationStructureHostCommands-03584]] The <> feature must: be enabled ifdef::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03783]] The pname:buffer used to create pname:pInfo->src must: be bound to memory that was not allocated with multiple instances endif::VK_KHR_device_group,VK_VERSION_1_1[] **** include::{generated}/validity/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] -- [open,refpage='vkWriteAccelerationStructuresPropertiesKHR',desc='Query acceleration structure meta-data on the host',type='protos'] -- :refpage: vkWriteAccelerationStructuresPropertiesKHR To query acceleration structure size parameters on the host, call: include::{generated}/api/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] * pname:device is the device which owns the acceleration structures in pname:pAccelerationStructures. * pname:accelerationStructureCount is the count of acceleration structures for which to query the property. * pname:pAccelerationStructures is a pointer to an array of existing previously built acceleration structures. * pname:queryType is a elink:VkQueryType value specifying the property to be queried. * 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. * pname:stride is the stride in bytes between results for individual queries within pname:pData. This command fulfills the same task as flink:vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the host. .Valid Usage **** include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then pname:stride must: be a multiple of the size of basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then pname:pData must: point to a basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then pname:stride must: be a multiple of the size of basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then pname:pData must: point to a basetype:VkDeviceSize ifdef::VK_KHR_ray_tracing_maintenance1[] * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06731]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:stride must: be a multiple of the size of basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06732]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:pData must: point to a basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06733]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then pname:stride must: be a multiple of the size of basetype:VkDeviceSize * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06734]] If pname:queryType is ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then pname:pData must: point to a basetype:VkDeviceSize endif::VK_KHR_ray_tracing_maintenance1[] * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452]] pname:dataSize must: be greater than or equal to [eq]#pname:accelerationStructureCount*pname:stride# * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03733]] The pname:buffer used to create each acceleration structure in pname:pAccelerationStructures must: be bound to host-visible device memory * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureHostCommands-03585]] The <> feature must: be enabled ifdef::VK_KHR_device_group,VK_VERSION_1_1[] * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03784]] The pname:buffer used to create each acceleration structure in pname:pAccelerationStructures must: be bound to memory that was not allocated with multiple instances endif::VK_KHR_device_group,VK_VERSION_1_1[] **** include::{generated}/validity/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] --