1// Copyright 2020-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[acceleration-structure]] 6= Acceleration Structures 7 8 9[[acceleration-structure-def]] 10== Acceleration Structures 11 12_Acceleration structures_ are data structures used by the implementation to 13efficiently manage scene geometry as it is <<ray-traversal, traversed during 14a ray tracing query>>. 15The application is responsible for managing acceleration structure objects 16(see <<resources-acceleration-structures,Acceleration Structures>>), 17including allocation, destruction, executing builds or updates, and 18synchronizing resources used during ray tracing queries. 19 20There are two types of acceleration structures, _top level acceleration 21structures_ and _bottom level acceleration structures_. 22 23An acceleration structure is considered to be constructed if an 24<<acceleration-structure-building,acceleration structure build command>> or 25<<acceleration-structure-copying,copy command>> has been executed with the 26given acceleration structure as the destination. 27 28[[fig-accelstruct]] 29image::{images}/accelstruct.svg[align="center",title="Acceleration Structure",opts="{imageopts}"] 30 31.Caption 32**** 33The diagram shows the relationship between top and bottom level acceleration 34structures. 35**** 36 37 38[[acceleration-structure-geometry]] 39=== Geometry 40 41_Geometries_ refer to a triangle or axis-aligned bounding box. 42 43 44[[acceleration-structure-top-level]] 45=== Top Level Acceleration Structures 46 47Opaque acceleration structure for an array of instances. 48The descriptor or device address referencing this is the starting point for 49traversal. 50 51The top level acceleration structure takes a reference to any bottom level 52acceleration structure referenced by its instances. 53Those bottom level acceleration structure objects must: be valid when the 54top level acceleration structure is accessed. 55 56 57[[acceleration-structure-bottom-level]] 58=== Bottom Level Acceleration Structures 59 60Opaque acceleration structure for an array of geometries. 61 62 63[[acceleration-structure-update]] 64=== Acceleration Structure Update Rules 65 66The API defines two types of operations to produce acceleration structures 67from geometry: 68 69 * A _build_ operation is used to construct an acceleration structure. 70 * An _update_ operation is used to modify an existing acceleration 71 structure. 72 73An update operation imposes certain constraints on the input, in exchange 74for considerably faster execution. 75When performing an update, the application is required to provide a full 76description of the acceleration structure, but is prohibited from changing 77anything other than instance definitions, transform matrices, and vertex or 78AABB positions. 79All other aspects of the description must: exactly match the one from the 80original build. 81 82More precisely, the application must: not use an update operation to do any 83of the following: 84 85 * Change primitives or instances from _active_ to _inactive_, or vice 86 versa (as defined in <<acceleration-structure-inactive-prims>>). 87 * Change the index or vertex formats of triangle geometry. 88 * Change triangle geometry transform pointers from null to non-null or 89 vice versa. 90 * Change the number of geometries or instances in the structure. 91 * Change the geometry flags for any geometry in the structure. 92 * Change the number of vertices or primitives for any geometry in the 93 structure. 94 95ifdef::VK_EXT_opacity_micromap[] 96 97If the original acceleration structure was built using opacity micromaps and 98ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT 99was set in pname:flags, the application must: provide the corresponding 100micromap information to the update operation. 101The application is prohibited from changing anything other than the specific 102opacity values assigned to the triangles. 103 104More precisely, the application must: not use an update operation to do any 105of the following: 106 107 * Remove micromaps or elink:VkOpacityMicromapSpecialIndexEXT values from a 108 geometry which previously had them, or vice versa. 109 * Change between use of elink:VkOpacityMicromapSpecialIndexEXT values and 110 explicit micro-map triangles. 111 * Change the subdivision level or format of the micromap triangle 112 associated with any acceleration-structure triangle. 113 114If the original acceleration structure was built using opacity micromaps and 115ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT was 116set in pname:flags, the application must: provide a micromap to the update 117operation. 118 119If the original acceleration structure was built using opacity micromaps and 120neither opacity micromap update flag is set the application must: provide 121the original micromap to the update operation. 122 123endif::VK_EXT_opacity_micromap[] 124 125ifdef::VK_NV_displacement_micromap[] 126If the original acceleration structure was built using displacement 127micromaps and 128ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV 129was set in pname:flags, the application must: provide a displacement 130micromap to the update operation. 131 132If the original acceleration structure was built using displacement 133micromaps and the displacement micromap update flag is not set the 134application must: provide the original micromap to the update operation. 135endif::VK_NV_displacement_micromap[] 136 137[[acceleration-structure-inactive-prims]] 138=== Inactive Primitives and Instances 139 140Acceleration structures allow the use of particular input values to signal 141_inactive_ primitives or instances. 142 143An _inactive_ triangle is one for which the first (X) component of any 144vertex is NaN. 145If any other vertex component is NaN, and the first is not, the behavior is 146undefined:. 147If the vertex format does not have a NaN representation, then all triangles 148are considered active. 149 150An _inactive_ instance is one whose acceleration structure reference is `0`. 151 152An _inactive_ AABB is one for which the minimum X coordinate is NaN. 153If any other component is NaN, and the first is not, the behavior is 154undefined:. 155 156In the above definitions, "`NaN`" refers to any type of NaN. 157Signaling, non-signaling, quiet, loud, or otherwise. 158 159An inactive object is considered invisible to all rays, and should: not be 160represented in the acceleration structure. 161Implementations should: ensure that the presence of inactive objects does 162not seriously degrade traversal performance. 163 164Inactive objects are counted in the auto-generated index sequences which are 165provided to shaders via code:InstanceId and code:PrimitiveId SPIR-V 166decorations. 167This allows objects in the scene to change freely between the active and 168inactive states, without affecting the layout of any arrays which are being 169indexed using the ID values. 170 171Any transition between the active and inactive states requires a full 172acceleration structure rebuild. 173Applications must: not perform an acceleration structure update where an 174object is active in the source acceleration structure but would be inactive 175in the destination, or vice versa. 176 177 178[[acceleration-structure-building]] 179=== Building Acceleration Structures 180 181ifdef::VK_NV_ray_tracing[] 182[open,refpage='vkCmdBuildAccelerationStructureNV',desc='Build an acceleration structure',type='protos'] 183-- 184:refpage: vkCmdBuildAccelerationStructureNV 185 186To build an acceleration structure call: 187 188include::{generated}/api/protos/vkCmdBuildAccelerationStructureNV.adoc[] 189 190 * pname:commandBuffer is the command buffer into which the command will be 191 recorded. 192 * pname:pInfo contains the shared information for the acceleration 193 structure's structure. 194 * pname:instanceData is the buffer containing an array of 195 slink:VkAccelerationStructureInstanceKHR structures defining 196 acceleration structures. 197 This parameter must: be `NULL` for bottom level acceleration structures. 198 * pname:instanceOffset is the offset in bytes (relative to the start of 199 pname:instanceData) at which the instance data is located. 200 * pname:update specifies whether to update the pname:dst acceleration 201 structure with the data in pname:src. 202 * pname:dst is a pointer to the target acceleration structure for the 203 build. 204 * pname:src is a pointer to an existing acceleration structure that is to 205 be used to update the pname:dst acceleration structure. 206 * pname:scratch is the slink:VkBuffer that will be used as scratch memory 207 for the build. 208 * pname:scratchOffset is the offset in bytes relative to the start of 209 pname:scratch that will be used as a scratch memory. 210 211Accesses to pname:dst, pname:src, and pname:scratch must: be 212<<synchronization-dependencies,synchronized>> with the 213ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 214<<synchronization-pipeline-stages, pipeline stage>> and an 215<<synchronization-access-types, access type>> of 216ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 217ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. 218 219.Valid Usage 220**** 221 * [[VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241]] 222 pname:geometryCount must: be less than or equal to 223 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount 224 * [[VUID-vkCmdBuildAccelerationStructureNV-dst-02488]] 225 pname:dst must: have been created with compatible 226 slink:VkAccelerationStructureInfoNV where 227 slink:VkAccelerationStructureInfoNV::pname:type and 228 slink:VkAccelerationStructureInfoNV::pname:flags are identical, 229 slink:VkAccelerationStructureInfoNV::pname:instanceCount and 230 slink:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst 231 are greater than or equal to the build size and each geometry in 232 slink:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has 233 greater than or equal to the number of vertices, indices, and AABBs 234 * [[VUID-vkCmdBuildAccelerationStructureNV-update-02489]] 235 If pname:update is ename:VK_TRUE, pname:src must: not be 236 dlink:VK_NULL_HANDLE 237 * [[VUID-vkCmdBuildAccelerationStructureNV-update-02490]] 238 If pname:update is ename:VK_TRUE, pname:src must: have previously been 239 constructed with 240 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in 241 slink:VkAccelerationStructureInfoNV::pname:flags in the original build 242 * [[VUID-vkCmdBuildAccelerationStructureNV-update-02491]] 243 If pname:update is ename:VK_FALSE, the pname:size member of the 244 slink:VkMemoryRequirements structure returned from a call to 245 flink:vkGetAccelerationStructureMemoryRequirementsNV with 246 slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure 247 set to pname:dst and 248 slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to 249 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 250 must: be less than or equal to the size of pname:scratch minus 251 pname:scratchOffset 252 * [[VUID-vkCmdBuildAccelerationStructureNV-update-02492]] 253 If pname:update is ename:VK_TRUE, the pname:size member of the 254 slink:VkMemoryRequirements structure returned from a call to 255 flink:vkGetAccelerationStructureMemoryRequirementsNV with 256 slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure 257 set to pname:dst and 258 slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to 259 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 260 must: be less than or equal to the size of pname:scratch minus 261 pname:scratchOffset 262 * [[VUID-vkCmdBuildAccelerationStructureNV-scratch-03522]] 263 pname:scratch must: have been created with 264 ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag 265 * [[VUID-vkCmdBuildAccelerationStructureNV-instanceData-03523]] 266 If pname:instanceData is not dlink:VK_NULL_HANDLE, pname:instanceData 267 must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV 268 usage flag 269 * [[VUID-vkCmdBuildAccelerationStructureNV-accelerationStructureReference-03786]] 270 Each 271 slink:VkAccelerationStructureInstanceKHR::pname:accelerationStructureReference 272 value in pname:instanceData must: be a valid device address containing a 273 value obtained from flink:vkGetAccelerationStructureHandleNV 274 * [[VUID-vkCmdBuildAccelerationStructureNV-update-03524]] 275 If pname:update is ename:VK_TRUE, then objects that were previously 276 active must: not be made inactive as per 277 <<acceleration-structure-inactive-prims>> 278 * [[VUID-vkCmdBuildAccelerationStructureNV-update-03525]] 279 If pname:update is ename:VK_TRUE, then objects that were previously 280 inactive must: not be made active as per 281 <<acceleration-structure-inactive-prims>> 282 * [[VUID-vkCmdBuildAccelerationStructureNV-update-03526]] 283 If pname:update is ename:VK_TRUE, the pname:src and pname:dst objects 284 must: either be the same object or not have any 285 <<resources-memory-aliasing, memory aliasing>> 286 * [[VUID-vkCmdBuildAccelerationStructureNV-dst-07787]] 287 pname:dst must: be bound completely and contiguously to a single 288 sname:VkDeviceMemory object via 289 flink:vkBindAccelerationStructureMemoryNV 290 291**** 292 293include::{generated}/validity/protos/vkCmdBuildAccelerationStructureNV.adoc[] 294-- 295endif::VK_NV_ray_tracing[] 296 297ifdef::VK_KHR_acceleration_structure[] 298[open,refpage='vkCmdBuildAccelerationStructuresKHR',desc='Build an acceleration structure',type='protos'] 299-- 300:refpage: vkCmdBuildAccelerationStructuresKHR 301 302To build acceleration structures call: 303 304include::{generated}/api/protos/vkCmdBuildAccelerationStructuresKHR.adoc[] 305 306 * pname:commandBuffer is the command buffer into which the command will be 307 recorded. 308 * pname:infoCount is the number of acceleration structures to build. 309 It specifies the number of the pname:pInfos structures and 310 pname:ppBuildRangeInfos pointers that must: be provided. 311 * pname:pInfos is a pointer to an array of pname:infoCount 312 slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining 313 the geometry used to build each acceleration structure. 314 * pname:ppBuildRangeInfos is a pointer to an array of pname:infoCount 315 pointers to arrays of slink:VkAccelerationStructureBuildRangeInfoKHR 316 structures. 317 Each pname:ppBuildRangeInfos[i] is a pointer to an array of 318 pname:pInfos[i].pname:geometryCount 319 slink:VkAccelerationStructureBuildRangeInfoKHR structures defining 320 dynamic offsets to the addresses where geometry data is stored, as 321 defined by pname:pInfos[i]. 322 323The fname:vkCmdBuildAccelerationStructuresKHR command provides the ability 324to initiate multiple acceleration structures builds, however there is no 325ordering or synchronization implied between any of the individual 326acceleration structure builds. 327 328[NOTE] 329.Note 330==== 331This means that an application cannot: build a top-level acceleration 332structure in the same flink:vkCmdBuildAccelerationStructuresKHR call as the 333associated bottom-level or instance acceleration structures are being built. 334There also cannot: be any memory aliasing between any acceleration structure 335memories or scratch memories being used by any of the builds. 336==== 337 338[[acceleration-structure-scratch]] 339Accesses to the acceleration structure scratch buffers as identified by the 340slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:scratchData buffer 341device addresses must: be <<synchronization-dependencies,synchronized>> with 342the ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 343<<synchronization-pipeline-stages, pipeline stage>> and an 344<<synchronization-access-types, access type>> of 345(ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR | 346ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR). 347Accesses to each 348slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:srcAccelerationStructure 349and 350slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:dstAccelerationStructure 351must: be <<synchronization-dependencies,synchronized>> with the 352ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 353<<synchronization-pipeline-stages, pipeline stage>> and an 354<<synchronization-access-types, access type>> of 355ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 356ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR, as appropriate. 357 358Accesses to other input buffers as identified by any used values of 359ifdef::VK_NV_ray_tracing_motion_blur[] 360slink:VkAccelerationStructureGeometryMotionTrianglesDataNV::pname:vertexData, 361endif::VK_NV_ray_tracing_motion_blur[] 362slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData, 363slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData, 364slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData, 365slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data, and 366slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data must: be 367<<synchronization-dependencies,synchronized>> with the 368ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 369<<synchronization-pipeline-stages, pipeline stage>> and an 370<<synchronization-access-types, access type>> of 371ename:VK_ACCESS_SHADER_READ_BIT. 372 373 374.Valid Usage 375**** 376 * [[VUID-vkCmdBuildAccelerationStructuresKHR-accelerationStructure-08923]] 377 The <<features-accelerationStructure, 378 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 379 feature must: be enabled 380 381:maxinstancecheck: pname:ppBuildRangeInfos[i][j].pname:primitiveCount 382include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] 383include::{chapters}/commonvalidity/build_acceleration_structure_device_common.adoc[] 384include::{chapters}/commonvalidity/build_acceleration_structure_nonindirect_common.adoc[] 385**** 386 387include::{generated}/validity/protos/vkCmdBuildAccelerationStructuresKHR.adoc[] 388-- 389 390[open,refpage='vkCmdBuildAccelerationStructuresIndirectKHR',desc='Build an acceleration structure with some parameters provided on the device',type='protos'] 391-- 392:refpage: vkCmdBuildAccelerationStructuresIndirectKHR 393 394To build acceleration structures with some parameters sourced on the device 395call: 396 397include::{generated}/api/protos/vkCmdBuildAccelerationStructuresIndirectKHR.adoc[] 398 399 * pname:commandBuffer is the command buffer into which the command will be 400 recorded. 401 * pname:infoCount is the number of acceleration structures to build. 402 * pname:pInfos is a pointer to an array of pname:infoCount 403 slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining 404 the geometry used to build each acceleration structure. 405 * pname:pIndirectDeviceAddresses is a pointer to an array of 406 pname:infoCount buffer device addresses which point to 407 pname:pInfos[i].pname:geometryCount 408 slink:VkAccelerationStructureBuildRangeInfoKHR structures defining 409 dynamic offsets to the addresses where geometry data is stored, as 410 defined by pname:pInfos[i]. 411 * pname:pIndirectStrides is a pointer to an array of pname:infoCount byte 412 strides between elements of pname:pIndirectDeviceAddresses. 413 * pname:ppMaxPrimitiveCounts is a pointer to an array of pname:infoCount 414 pointers to arrays of pname:pInfos[i].pname:geometryCount values 415 indicating the maximum number of primitives that will be built by this 416 command for each geometry. 417 418Accesses to acceleration structures, scratch buffers, vertex buffers, index 419buffers, and instance buffers must be synchronized as with 420<<acceleration-structure-scratch,vkCmdBuildAccelerationStructuresKHR>>. 421 422Accesses to any element of pname:pIndirectDeviceAddresses must: be 423<<synchronization-dependencies,synchronized>> with the 424ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 425<<synchronization-pipeline-stages, pipeline stage>> and an 426<<synchronization-access-types, access type>> of 427ename:VK_ACCESS_INDIRECT_COMMAND_READ_BIT. 428 429 430.Valid Usage 431**** 432 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-accelerationStructureIndirectBuild-03650]] 433 The <<features-accelerationStructureIndirectBuild, 434 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureIndirectBuild>> 435 feature must: be enabled 436 437:maxinstancecheck: pname:ppMaxPrimitiveCounts[i][j] 438include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] 439include::{chapters}/commonvalidity/build_acceleration_structure_device_common.adoc[] 440 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03645]] 441 For any element of pname:pIndirectDeviceAddresses, if the buffer from 442 which it was queried is non-sparse then it must: be bound completely and 443 contiguously to a single slink:VkDeviceMemory object 444 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03646]] 445 For any element of pname:pIndirectDeviceAddresses[i], all device 446 addresses between pname:pIndirectDeviceAddresses[i] and 447 [eq]#pname:pIndirectDeviceAddresses[i] {plus} 448 (pname:pInfos[i].pname:geometryCount {times} pname:pIndirectStrides[i]) - 449 1# must: be in the buffer device address range of the same buffer 450 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03647]] 451 For any element of pname:pIndirectDeviceAddresses, the buffer from which 452 it was queried must: have been created with the 453 ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set 454 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03648]] 455 Each element of pname:pIndirectDeviceAddresses must: be a multiple of 456 `4` 457 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectStrides-03787]] 458 Each element of pname:pIndirectStrides must: be a multiple of `4` 459 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-commandBuffer-03649]] 460 pname:commandBuffer must: not be a protected command buffer 461 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pIndirectDeviceAddresses-03651]] 462 Each slink:VkAccelerationStructureBuildRangeInfoKHR structure referenced 463 by any element of pname:pIndirectDeviceAddresses must: be a valid 464 slink:VkAccelerationStructureBuildRangeInfoKHR structure 465 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-pInfos-03652]] 466 pname:pInfos[i].pname:dstAccelerationStructure must: have been created 467 with a value of slink:VkAccelerationStructureCreateInfoKHR::pname:size 468 greater than or equal to the memory size required by the build 469 operation, as returned by flink:vkGetAccelerationStructureBuildSizesKHR 470 with [eq]#pname:pBuildInfo = pname:pInfos[i]# and 471 [eq]#pname:pMaxPrimitiveCounts = pname:ppMaxPrimitiveCounts[i]# 472 * [[VUID-vkCmdBuildAccelerationStructuresIndirectKHR-ppMaxPrimitiveCounts-03653]] 473 Each pname:ppMaxPrimitiveCounts[i][j] must: be greater than or equal to 474 the pname:primitiveCount value specified by the 475 slink:VkAccelerationStructureBuildRangeInfoKHR structure located at 476 [eq]#pname:pIndirectDeviceAddresses[i] {plus} (code:j {times} 477 pname:pIndirectStrides[i])# 478**** 479 480include::{generated}/validity/protos/vkCmdBuildAccelerationStructuresIndirectKHR.adoc[] 481-- 482 483 484[open,refpage='VkAccelerationStructureBuildGeometryInfoKHR',desc='Structure specifying the geometry data used to build an acceleration structure',type='structs'] 485-- 486:refpage: VkAccelerationStructureBuildGeometryInfoKHR 487 488The sname:VkAccelerationStructureBuildGeometryInfoKHR structure is defined 489as: 490 491include::{generated}/api/structs/VkAccelerationStructureBuildGeometryInfoKHR.adoc[] 492 493 * pname:sType is a elink:VkStructureType value identifying this structure. 494 * pname:pNext is `NULL` or a pointer to a structure extending this 495 structure. 496 * pname:type is a elink:VkAccelerationStructureTypeKHR value specifying 497 the type of acceleration structure being built. 498 * pname:flags is a bitmask of 499 elink:VkBuildAccelerationStructureFlagBitsKHR specifying additional 500 parameters of the acceleration structure. 501 * pname:mode is a elink:VkBuildAccelerationStructureModeKHR value 502 specifying the type of operation to perform. 503 * pname:srcAccelerationStructure is a pointer to an existing acceleration 504 structure that is to be used to update the pname:dst acceleration 505 structure when pname:mode is 506 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR. 507 * pname:dstAccelerationStructure is a pointer to the target acceleration 508 structure for the build. 509 * pname:geometryCount specifies the number of geometries that will be 510 built into pname:dstAccelerationStructure. 511 * pname:pGeometries is a pointer to an array of 512 slink:VkAccelerationStructureGeometryKHR structures. 513 * pname:ppGeometries is a pointer to an array of pointers to 514 slink:VkAccelerationStructureGeometryKHR structures. 515 * pname:scratchData is the device or host address to memory that will be 516 used as scratch memory for the build. 517 518Only one of pname:pGeometries or pname:ppGeometries can: be a valid pointer, 519the other must: be `NULL`. 520Each element of the non-`NULL` array describes the data used to build each 521acceleration structure geometry. 522 523ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 524[[acceleration-structure-geometry-index]] 525The index of each element of the pname:pGeometries or pname:ppGeometries 526members of slink:VkAccelerationStructureBuildGeometryInfoKHR is used as the 527_geometry index_ during ray traversal. 528ifdef::VK_KHR_ray_tracing_pipeline[] 529The geometry index is available in ray shaders via the 530<<interfaces-builtin-variables-raygeometryindex,code:RayGeometryIndexKHR 531built-in>>, and is <<shader-binding-table-hit-shader-indexing, used to 532determine hit and intersection shaders executed during traversal>>. 533endif::VK_KHR_ray_tracing_pipeline[] 534ifdef::VK_KHR_ray_query[] 535The geometry index is available to ray queries via the 536code:OpRayQueryGetIntersectionGeometryIndexKHR instruction. 537endif::VK_KHR_ray_query[] 538endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 539 540ifdef::VK_NV_ray_tracing_motion_blur[] 541[[acceleration-structure-motion-instances]] 542Setting ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in pname:flags 543indicates that this build is a motion top level acceleration structure. 544A motion top level uses instances of format 545slink:VkAccelerationStructureMotionInstanceNV if 546slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:arrayOfPointers 547is ename:VK_FALSE. 548 549If 550slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:arrayOfPointers 551is ename:VK_TRUE, the pointer for each element of the array of instance 552pointers consists of 4 bits of 553ename:VkAccelerationStructureMotionInstanceTypeNV in the low 4 bits of the 554pointer identifying the type of structure at the pointer. 555The device address accessed is the value in the array with the low 4 bits 556set to zero. 557The structure at the pointer is one of 558slink:VkAccelerationStructureInstanceKHR, 559slink:VkAccelerationStructureMatrixMotionInstanceNV or 560slink:VkAccelerationStructureSRTMotionInstanceNV, depending on the type 561value encoded in the low 4 bits. 562 563A top level acceleration structure with either motion instances or vertex 564motion in its instances must: set 565ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV in pname:flags. 566endif::VK_NV_ray_tracing_motion_blur[] 567 568Members pname:srcAccelerationStructure and pname:dstAccelerationStructure 569may: be the same or different for an update operation (when pname:mode is 570ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR). 571If they are the same, the update happens in-place. 572Otherwise, the target acceleration structure is updated and the source is 573not modified. 574 575.Valid Usage 576**** 577 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03654]] 578 pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 579 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-pGeometries-03788]] 580 Only one of pname:pGeometries or pname:ppGeometries can: be a valid 581 pointer, the other must: be `NULL` 582 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03789]] 583 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, the 584 pname:geometryType member of elements of either pname:pGeometries or 585 pname:ppGeometries must: be ename:VK_GEOMETRY_TYPE_INSTANCES_KHR 586 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03790]] 587 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, 588 pname:geometryCount must: be `1` 589 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03791]] 590 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR 591 the pname:geometryType member of elements of either pname:pGeometries or 592 pname:ppGeometries must: not be ename:VK_GEOMETRY_TYPE_INSTANCES_KHR 593 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03792]] 594 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR 595 then the pname:geometryType member of each geometry in either 596 pname:pGeometries or pname:ppGeometries must: be the same 597 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03793]] 598 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR 599 then pname:geometryCount must: be less than or equal to 600 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxGeometryCount 601 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03794]] 602 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR 603 and the pname:geometryType member of either pname:pGeometries or 604 pname:ppGeometries is ename:VK_GEOMETRY_TYPE_AABBS_KHR, the total number 605 of AABBs in all geometries must: be less than or equal to 606 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPrimitiveCount 607 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-type-03795]] 608 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR 609 and the pname:geometryType member of either pname:pGeometries or 610 pname:ppGeometries is ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the total 611 number of triangles in all geometries must: be less than or equal to 612 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPrimitiveCount 613 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-03796]] 614 If pname:flags has the 615 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR bit set, 616 then it must: not have the 617 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR bit set 618ifdef::VK_NV_ray_tracing_motion_blur[] 619 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-dstAccelerationStructure-04927]] 620 If pname:dstAccelerationStructure was created with 621 ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in 622 slink:VkAccelerationStructureCreateInfoKHR::pname:flags, 623 ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV must: be set in 624 pname:flags 625 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04928]] 626 If ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in 627 pname:flags, pname:dstAccelerationStructure must: have been created with 628 ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV set in 629 slink:VkAccelerationStructureCreateInfoKHR::pname:flags 630 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-04929]] 631 If ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV is set in 632 pname:flags, pname:type must: not be 633 ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 634endif::VK_NV_ray_tracing_motion_blur[] 635ifdef::VK_EXT_opacity_micromap[] 636 * [[VUID-VkAccelerationStructureBuildGeometryInfoKHR-flags-07334]] 637 If pname:flags has the 638 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT 639 bit set then it must: not have the 640 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT 641 bit set 642endif::VK_EXT_opacity_micromap[] 643**** 644include::{generated}/validity/structs/VkAccelerationStructureBuildGeometryInfoKHR.adoc[] 645-- 646 647[open,refpage='VkBuildAccelerationStructureModeKHR',desc='Enum specifying the type of build operation to perform',type='enums'] 648-- 649:refpage: VkBuildAccelerationStructureModeKHR 650 651The ename:VkBuildAccelerationStructureModeKHR enumeration is defined as: 652 653include::{generated}/api/enums/VkBuildAccelerationStructureModeKHR.adoc[] 654 655 * ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR specifies that the 656 destination acceleration structure will be built using the specified 657 geometries. 658 * ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR specifies that the 659 destination acceleration structure will be built using data in a source 660 acceleration structure, updated by the specified geometries. 661-- 662 663[open,refpage='VkDeviceOrHostAddressKHR',desc='Union specifying a device or host address',type='structs'] 664-- 665:refpage: VkDeviceOrHostAddressKHR 666 667The sname:VkDeviceOrHostAddressKHR union is defined as: 668 669include::{generated}/api/structs/VkDeviceOrHostAddressKHR.adoc[] 670 671 * pname:deviceAddress is a buffer device address as returned by the 672 flink:vkGetBufferDeviceAddressKHR command. 673 * pname:hostAddress is a host memory address. 674 675include::{generated}/validity/structs/VkDeviceOrHostAddressKHR.adoc[] 676-- 677 678[open,refpage='VkDeviceOrHostAddressConstKHR',desc='Union specifying a const device or host address',type='structs'] 679-- 680:refpage: VkDeviceOrHostAddressConstKHR 681 682The sname:VkDeviceOrHostAddressConstKHR union is defined as: 683 684include::{generated}/api/structs/VkDeviceOrHostAddressConstKHR.adoc[] 685 686 * pname:deviceAddress is a buffer device address as returned by the 687 flink:vkGetBufferDeviceAddressKHR command. 688 * pname:hostAddress is a const host memory address. 689 690include::{generated}/validity/structs/VkDeviceOrHostAddressConstKHR.adoc[] 691-- 692 693[open,refpage='VkAccelerationStructureGeometryKHR',desc='Structure specifying geometries to be built into an acceleration structure',type='structs'] 694-- 695:refpage: VkAccelerationStructureGeometryKHR 696 697The sname:VkAccelerationStructureGeometryKHR structure is defined as: 698 699include::{generated}/api/structs/VkAccelerationStructureGeometryKHR.adoc[] 700 701 * pname:sType is a elink:VkStructureType value identifying this structure. 702 * pname:pNext is `NULL` or a pointer to a structure extending this 703 structure. 704 * pname:geometryType describes which type of geometry this 705 sname:VkAccelerationStructureGeometryKHR refers to. 706 * pname:geometry is a slink:VkAccelerationStructureGeometryDataKHR union 707 describing the geometry data for the relevant geometry type. 708 * pname:flags is a bitmask of elink:VkGeometryFlagBitsKHR values 709 describing additional properties of how the geometry should be built. 710 711include::{generated}/validity/structs/VkAccelerationStructureGeometryKHR.adoc[] 712-- 713 714[open,refpage='VkAccelerationStructureGeometryDataKHR',desc='Union specifying acceleration structure geometry data',type='structs'] 715-- 716:refpage: VkAccelerationStructureGeometryDataKHR 717 718The sname:VkAccelerationStructureGeometryDataKHR union is defined as: 719 720include::{generated}/api/structs/VkAccelerationStructureGeometryDataKHR.adoc[] 721 722 * pname:triangles is a 723 slink:VkAccelerationStructureGeometryTrianglesDataKHR structure. 724 * pname:aabbs is a slink:VkAccelerationStructureGeometryAabbsDataKHR 725 structure. 726 * pname:instances is a 727 slink:VkAccelerationStructureGeometryInstancesDataKHR structure. 728 729include::{generated}/validity/structs/VkAccelerationStructureGeometryDataKHR.adoc[] 730-- 731 732[open,refpage='VkAccelerationStructureGeometryTrianglesDataKHR',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] 733-- 734:refpage: VkAccelerationStructureGeometryTrianglesDataKHR 735 736The sname:VkAccelerationStructureGeometryTrianglesDataKHR structure is 737defined as: 738 739include::{generated}/api/structs/VkAccelerationStructureGeometryTrianglesDataKHR.adoc[] 740 741 * pname:sType is a elink:VkStructureType value identifying this structure. 742 * pname:pNext is `NULL` or a pointer to a structure extending this 743 structure. 744 * pname:vertexFormat is the elink:VkFormat of each vertex element. 745 * pname:vertexData is a device or host address to memory containing vertex 746 data for this geometry. 747 * pname:maxVertex is the highest index of a vertex that will be addressed 748 by a build command using this structure. 749 * pname:vertexStride is the stride in bytes between each vertex. 750 * pname:indexType is the elink:VkIndexType of each index element. 751 * pname:indexData is a device or host address to memory containing index 752 data for this geometry. 753 * pname:transformData is a device or host address to memory containing an 754 optional reference to a slink:VkTransformMatrixKHR structure describing 755 a transformation from the space in which the vertices in this geometry 756 are described to the space in which the acceleration structure is 757 defined. 758 759[NOTE] 760.Note 761==== 762Unlike the stride for vertex buffers in 763slink:VkVertexInputBindingDescription for graphics pipelines which must not 764exceed pname:maxVertexInputBindingStride, pname:vertexStride for 765acceleration structure geometry is instead restricted to being a 32-bit 766value. 767==== 768 769.Valid Usage 770**** 771 * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03735]] 772 pname:vertexStride must: be a multiple of the size in bytes of the 773 smallest component of pname:vertexFormat 774 * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexStride-03819]] 775 pname:vertexStride must: be less than or equal to [eq]#2^32^-1# 776 * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-vertexFormat-03797]] 777 The <<resources-buffer-view-format-features,format features>> of 778 pname:vertexFormat must: contain 779 ename:VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR 780 * [[VUID-VkAccelerationStructureGeometryTrianglesDataKHR-indexType-03798]] 781 pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, 782 ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_KHR 783**** 784 785include::{generated}/validity/structs/VkAccelerationStructureGeometryTrianglesDataKHR.adoc[] 786-- 787 788ifdef::VK_NV_ray_tracing_motion_blur[] 789[open,refpage='VkAccelerationStructureGeometryMotionTrianglesDataNV',desc='Structure specifying vertex motion in a bottom-level acceleration structure',type='structs'] 790-- 791:refpage: VkAccelerationStructureGeometryMotionTrianglesDataNV 792 793The sname:VkAccelerationStructureGeometryMotionTrianglesDataNV structure is 794defined as: 795 796include::{generated}/api/structs/VkAccelerationStructureGeometryMotionTrianglesDataNV.adoc[] 797 798 * pname:sType is a elink:VkStructureType value identifying this structure. 799 * pname:pNext is `NULL` or a pointer to a structure extending this 800 structure. 801 * pname:vertexData is a pointer to vertex data for this geometry at time 802 1.0 803 804If sname:VkAccelerationStructureGeometryMotionTrianglesDataNV is included in 805the pname:pNext chain of a 806slink:VkAccelerationStructureGeometryTrianglesDataKHR structure, the basic 807vertex positions are used for the position of the triangles in the geometry 808at time 0.0 and the pname:vertexData in 809sname:VkAccelerationStructureGeometryMotionTrianglesDataNV is used for the 810vertex positions at time 1.0, with positions linearly interpolated at 811intermediate times. 812 813Indexing for sname:VkAccelerationStructureGeometryMotionTrianglesDataNV 814pname:vertexData is equivalent to the basic vertex position data. 815 816include::{generated}/validity/structs/VkAccelerationStructureGeometryMotionTrianglesDataNV.adoc[] 817-- 818endif::VK_NV_ray_tracing_motion_blur[] 819 820ifdef::VK_EXT_opacity_micromap[] 821[open,refpage='VkAccelerationStructureTrianglesOpacityMicromapEXT',desc='Structure specifying an opacity micromap in a bottom-level acceleration structure',type='structs'] 822-- 823:refpage: VkAccelerationStructureTrianglesOpacityMicromapEXT 824 825The sname:VkAccelerationStructureTrianglesOpacityMicromapEXT structure is 826defined as: 827 828include::{generated}/api/structs/VkAccelerationStructureTrianglesOpacityMicromapEXT.adoc[] 829 830 * pname:sType is a elink:VkStructureType value identifying this structure. 831 * pname:pNext is `NULL` or a pointer to a structure extending this 832 structure. 833 * pname:indexType is the type of triangle indices used when indexing this 834 micromap 835 * pname:indexBuffer is the address containing the triangle indices 836 * pname:indexStride is the byte stride between triangle indices 837 * pname:baseTriangle is the base value added to the non-negative triangle 838 indices 839 * pname:usageCountsCount specifies the number of usage counts structures 840 that will be used to determine the size of this micromap. 841 * pname:pUsageCounts is a pointer to an array of slink:VkMicromapUsageEXT 842 structures. 843 * pname:ppUsageCounts is a pointer to an array of pointers to 844 slink:VkMicromapUsageEXT structures. 845 * pname:micromap is the handle to the micromap object to include in this 846 geometry 847 848If sname:VkAccelerationStructureTrianglesOpacityMicromapEXT is included in 849the pname:pNext chain of a 850slink:VkAccelerationStructureGeometryTrianglesDataKHR structure, that 851geometry will reference that micromap. 852 853For each triangle in the geometry, the acceleration structure build fetches 854an index from pname:indexBuffer using pname:indexType and pname:indexStride. 855If that value is the unsigned cast of one of the values from 856elink:VkOpacityMicromapSpecialIndexEXT then that triangle behaves as 857described for that special value in <<ray-opacity-micromap,Ray Opacity 858Micromap>>. 859Otherwise that triangle uses the opacity micromap information from 860pname:micromap at that index plus pname:baseTriangle. 861 862Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 863pointer, the other must: be `NULL`. 864The elements of the non-`NULL` array describe the total count used to build 865this geometry. 866For a given pname:format and pname:subdivisionLevel the number of triangles 867in this geometry matching those values after indirection and special index 868handling must: be equal to the sum of matching pname:count provided. 869 870If pname:micromap is dlink:VK_NULL_HANDLE, then every value read from 871pname:indexBuffer must: be one of the values in 872ename:VkOpacityMicromapSpecialIndexEXT. 873 874.Valid Usage 875**** 876 * [[VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-pUsageCounts-07335]] 877 Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 878 pointer, the other must: be `NULL` 879**** 880 881include::{generated}/validity/structs/VkAccelerationStructureTrianglesOpacityMicromapEXT.adoc[] 882-- 883 884[open,refpage='VkOpacityMicromapSpecialIndexEXT',desc='Enum for special indices in the opacity micromap',type='enums'] 885-- 886:refpage: VkOpacityMicromapSpecialIndexEXT 887 888The ename:VkOpacityMicromapSpecialIndexEXT enumeration is defined as: 889 890include::{generated}/api/enums/VkOpacityMicromapSpecialIndexEXT.adoc[] 891 892 * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_TRANSPARENT_EXT specifies 893 that the entire triangle is fully transparent. 894 * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_OPAQUE_EXT specifies that 895 the entire triangle is fully opaque. 896 * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_TRANSPARENT_EXT 897 specifies that the entire triangle is unknown-transparent. 898 * ename:VK_OPACITY_MICROMAP_SPECIAL_INDEX_FULLY_UNKNOWN_OPAQUE_EXT 899 specifies that the entire triangle is unknown-opaque. 900-- 901 902endif::VK_EXT_opacity_micromap[] 903 904ifdef::VK_NV_displacement_micromap[] 905[open,refpage='VkAccelerationStructureTrianglesDisplacementMicromapNV',desc='Structure specifying a displacement micromap in a bottom-level acceleration structure',type='structs'] 906-- 907:refpage: VkAccelerationStructureTrianglesDisplacementMicromapNV 908 909The sname:VkAccelerationStructureTrianglesDisplacementMicromapNV structure 910is defined as: 911 912include::{generated}/api/structs/VkAccelerationStructureTrianglesDisplacementMicromapNV.adoc[] 913 914 * pname:sType is a elink:VkStructureType value identifying this structure. 915 * pname:pNext is `NULL` or a pointer to a structure extending this 916 structure. 917 * pname:displacementBiasAndScaleFormat is the format of displacement bias 918 and scale used in this displacement micromap reference. 919 * pname:displacementVectorFormat is the format of displacement vector used 920 in this displacement micromap reference. 921 * pname:displacementBiasAndScaleBuffer is the address containing the bias 922 and scale. 923 * pname:displacementBiasAndScaleStride is the byte stride between bias and 924 scale values. 925 * pname:displacementVectorBuffer is the address containing the 926 displacement vector values. 927 * pname:displacementVectorStride is the byte stride between displacement 928 vector values. 929 * pname:displacedMicromapPrimitiveFlags is the address containing the 930 primitive flags. 931 * pname:displacedMicromapPrimitiveFlagsStride is the byte stride between 932 primitive flag values. 933 * pname:indexType is the type of triangle indices used when indexing this 934 micromap. 935 * pname:indexBuffer is the address containing the triangle indices. 936 * pname:indexStride is the byte stride between triangle indices. 937 * pname:baseTriangle is the base value added to the non-negative triangle 938 indices. 939 * pname:usageCountsCount specifies the number of usage counts structures 940 that will be used to determine the size of this micromap. 941 * pname:pUsageCounts is a pointer to an array of slink:VkMicromapUsageEXT 942 structures. 943 * pname:ppUsageCounts is a pointer to an array of pointers to 944 slink:VkMicromapUsageEXT structures. 945 * pname:micromap is the handle to the micromap object to include in this 946 geometry. 947 948If sname:VkAccelerationStructureTrianglesDisplacementMicromapNV is included 949in the pname:pNext chain of a 950slink:VkAccelerationStructureGeometryTrianglesDataKHR structure, that 951geometry will reference that micromap. 952 953For each triangle in the geometry, the acceleration structure build fetches 954an index from pname:indexBuffer using pname:indexType and pname:indexStride. 955That triangle uses the displacement micromap information from pname:micromap 956at that index plus pname:baseTriangle. 957 958Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 959pointer, the other must: be `NULL`. 960The elements of the non-`NULL` array describe the total count used to build 961this geometry. 962For a given pname:format and pname:subdivisionLevel the number of triangles 963in this geometry matching those values after indirection must: be equal to 964the sum of matching pname:count provided. 965 966.Valid Usage 967**** 968 * [[VUID-VkAccelerationStructureTrianglesDisplacementMicromapNV-pUsageCounts-07992]] 969 Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 970 pointer, the other must: be `NULL` 971**** 972 973include::{generated}/validity/structs/VkAccelerationStructureTrianglesDisplacementMicromapNV.adoc[] 974-- 975endif::VK_NV_displacement_micromap[] 976endif::VK_KHR_acceleration_structure[] 977 978[open,refpage='VkTransformMatrixKHR',desc='Structure specifying a 3x4 affine transformation matrix',type='structs',alias='VkTransformMatrixNV'] 979-- 980:refpage: VkTransformMatrixKHR 981 982The sname:VkTransformMatrixKHR structure is defined as: 983 984include::{generated}/api/structs/VkTransformMatrixKHR.adoc[] 985 986ifdef::VK_NV_ray_tracing[] 987or the equivalent 988 989include::{generated}/api/structs/VkTransformMatrixNV.adoc[] 990endif::VK_NV_ray_tracing[] 991 992 * pname:matrix is a 3x4 row-major affine transformation matrix. 993 994include::{generated}/validity/structs/VkTransformMatrixKHR.adoc[] 995 996.Valid Usage 997**** 998 * [[VUID-VkTransformMatrixKHR-matrix-03799]] 999 The first three columns of pname:matrix must: define an invertible 3x3 1000 matrix 1001**** 1002-- 1003 1004ifdef::VK_KHR_acceleration_structure[] 1005[open,refpage='VkAccelerationStructureGeometryAabbsDataKHR',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] 1006-- 1007:refpage: VkAccelerationStructureGeometryAabbsDataKHR 1008 1009The sname:VkAccelerationStructureGeometryAabbsDataKHR structure is defined 1010as: 1011 1012include::{generated}/api/structs/VkAccelerationStructureGeometryAabbsDataKHR.adoc[] 1013 1014 * pname:sType is a elink:VkStructureType value identifying this structure. 1015 * pname:pNext is `NULL` or a pointer to a structure extending this 1016 structure. 1017 * pname:data is a device or host address to memory containing 1018 slink:VkAabbPositionsKHR structures containing position data for each 1019 axis-aligned bounding box in the geometry. 1020 * pname:stride is the stride in bytes between each entry in pname:data. 1021 The stride must: be a multiple of `8`. 1022 1023.Valid Usage 1024**** 1025 * [[VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03545]] 1026 pname:stride must: be a multiple of `8` 1027 * [[VUID-VkAccelerationStructureGeometryAabbsDataKHR-stride-03820]] 1028 pname:stride must: be less than or equal to [eq]#2^32^-1# 1029**** 1030 1031include::{generated}/validity/structs/VkAccelerationStructureGeometryAabbsDataKHR.adoc[] 1032-- 1033endif::VK_KHR_acceleration_structure[] 1034 1035[open,refpage='VkAabbPositionsKHR',desc='Structure specifying two opposing corners of an axis-aligned bounding box',type='structs',alias='VkAabbPositionsNV'] 1036-- 1037:refpage: VkAabbPositionsKHR 1038 1039The sname:VkAabbPositionsKHR structure is defined as: 1040 1041include::{generated}/api/structs/VkAabbPositionsKHR.adoc[] 1042 1043ifdef::VK_NV_ray_tracing[] 1044or the equivalent 1045 1046include::{generated}/api/structs/VkAabbPositionsNV.adoc[] 1047endif::VK_NV_ray_tracing[] 1048 1049 * pname:minX is the x position of one opposing corner of a bounding box. 1050 * pname:minY is the y position of one opposing corner of a bounding box. 1051 * pname:minZ is the z position of one opposing corner of a bounding box. 1052 * pname:maxX is the x position of the other opposing corner of a bounding 1053 box. 1054 * pname:maxY is the y position of the other opposing corner of a bounding 1055 box. 1056 * pname:maxZ is the z position of the other opposing corner of a bounding 1057 box. 1058 1059.Valid Usage 1060**** 1061 * [[VUID-VkAabbPositionsKHR-minX-03546]] 1062 pname:minX must: be less than or equal to pname:maxX 1063 * [[VUID-VkAabbPositionsKHR-minY-03547]] 1064 pname:minY must: be less than or equal to pname:maxY 1065 * [[VUID-VkAabbPositionsKHR-minZ-03548]] 1066 pname:minZ must: be less than or equal to pname:maxZ 1067**** 1068 1069include::{generated}/validity/structs/VkAabbPositionsKHR.adoc[] 1070-- 1071 1072ifdef::VK_KHR_acceleration_structure[] 1073[open,refpage='VkAccelerationStructureGeometryInstancesDataKHR',desc='Structure specifying a geometry consisting of instances of other acceleration structures',type='structs'] 1074-- 1075:refpage: VkAccelerationStructureGeometryInstancesDataKHR 1076 1077The sname:VkAccelerationStructureGeometryInstancesDataKHR structure is 1078defined as: 1079 1080include::{generated}/api/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] 1081 1082 * pname:sType is a elink:VkStructureType value identifying this structure. 1083 * pname:pNext is `NULL` or a pointer to a structure extending this 1084 structure. 1085 * pname:arrayOfPointers specifies whether pname:data is used as an array 1086 of addresses or just an array. 1087 * pname:data is either the address of an array of device or host addresses 1088 referencing individual slink:VkAccelerationStructureInstanceKHR 1089 structures 1090ifdef::VK_NV_ray_tracing_motion_blur[] 1091 or packed motion instance information as described in 1092 <<acceleration-structure-motion-instances, motion instances>> 1093endif::VK_NV_ray_tracing_motion_blur[] 1094 if pname:arrayOfPointers is ename:VK_TRUE, or the address of an array of 1095 slink:VkAccelerationStructureInstanceKHR 1096ifdef::VK_NV_ray_tracing_motion_blur[] 1097 or slink:VkAccelerationStructureMotionInstanceNV 1098endif::VK_NV_ray_tracing_motion_blur[] 1099 structures. 1100 Addresses and slink:VkAccelerationStructureInstanceKHR structures are 1101 tightly packed. 1102ifdef::VK_NV_ray_tracing_motion_blur[] 1103 slink:VkAccelerationStructureMotionInstanceNV structures have a stride 1104 of 160 bytes. 1105endif::VK_NV_ray_tracing_motion_blur[] 1106 1107include::{generated}/validity/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] 1108-- 1109endif::VK_KHR_acceleration_structure[] 1110 1111[open,refpage='VkAccelerationStructureInstanceKHR',desc='Structure specifying a single acceleration structure instance for building into an acceleration structure geometry',type='structs',alias='VkAccelerationStructureInstanceNV'] 1112-- 1113:refpage: VkAccelerationStructureInstanceKHR 1114 1115_Acceleration structure instances_ can: be built into top-level acceleration 1116structures. 1117Each acceleration structure instance is a separate entry in the top-level 1118acceleration structure which includes all the geometry of a bottom-level 1119acceleration structure at a transformed location. 1120Multiple instances can: point to the same bottom level acceleration 1121structure. 1122 1123An acceleration structure instance is defined by the structure: 1124 1125include::{generated}/api/structs/VkAccelerationStructureInstanceKHR.adoc[] 1126 1127ifdef::VK_NV_ray_tracing[] 1128or the equivalent 1129 1130include::{generated}/api/structs/VkAccelerationStructureInstanceNV.adoc[] 1131endif::VK_NV_ray_tracing[] 1132 1133 * pname:transform is a slink:VkTransformMatrixKHR structure describing a 1134 transformation to be applied to the acceleration structure. 1135 * pname:instanceCustomIndex is a 24-bit user-specified index value 1136 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1137 * pname:mask is an 8-bit visibility mask for the geometry. 1138 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1139 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1140 calculating the hit shader binding table index. 1141 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1142 values to apply to this instance. 1143 * pname:accelerationStructureReference is either: 1144 ** a device address containing the value obtained from 1145ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1146ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1147ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1148 (used by device operations which reference acceleration structures) or, 1149 ** a slink:VkAccelerationStructureKHR object (used by host operations 1150 which reference acceleration structures). 1151 1152The C language specification does not define the ordering of bit-fields, but 1153in practice, this struct produces the correct layout with existing 1154compilers. 1155The intended bit pattern is for the following: 1156 1157 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1158 single code:uint32_t was specified in their place 1159 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1160 that memory 1161 ** pname:mask occupies the 8 most significant bits of that memory 1162 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1163 same memory as if a single code:uint32_t was specified in their place 1164 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1165 significant bits of that memory 1166 ** pname:flags occupies the 8 most significant bits of that memory 1167 1168If a compiler produces code that diverges from that pattern, applications 1169must: employ another method to set values according to the correct bit 1170pattern. 1171 1172include::{generated}/validity/structs/VkAccelerationStructureInstanceKHR.adoc[] 1173-- 1174 1175[open,refpage='VkGeometryInstanceFlagBitsKHR',desc='Instance flag bits',type='enums',alias='VkGeometryInstanceFlagBitsNV'] 1176-- 1177:refpage: VkGeometryInstanceFlagBitsKHR 1178 1179Possible values of pname:flags in the instance modifying the behavior of 1180that instance are: 1181 1182include::{generated}/api/enums/VkGeometryInstanceFlagBitsKHR.adoc[] 1183 1184ifdef::VK_NV_ray_tracing[] 1185or the equivalent 1186 1187include::{generated}/api/enums/VkGeometryInstanceFlagBitsNV.adoc[] 1188endif::VK_NV_ray_tracing[] 1189 1190 * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR disables 1191 face culling for this instance. 1192 * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR indicates that 1193 the <<ray-traversal-culling-face, facing determination>> for geometry in 1194 this instance is inverted. 1195 Because the facing is determined in object space, an instance transform 1196 does not change the winding, but a geometry transform does. 1197 * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR causes this instance to 1198 act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were specified on all 1199 geometries referenced by this instance. 1200 This behavior can: be overridden by the SPIR-V code:NoOpaqueKHR ray 1201 flag. 1202 * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR causes this instance 1203 to act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were not specified on 1204 all geometries referenced by this instance. 1205 This behavior can: be overridden by the SPIR-V code:OpaqueKHR ray flag. 1206 1207ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and 1208ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must: not be used in the 1209same flag. 1210-- 1211 1212[open,refpage='VkGeometryInstanceFlagsKHR',desc='Bitmask of VkGeometryInstanceFlagBitsKHR',type='flags',alias='VkGeometryInstanceFlagsNV'] 1213-- 1214:refpage: VkGeometryInstanceFlagsKHR 1215 1216include::{generated}/api/flags/VkGeometryInstanceFlagsKHR.adoc[] 1217 1218ifdef::VK_NV_ray_tracing[] 1219or the equivalent 1220 1221include::{generated}/api/flags/VkGeometryInstanceFlagsNV.adoc[] 1222endif::VK_NV_ray_tracing[] 1223 1224tname:VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of 1225zero or more elink:VkGeometryInstanceFlagBitsKHR. 1226-- 1227 1228ifdef::VK_NV_ray_tracing_motion_blur[] 1229[open,refpage='VkAccelerationStructureMotionInstanceNV',desc='Structure specifying a single acceleration structure motion instance for building into an acceleration structure geometry',type='structs'] 1230-- 1231:refpage: VkAccelerationStructureMotionInstanceNV 1232 1233_Acceleration structure motion instances_ can: be built into top-level 1234acceleration structures. 1235Each acceleration structure instance is a separate entry in the top-level 1236acceleration structure which includes all the geometry of a bottom-level 1237acceleration structure at a transformed location including a type of motion 1238and parameters to determine the motion of the instance over time. 1239 1240An acceleration structure motion instance is defined by the structure: 1241 1242include::{generated}/api/structs/VkAccelerationStructureMotionInstanceNV.adoc[] 1243 1244 * pname:type is a elink:VkAccelerationStructureMotionInstanceTypeNV 1245 enumerant identifying which type of motion instance this is and which 1246 type of the union is valid. 1247 * pname:flags is currently unused, but is required to keep natural 1248 alignment of pname:data. 1249 * pname:data is a slink:VkAccelerationStructureMotionInstanceDataNV 1250 containing motion instance data for this instance. 1251 1252[NOTE] 1253.Note 1254==== 1255If writing this other than with a standard C compiler, note that the final 1256structure should be 152 bytes in size. 1257==== 1258 1259include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceNV.adoc[] 1260-- 1261 1262[open,refpage='VkAccelerationStructureMotionInstanceDataNV',desc='Union specifying a acceleration structure motion instance data for building into an acceleration structure geometry',type='structs'] 1263-- 1264:refpage: VkAccelerationStructureMotionInstanceDataNV 1265 1266Acceleration structure motion instance is defined by the union: 1267 1268include::{generated}/api/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] 1269 1270 * pname:staticInstance is a slink:VkAccelerationStructureInstanceKHR 1271 structure containing data for a static instance. 1272 * pname:matrixMotionInstance is a 1273 slink:VkAccelerationStructureMatrixMotionInstanceNV structure containing 1274 data for a matrix motion instance. 1275 * pname:srtMotionInstance is a 1276 slink:VkAccelerationStructureSRTMotionInstanceNV structure containing 1277 data for an SRT motion instance. 1278 1279include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] 1280-- 1281 1282[open,refpage='VkAccelerationStructureMotionInstanceFlagsNV',desc='Reserved for future use',type='flags'] 1283-- 1284include::{generated}/api/flags/VkAccelerationStructureMotionInstanceFlagsNV.adoc[] 1285 1286tname:VkAccelerationStructureMotionInstanceFlagsNV is a bitmask type for 1287setting a mask, but is currently reserved for future use. 1288-- 1289 1290[open,refpage='VkAccelerationStructureMotionInstanceTypeNV',desc='Enum specifying a type of acceleration structure motion instance data for building into an acceleration structure geometry',type='enums'] 1291-- 1292:refpage: VkAccelerationStructureMotionInstanceTypeNV 1293 1294The ename:VkAccelerationStructureMotionInstanceTypeNV enumeration is defined 1295as: 1296 1297include::{generated}/api/enums/VkAccelerationStructureMotionInstanceTypeNV.adoc[] 1298 1299 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NV specifies 1300 that the instance is a static instance with no instance motion. 1301 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NV 1302 specifies that the instance is a motion instance with motion specified 1303 by interpolation between two matrices. 1304 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NV 1305 specifies that the instance is a motion instance with motion specified 1306 by interpolation in the SRT decomposition. 1307-- 1308 1309[open,refpage='VkAccelerationStructureMatrixMotionInstanceNV',desc='Structure specifying a single acceleration structure matrix motion instance for building into an acceleration structure geometry',type='structs'] 1310-- 1311:refpage: VkAccelerationStructureMatrixMotionInstanceNV 1312 1313An acceleration structure matrix motion instance is defined by the 1314structure: 1315 1316include::{generated}/api/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] 1317 1318 * pname:transformT0 is a slink:VkTransformMatrixKHR structure describing a 1319 transformation to be applied to the acceleration structure at time 0. 1320 * pname:transformT1 is a slink:VkTransformMatrixKHR structure describing a 1321 transformation to be applied to the acceleration structure at time 1. 1322 * pname:instanceCustomIndex is a 24-bit user-specified index value 1323 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1324 * pname:mask is an 8-bit visibility mask for the geometry. 1325 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1326 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1327 calculating the hit shader binding table index. 1328 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1329 values to apply to this instance. 1330 * pname:accelerationStructureReference is either: 1331 ** a device address containing the value obtained from 1332ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1333ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1334ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1335 (used by device operations which reference acceleration structures) or, 1336 ** a slink:VkAccelerationStructureKHR object (used by host operations 1337 which reference acceleration structures). 1338 1339The C language specification does not define the ordering of bit-fields, but 1340in practice, this struct produces the correct layout with existing 1341compilers. 1342The intended bit pattern is for the following: 1343 1344 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1345 single code:uint32_t was specified in their place 1346 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1347 that memory 1348 ** pname:mask occupies the 8 most significant bits of that memory 1349 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1350 same memory as if a single code:uint32_t was specified in their place 1351 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1352 significant bits of that memory 1353 ** pname:flags occupies the 8 most significant bits of that memory 1354 1355If a compiler produces code that diverges from that pattern, applications 1356must: employ another method to set values according to the correct bit 1357pattern. 1358 1359The transform for a matrix motion instance at a point in time is derived by 1360component-wise linear interpolation of the two transforms. 1361That is, for a code:time in [0,1] the resulting transform is 1362 1363 {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} 1364 pname:transformT1 {times} code:time# 1365 1366include::{generated}/validity/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] 1367-- 1368 1369[open,refpage='VkAccelerationStructureSRTMotionInstanceNV',desc='Structure specifying a single acceleration structure SRT motion instance for building into an acceleration structure geometry',type='structs'] 1370-- 1371:refpage: VkAccelerationStructureSRTMotionInstanceNV 1372 1373An acceleration structure SRT motion instance is defined by the structure: 1374 1375include::{generated}/api/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] 1376 1377 * pname:transformT0 is a slink:VkSRTDataNV structure describing a 1378 transformation to be applied to the acceleration structure at time 0. 1379 * pname:transformT1 is a slink:VkSRTDataNV structure describing a 1380 transformation to be applied to the acceleration structure at time 1. 1381 * pname:instanceCustomIndex is a 24-bit user-specified index value 1382 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1383 * pname:mask is an 8-bit visibility mask for the geometry. 1384 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1385 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1386 calculating the hit shader binding table index. 1387 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1388 values to apply to this instance. 1389 * pname:accelerationStructureReference is either: 1390 ** a device address containing the value obtained from 1391ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1392ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1393ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1394 (used by device operations which reference acceleration structures) or, 1395 ** a slink:VkAccelerationStructureKHR object (used by host operations 1396 which reference acceleration structures). 1397 1398The C language specification does not define the ordering of bit-fields, but 1399in practice, this struct produces the correct layout with existing 1400compilers. 1401The intended bit pattern is for the following: 1402 1403 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1404 single code:uint32_t was specified in their place 1405 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1406 that memory 1407 ** pname:mask occupies the 8 most significant bits of that memory 1408 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1409 same memory as if a single code:uint32_t was specified in their place 1410 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1411 significant bits of that memory 1412 ** pname:flags occupies the 8 most significant bits of that memory 1413 1414If a compiler produces code that diverges from that pattern, applications 1415must: employ another method to set values according to the correct bit 1416pattern. 1417 1418The transform for a SRT motion instance at a point in time is derived from 1419component-wise linear interpolation of the two SRT transforms. 1420That is, for a code:time in [0,1] the resulting transform is 1421 1422 {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} 1423 pname:transformT1 {times} code:time# 1424 1425include::{generated}/validity/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] 1426-- 1427 1428[open,refpage='VkSRTDataNV',desc='Structure specifying a transform in SRT decomposition',type='structs'] 1429-- 1430:refpage: VkSRTDataNV 1431 1432An acceleration structure SRT transform is defined by the structure: 1433 1434include::{generated}/api/structs/VkSRTDataNV.adoc[] 1435 1436 * pname:sx is the x component of the scale of the transform 1437 * pname:a is one component of the shear for the transform 1438 * pname:b is one component of the shear for the transform 1439 * pname:pvx is the x component of the pivot point of the transform 1440 * pname:sy is the y component of the scale of the transform 1441 * pname:c is one component of the shear for the transform 1442 * pname:pvy is the y component of the pivot point of the transform 1443 * pname:sz is the z component of the scale of the transform 1444 * pname:pvz is the z component of the pivot point of the transform 1445 * pname:qx is the x component of the rotation quaternion 1446 * pname:qy is the y component of the rotation quaternion 1447 * pname:qz is the z component of the rotation quaternion 1448 * pname:qw is the w component of the rotation quaternion 1449 * pname:tx is the x component of the post-rotation translation 1450 * pname:ty is the y component of the post-rotation translation 1451 * pname:tz is the z component of the post-rotation translation 1452 1453This transform decomposition consists of three elements. 1454The first is a matrix S, consisting of a scale, shear, and translation, 1455usually used to define the pivot point of the following rotation. 1456This matrix is constructed from the parameters above by: 1457 1458[latexmath] 1459++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1460S = 1461\left( 1462 \begin{matrix} 1463 sx & a & b & pvx \\ 1464 0 & sy & c & pvy \\ 1465 0 & 0 & sz & pvz 1466 \end{matrix} 1467\right) 1468++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1469 1470The rotation quaternion is defined as: 1471 1472 {empty}:: [eq]#code:R = [ pname:qx, pname:qy, pname:qz, pname:qw ]# 1473 1474This is a rotation around a conceptual normalized axis [eq]#[ ax, ay, az ]# 1475of amount code:theta such that: 1476 1477 {empty}:: [eq]#[ pname:qx, pname:qy, pname:qz ] = sin(code:theta/2) 1478 {times} [ code:ax, code:ay, code:az ]# 1479 1480and 1481 1482 {empty}:: [eq]#pname:qw = cos(code:theta/2)# 1483 1484Finally, the transform has a translation T constructed from the parameters 1485above by: 1486 1487[latexmath] 1488++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1489T = 1490\left( 1491 \begin{matrix} 1492 1 & 0 & 0 & tx \\ 1493 0 & 1 & 0 & ty \\ 1494 0 & 0 & 1 & tz 1495 \end{matrix} 1496\right) 1497++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1498 1499The effective derived transform is then given by 1500 1501 {empty}:: [eq]#code:T {times} code:R {times} code:S# 1502 1503include::{generated}/validity/structs/VkSRTDataNV.adoc[] 1504-- 1505endif::VK_NV_ray_tracing_motion_blur[] 1506 1507ifdef::VK_KHR_acceleration_structure[] 1508[open,refpage='VkAccelerationStructureBuildRangeInfoKHR',desc='Structure specifying build offsets and counts for acceleration structure builds',type='structs'] 1509-- 1510:refpage: VkAccelerationStructureBuildOffsetInfoKHR 1511 1512sname:VkAccelerationStructureBuildRangeInfoKHR is defined as: 1513 1514include::{generated}/api/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] 1515 1516 * pname:primitiveCount defines the number of primitives for a 1517 corresponding acceleration structure geometry. 1518 * pname:primitiveOffset defines an offset in bytes into the memory where 1519 primitive data is defined. 1520 * pname:firstVertex is the index of the first vertex to build from for 1521 triangle geometry. 1522 * pname:transformOffset defines an offset in bytes into the memory where a 1523 transform matrix is defined. 1524 1525The primitive count and primitive offset are interpreted differently 1526depending on the elink:VkGeometryTypeKHR used: 1527 1528 * For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, 1529 pname:primitiveCount is the number of triangles to be built, where each 1530 triangle is treated as 3 vertices. 1531 ** If the geometry uses indices, [eq]#pname:primitiveCount {times} 3# 1532 indices are consumed from 1533 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData, 1534 starting at an offset of pname:primitiveOffset. 1535 The value of pname:firstVertex is added to the index values before 1536 fetching vertices. 1537 ** If the geometry does not use indices, [eq]#pname:primitiveCount {times} 1538 3# vertices are consumed from 1539 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData, 1540 starting at an offset of [eq]#pname:primitiveOffset {plus} 1541 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexStride 1542 {times} pname:firstVertex#. 1543 ** If 1544 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 1545 is not `NULL`, a single slink:VkTransformMatrixKHR structure is 1546 consumed from 1547 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData, 1548 at an offset of pname:transformOffset. 1549 This matrix describes a transformation from the space in which the 1550 vertices for all triangles in this geometry are described to the space 1551 in which the acceleration structure is defined. 1552 * For geometries of type ename:VK_GEOMETRY_TYPE_AABBS_KHR, 1553 pname:primitiveCount is the number of axis-aligned bounding boxes. 1554 pname:primitiveCount slink:VkAabbPositionsKHR structures are consumed 1555 from slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data, 1556 starting at an offset of pname:primitiveOffset. 1557 * For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, 1558 pname:primitiveCount is the number of acceleration structures. 1559 pname:primitiveCount slink:VkAccelerationStructureInstanceKHR 1560ifdef::VK_NV_ray_tracing_motion_blur[] 1561 or slink:VkAccelerationStructureMotionInstanceNV 1562endif::VK_NV_ray_tracing_motion_blur[] 1563 structures are consumed from 1564 slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data, 1565 starting at an offset of pname:primitiveOffset. 1566 1567.Valid Usage 1568**** 1569 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03656]] 1570 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the 1571 geometry uses indices, the offset pname:primitiveOffset from 1572 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData 1573 must: be a multiple of the element size of 1574 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexType 1575 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03657]] 1576 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the 1577 geometry does not use indices, the offset pname:primitiveOffset from 1578 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData 1579 must: be a multiple of the component size of 1580 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexFormat 1581 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-transformOffset-03658]] 1582 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the offset 1583 pname:transformOffset from 1584 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 1585 must: be a multiple of 16 1586 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03659]] 1587 For geometries of type ename:VK_GEOMETRY_TYPE_AABBS_KHR, the offset 1588 pname:primitiveOffset from 1589 slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data must: be a 1590 multiple of 8 1591 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03660]] 1592 For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, the offset 1593 pname:primitiveOffset from 1594 slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data must: 1595 be a multiple of 16 1596**** 1597 1598include::{generated}/validity/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] 1599-- 1600endif::VK_KHR_acceleration_structure[] 1601 1602 1603[[acceleration-structure-copying]] 1604=== Copying Acceleration Structures 1605 1606An additional command exists for copying acceleration structures without 1607updating their contents. 1608The acceleration structure object can: be compacted in order to improve 1609performance. 1610Before copying, an application must: query the size of the resulting 1611acceleration structure. 1612 1613[open,refpage='vkCmdWriteAccelerationStructuresPropertiesKHR',desc='Write acceleration structure result parameters to query results.',type='protos'] 1614-- 1615:refpage: vkCmdWriteAccelerationStructuresPropertiesKHR 1616 1617To query acceleration structure size parameters call: 1618 1619ifdef::VK_KHR_acceleration_structure[] 1620include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] 1621endif::VK_KHR_acceleration_structure[] 1622 1623 * pname:commandBuffer is the command buffer into which the command will be 1624 recorded. 1625 * pname:accelerationStructureCount is the count of acceleration structures 1626 for which to query the property. 1627 * pname:pAccelerationStructures is a pointer to an array of existing 1628 previously built acceleration structures. 1629 * pname:queryType is a elink:VkQueryType value specifying the type of 1630 queries managed by the pool. 1631 * pname:queryPool is the query pool that will manage the results of the 1632 query. 1633 * pname:firstQuery is the first query index within the query pool that 1634 will contain the pname:accelerationStructureCount number of results. 1635 1636Accesses to any of the acceleration structures listed in 1637pname:pAccelerationStructures must: be <<synchronization-dependencies, 1638synchronized>> with the 1639ifdef::VK_KHR_synchronization2[] 1640ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1641<<synchronization-pipeline-stages, pipeline stage>> or the 1642endif::VK_KHR_synchronization2[] 1643ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1644<<synchronization-pipeline-stages, pipeline stage>>, and an 1645<<synchronization-access-types, access type>> of 1646ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1647 1648 * If pname:queryType is 1649 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the 1650 value written out is the number of bytes required by a compacted 1651 acceleration structure. 1652 * If pname:queryType is 1653 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 1654 the value written out is the number of bytes required by a serialized 1655 acceleration structure. 1656 1657.Valid Usage 1658**** 1659 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructure-08924]] 1660 The <<features-accelerationStructure, 1661 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1662 feature must: be enabled 1663 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493]] 1664 pname:queryPool must: have been created with a pname:queryType matching 1665 pname:queryType 1666 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494]] 1667 The queries identified by pname:queryPool and pname:firstQuery must: be 1668 _unavailable_ 1669 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-buffer-03736]] 1670 The pname:buffer used to create each acceleration structure in 1671 pname:pAccelerationStructures must: be bound to device memory 1672 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-query-04880]] 1673 The sum of pname:query plus pname:accelerationStructureCount must: be 1674 less than or equal to the number of queries in pname:queryPool 1675include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] 1676**** 1677 1678include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] 1679-- 1680 1681ifdef::VK_NV_ray_tracing[] 1682[open,refpage='vkCmdWriteAccelerationStructuresPropertiesNV',desc='Write acceleration structure result parameters to query results.',type='protos'] 1683-- 1684:refpage: vkCmdWriteAccelerationStructuresPropertiesNV 1685 1686To query acceleration structure size parameters call: 1687 1688include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] 1689 1690 * pname:commandBuffer is the command buffer into which the command will be 1691 recorded. 1692 * pname:accelerationStructureCount is the count of acceleration structures 1693 for which to query the property. 1694 * pname:pAccelerationStructures is a pointer to an array of existing 1695 previously built acceleration structures. 1696 * pname:queryType is a elink:VkQueryType value specifying the type of 1697 queries managed by the pool. 1698 * pname:queryPool is the query pool that will manage the results of the 1699 query. 1700 * pname:firstQuery is the first query index within the query pool that 1701 will contain the pname:accelerationStructureCount number of results. 1702 1703Accesses to any of the acceleration structures listed in 1704pname:pAccelerationStructures must: be <<synchronization-dependencies, 1705synchronized>> with the 1706ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1707<<synchronization-pipeline-stages, pipeline stage>> and an 1708<<synchronization-access-types, access type>> of 1709ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1710 1711.Valid Usage 1712**** 1713 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03755]] 1714 pname:queryPool must: have been created with a pname:queryType matching 1715 pname:queryType 1716 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03756]] 1717 The queries identified by pname:queryPool and pname:firstQuery must: be 1718 _unavailable_ 1719 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructure-03757]] 1720 pname:accelerationStructure must: be bound completely and contiguously 1721 to a single sname:VkDeviceMemory object via 1722 flink:vkBindAccelerationStructureMemoryNV 1723 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-04958]] 1724 All acceleration structures in pname:pAccelerationStructures must: have 1725 been built prior to the execution of this command 1726 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-06215]] 1727 All acceleration structures in pname:pAccelerationStructures must: have 1728 been built with 1729 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if 1730 pname:queryType is 1731 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV 1732 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-06216]] 1733 pname:queryType must: be 1734 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV 1735**** 1736 1737include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] 1738-- 1739 1740[open,refpage='vkCmdCopyAccelerationStructureNV',desc='Copy an acceleration structure',type='protos'] 1741-- 1742:refpage: vkCmdCopyAccelerationStructureNV 1743 1744To copy an acceleration structure call: 1745 1746include::{generated}/api/protos/vkCmdCopyAccelerationStructureNV.adoc[] 1747 1748 * pname:commandBuffer is the command buffer into which the command will be 1749 recorded. 1750 * pname:dst is the target acceleration structure for the copy. 1751 * pname:src is the source acceleration structure for the copy. 1752 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 1753 specifying additional operations to perform during the copy. 1754 1755Accesses to pname:src and pname:dst must: be <<synchronization-dependencies, 1756synchronized>> with the 1757ifdef::VK_KHR_synchronization2[] 1758ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1759<<synchronization-pipeline-stages, pipeline stage>> or the 1760endif::VK_KHR_synchronization2[] 1761ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1762<<synchronization-pipeline-stages, pipeline stage>>, and an 1763<<synchronization-access-types, access type>> of 1764ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 1765ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. 1766 1767.Valid Usage 1768**** 1769include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] 1770**** 1771 1772include::{generated}/validity/protos/vkCmdCopyAccelerationStructureNV.adoc[] 1773-- 1774endif::VK_NV_ray_tracing[] 1775 1776ifdef::VK_KHR_acceleration_structure[] 1777[open,refpage='vkCmdCopyAccelerationStructureKHR',desc='Copy an acceleration structure',type='protos'] 1778-- 1779:refpage: vkCmdCopyAccelerationStructureKHR 1780 1781To copy an acceleration structure call: 1782 1783include::{generated}/api/protos/vkCmdCopyAccelerationStructureKHR.adoc[] 1784 1785 * pname:commandBuffer is the command buffer into which the command will be 1786 recorded. 1787 * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR 1788 structure defining the copy operation. 1789 1790This command copies the pname:pInfo->src acceleration structure to the 1791pname:pInfo->dst acceleration structure in the manner specified by 1792pname:pInfo->mode. 1793 1794Accesses to pname:pInfo->src and pname:pInfo->dst must: be 1795<<synchronization-dependencies, synchronized>> with the 1796ifdef::VK_KHR_synchronization2[] 1797ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1798<<synchronization-pipeline-stages, pipeline stage>> or the 1799endif::VK_KHR_synchronization2[] 1800ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1801<<synchronization-pipeline-stages, pipeline stage>>, and an 1802<<synchronization-access-types, access type>> of 1803ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 1804ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. 1805 1806.Valid Usage 1807**** 1808 * [[VUID-vkCmdCopyAccelerationStructureKHR-accelerationStructure-08925]] 1809 The <<features-accelerationStructure, 1810 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1811 feature must: be enabled 1812 * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03737]] 1813 The pname:buffer used to create pname:pInfo->src must: be bound to 1814 device memory 1815 * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03738]] 1816 The pname:buffer used to create pname:pInfo->dst must: be bound to 1817 device memory 1818**** 1819 1820include::{generated}/validity/protos/vkCmdCopyAccelerationStructureKHR.adoc[] 1821-- 1822 1823[open,refpage='VkCopyAccelerationStructureInfoKHR',desc='Parameters for copying an acceleration structure',type='structs'] 1824-- 1825:refpage: VkCopyAccelerationStructureInfoKHR 1826 1827The sname:VkCopyAccelerationStructureInfoKHR structure is defined as: 1828 1829include::{generated}/api/structs/VkCopyAccelerationStructureInfoKHR.adoc[] 1830 1831 * pname:sType is a elink:VkStructureType value identifying this structure. 1832 * pname:pNext is `NULL` or a pointer to a structure extending this 1833 structure. 1834 * pname:src is the source acceleration structure for the copy. 1835 * pname:dst is the target acceleration structure for the copy. 1836 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 1837 specifying additional operations to perform during the copy. 1838 1839.Valid Usage 1840**** 1841include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] 1842**** 1843 1844include::{generated}/validity/structs/VkCopyAccelerationStructureInfoKHR.adoc[] 1845-- 1846endif::VK_KHR_acceleration_structure[] 1847 1848[open,refpage='VkCopyAccelerationStructureModeKHR',desc='Acceleration structure copy mode',type='enums',alias='VkCopyAccelerationStructureModeNV'] 1849-- 1850:refpage: VkCopyAccelerationStructureModeKHR 1851 1852Possible values of pname:mode specifying additional operations to perform 1853during the copy, are: 1854 1855include::{generated}/api/enums/VkCopyAccelerationStructureModeKHR.adoc[] 1856 1857ifdef::VK_NV_ray_tracing[] 1858or the equivalent 1859 1860include::{generated}/api/enums/VkCopyAccelerationStructureModeNV.adoc[] 1861endif::VK_NV_ray_tracing[] 1862 1863 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR creates a direct 1864 copy of the acceleration structure specified in pname:src into the one 1865 specified by pname:dst. 1866 The pname:dst acceleration structure must: have been created with the 1867 same parameters as pname:src. 1868 If pname:src contains references to other acceleration structures, 1869 pname:dst will reference the same acceleration structures. 1870 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR creates a more 1871 compact version of an acceleration structure pname:src into pname:dst. 1872 The acceleration structure pname:dst must: have been created with a size 1873 at least as large as that returned by 1874 flink:vkCmdWriteAccelerationStructuresPropertiesKHR 1875ifdef::VK_KHR_acceleration_structure[] 1876 or flink:vkWriteAccelerationStructuresPropertiesKHR 1877endif::VK_KHR_acceleration_structure[] 1878 after the build of the acceleration structure specified by pname:src. 1879 If pname:src contains references to other acceleration structures, 1880 pname:dst will reference the same acceleration structures. 1881 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR serializes the 1882 acceleration structure to a semi-opaque format which can be reloaded on 1883 a compatible implementation. 1884 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR deserializes 1885 the semi-opaque serialization format in the buffer to the acceleration 1886 structure. 1887-- 1888 1889[open,refpage='vkCmdCopyAccelerationStructureToMemoryKHR',desc='Copy an acceleration structure to device memory',type='protos'] 1890-- 1891:refpage: vkCmdCopyAccelerationStructureToMemoryKHR 1892 1893To copy an acceleration structure to device memory call: 1894 1895include::{generated}/api/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] 1896 1897 * pname:commandBuffer is the command buffer into which the command will be 1898 recorded. 1899 * pname:pInfo is an a pointer to a 1900 slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the 1901 copy operation. 1902 1903Accesses to pname:pInfo->src must: be <<synchronization-dependencies, 1904synchronized>> with the 1905ifdef::VK_KHR_synchronization2[] 1906ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1907<<synchronization-pipeline-stages, pipeline stage>> or the 1908endif::VK_KHR_synchronization2[] 1909ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1910<<synchronization-pipeline-stages, pipeline stage>>, and an 1911<<synchronization-access-types, access type>> of 1912ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1913Accesses to the buffer indicated by pname:pInfo->dst.deviceAddress must: be 1914synchronized with the 1915ifdef::VK_KHR_synchronization2[] 1916ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1917<<synchronization-pipeline-stages, pipeline stage>> or the 1918endif::VK_KHR_synchronization2[] 1919ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1920<<synchronization-pipeline-stages, pipeline stage>>, and an and an access 1921type of ename:VK_ACCESS_TRANSFER_WRITE_BIT. 1922 1923This command produces the same results as 1924flink:vkCopyAccelerationStructureToMemoryKHR, but writes its result to a 1925device address, and is executed on the device rather than the host. 1926The output may: not necessarily be bit-for-bit identical, but it can be 1927equally used by either flink:vkCmdCopyMemoryToAccelerationStructureKHR or 1928flink:vkCopyMemoryToAccelerationStructureKHR. 1929 1930[[serialized-as-header]] 1931The defined header structure for the serialized data consists of: 1932 1933 * ename:VK_UUID_SIZE bytes of data matching 1934 sname:VkPhysicalDeviceIDProperties::pname:driverUUID 1935 * ename:VK_UUID_SIZE bytes of data identifying the compatibility for 1936 comparison using flink:vkGetDeviceAccelerationStructureCompatibilityKHR 1937 * A 64-bit integer of the total size matching the value queried using 1938 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 1939 * A 64-bit integer of the deserialized size to be passed in to 1940 sname:VkAccelerationStructureCreateInfoKHR::pname:size 1941 * A 64-bit integer of the count of the number of acceleration structure 1942 handles following. 1943ifdef::VK_KHR_ray_tracing_maintenance1[] 1944 This value matches the value queried using 1945 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. 1946endif::VK_KHR_ray_tracing_maintenance1[] 1947 This will be zero for a bottom-level acceleration structure. 1948 For top-level acceleration structures this number is 1949 implementation-dependent; the number of and ordering of the handles may 1950 not match the instance descriptions which were used to build the 1951 acceleration structure. 1952 1953The corresponding handles matching the values returned by 1954ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1955ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1956ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1957are tightly packed in the buffer following the count. 1958The application is expected to store a mapping between those handles and the 1959original application-generated bottom-level acceleration structures to 1960provide when deserializing. 1961The serialized data is written to the buffer (or read from the buffer) 1962according to the host endianness. 1963 1964.Valid Usage 1965**** 1966 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-accelerationStructure-08926]] 1967 The <<features-accelerationStructure, 1968 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1969 feature must: be enabled 1970 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739]] 1971 pname:pInfo->dst.deviceAddress must: be a valid device address for a 1972 buffer bound to device memory 1973 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03740]] 1974 pname:pInfo->dst.deviceAddress must: be aligned to `256` bytes 1975 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03741]] 1976 If the buffer pointed to by pname:pInfo->dst.deviceAddress is non-sparse 1977 then it must: be bound completely and contiguously to a single 1978 slink:VkDeviceMemory object 1979 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559]] 1980 The pname:buffer used to create pname:pInfo->src must: be bound to 1981 device memory 1982**** 1983 1984include::{generated}/validity/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] 1985-- 1986 1987[open,refpage='VkCopyAccelerationStructureToMemoryInfoKHR',desc='Parameters for serializing an acceleration structure',type='structs'] 1988-- 1989:refpage: VkCopyAccelerationStructureToMemoryInfoKHR 1990 1991include::{generated}/api/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] 1992 1993 * pname:sType is a elink:VkStructureType value identifying this structure. 1994 * pname:pNext is `NULL` or a pointer to a structure extending this 1995 structure. 1996 * pname:src is the source acceleration structure for the copy 1997 * pname:dst is the device or host address to memory which is the target 1998 for the copy 1999 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 2000 specifying additional operations to perform during the copy. 2001 2002.Valid Usage 2003**** 2004 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-src-04959]] 2005 The source acceleration structure pname:src must: have been constructed 2006 prior to the execution of this command 2007 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-03561]] 2008 The memory pointed to by pname:dst must: be at least as large as the 2009 serialization size of pname:src, as reported by 2010 flink:vkWriteAccelerationStructuresPropertiesKHR or 2011 flink:vkCmdWriteAccelerationStructuresPropertiesKHR with a query type of 2012 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 2013 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-03412]] 2014 pname:mode must: be 2015 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR 2016**** 2017 2018include::{generated}/validity/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] 2019-- 2020 2021[open,refpage='vkCmdCopyMemoryToAccelerationStructureKHR',desc='Copy device memory to an acceleration structure',type='protos'] 2022-- 2023:refpage: vkCmdCopyMemoryToAccelerationStructureKHR 2024 2025To copy device memory to an acceleration structure call: 2026 2027include::{generated}/api/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] 2028 2029 * pname:commandBuffer is the command buffer into which the command will be 2030 recorded. 2031 * pname:pInfo is a pointer to a 2032 slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the 2033 copy operation. 2034 2035Accesses to pname:pInfo->dst must: be <<synchronization-dependencies, 2036synchronized>> with the 2037ifdef::VK_KHR_synchronization2[] 2038ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 2039<<synchronization-pipeline-stages, pipeline stage>> or the 2040endif::VK_KHR_synchronization2[] 2041ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 2042<<synchronization-pipeline-stages, pipeline stage>>, and an 2043<<synchronization-access-types, access type>> of 2044ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. 2045Accesses to the buffer indicated by pname:pInfo->src.deviceAddress must: be 2046synchronized with the 2047ifdef::VK_KHR_synchronization2[] 2048ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 2049<<synchronization-pipeline-stages, pipeline stage>> or the 2050endif::VK_KHR_synchronization2[] 2051ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 2052<<synchronization-pipeline-stages, pipeline stage>>, and an access type of 2053ename:VK_ACCESS_TRANSFER_READ_BIT. 2054 2055This command can accept acceleration structures produced by either 2056flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2057flink:vkCopyAccelerationStructureToMemoryKHR. 2058 2059The structure provided as input to deserialize is as described in 2060flink:vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration 2061structure handles filled in with the newly-queried handles to bottom level 2062acceleration structures created before deserialization. 2063These do not need to be built at deserialize time, but must: be created. 2064 2065.Valid Usage 2066**** 2067 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-accelerationStructure-08927]] 2068 The <<features-accelerationStructure, 2069 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 2070 feature must: be enabled 2071 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03742]] 2072 pname:pInfo->src.deviceAddress must: be a valid device address for a 2073 buffer bound to device memory 2074 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03743]] 2075 pname:pInfo->src.deviceAddress must: be aligned to `256` bytes 2076 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03744]] 2077 If the buffer pointed to by pname:pInfo->src.deviceAddress is non-sparse 2078 then it must: be bound completely and contiguously to a single 2079 slink:VkDeviceMemory object 2080 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-buffer-03745]] 2081 The pname:buffer used to create pname:pInfo->dst must: be bound to 2082 device memory 2083**** 2084 2085include::{generated}/validity/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] 2086-- 2087 2088[open,refpage='VkCopyMemoryToAccelerationStructureInfoKHR',desc='Parameters for deserializing an acceleration structure',type='structs'] 2089-- 2090:refpage: VkCopyMemoryToAccelerationStructureInfoKHR 2091 2092The sname:VkCopyMemoryToAccelerationStructureInfoKHR structure is defined 2093as: 2094 2095include::{generated}/api/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] 2096 2097 * pname:sType is a elink:VkStructureType value identifying this structure. 2098 * pname:pNext is `NULL` or a pointer to a structure extending this 2099 structure. 2100 * pname:src is the device or host address to memory containing the source 2101 data for the copy. 2102 * pname:dst is the target acceleration structure for the copy. 2103 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 2104 specifying additional operations to perform during the copy. 2105 2106.Valid Usage 2107**** 2108 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-src-04960]] 2109 The source memory pointed to by pname:src must: contain data previously 2110 serialized using flink:vkCmdCopyAccelerationStructureToMemoryKHR, 2111 potentially modified to relocate acceleration structure references as 2112 described in that command 2113 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-03413]] 2114 pname:mode must: be 2115 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR 2116 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pInfo-03414]] 2117 The data in pname:src must: have a format compatible with the 2118 destination physical device as returned by 2119 flink:vkGetDeviceAccelerationStructureCompatibilityKHR 2120 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-03746]] 2121 pname:dst must: have been created with a pname:size greater than or 2122 equal to that used to serialize the data in pname:src 2123**** 2124 2125include::{generated}/validity/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] 2126-- 2127 2128[open,refpage='vkGetDeviceAccelerationStructureCompatibilityKHR',desc='Check if a serialized acceleration structure is compatible with the current device',type='protos'] 2129-- 2130:refpage: vkGetDeviceAccelerationStructureCompatibilityKHR 2131 2132To check if a serialized acceleration structure is compatible with the 2133current device call: 2134 2135include::{generated}/api/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] 2136 2137 * pname:device is the device to check the version against. 2138 * pname:pVersionInfo is a pointer to a 2139 slink:VkAccelerationStructureVersionInfoKHR structure specifying version 2140 information to check against the device. 2141 * pname:pCompatibility is a pointer to a 2142 elink:VkAccelerationStructureCompatibilityKHR value in which 2143 compatibility information is returned. 2144 2145.Valid Usage 2146**** 2147 * [[VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-accelerationStructure-08928]] 2148 The <<features-accelerationStructure, 2149 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 2150 feature must: be enabled 2151**** 2152 2153include::{generated}/validity/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] 2154-- 2155 2156[open,refpage='VkAccelerationStructureVersionInfoKHR',desc='Acceleration structure version information',type='structs'] 2157-- 2158:refpage: VkAccelerationStructureVersionKHR 2159 2160The sname:VkAccelerationStructureVersionInfoKHR structure is defined as: 2161 2162include::{generated}/api/structs/VkAccelerationStructureVersionInfoKHR.adoc[] 2163 2164 * pname:sType is a elink:VkStructureType value identifying this structure. 2165 * pname:pNext is `NULL` or a pointer to a structure extending this 2166 structure. 2167 * pname:pVersionData is a pointer to the version header of an acceleration 2168 structure as defined in flink:vkCmdCopyAccelerationStructureToMemoryKHR 2169 2170[NOTE] 2171.Note 2172==== 2173pname:pVersionData is a _pointer_ to an array of 2{times}ename:VK_UUID_SIZE 2174code:uint8_t values instead of two ename:VK_UUID_SIZE arrays as the expected 2175use case for this member is to be pointed at the header of a previously 2176serialized acceleration structure (via 2177flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2178flink:vkCopyAccelerationStructureToMemoryKHR) that is loaded in memory. 2179Using arrays would necessitate extra memory copies of the UUIDs. 2180==== 2181 2182include::{generated}/validity/structs/VkAccelerationStructureVersionInfoKHR.adoc[] 2183-- 2184 2185[open,refpage='VkAccelerationStructureCompatibilityKHR',desc='Acceleration structure compatibility',type='enums'] 2186-- 2187Possible values of pname:pCompatibility returned by 2188flink:vkGetDeviceAccelerationStructureCompatibilityKHR are: 2189 2190include::{generated}/api/enums/VkAccelerationStructureCompatibilityKHR.adoc[] 2191 2192 * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR if the 2193 pname:pVersionData version acceleration structure is compatible with 2194 pname:device. 2195 * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR if the 2196 pname:pVersionData version acceleration structure is not compatible with 2197 pname:device. 2198-- 2199 2200 2201[[host-acceleration-structure]] 2202== Host Acceleration Structure Operations 2203 2204Implementations are also required to provide host implementations of the 2205acceleration structure operations if the 2206<<features-accelerationStructureHostCommands, 2207pname:accelerationStructureHostCommands>> feature is enabled: 2208 2209 * flink:vkBuildAccelerationStructuresKHR corresponding to 2210 flink:vkCmdBuildAccelerationStructuresKHR 2211 * flink:vkCopyAccelerationStructureKHR corresponding to 2212 flink:vkCmdCopyAccelerationStructureKHR 2213 * flink:vkCopyAccelerationStructureToMemoryKHR corresponding to 2214 flink:vkCmdCopyAccelerationStructureToMemoryKHR 2215 * flink:vkCopyMemoryToAccelerationStructureKHR corresponding to 2216 flink:vkCmdCopyMemoryToAccelerationStructureKHR 2217 * flink:vkWriteAccelerationStructuresPropertiesKHR corresponding to 2218 flink:vkCmdWriteAccelerationStructuresPropertiesKHR 2219 2220These commands are functionally equivalent to their device counterparts, 2221except that they are executed on the host timeline, rather than being 2222enqueued into command buffers. 2223 2224All acceleration structures used by the host commands must: be bound to 2225host-visible memory, and all input data for acceleration structure builds 2226must: be referenced using host addresses instead of device addresses. 2227Applications are not required to map acceleration structure memory when 2228using the host commands. 2229 2230 2231[NOTE] 2232.Note 2233==== 2234The flink:vkBuildAccelerationStructuresKHR and 2235flink:vkCmdBuildAccelerationStructuresKHR may: use different algorithms, and 2236thus are not required to produce identical structures. 2237The structures produced by these two commands may: exhibit different memory 2238footprints or traversal performance, but should strive to be similar where 2239possible. 2240 2241Apart from these details, the host and device operations are 2242interchangeable. 2243For example, an application can: use flink:vkBuildAccelerationStructuresKHR 2244to build a structure, compact it on the device using 2245flink:vkCmdCopyAccelerationStructureKHR, and serialize the result using 2246flink:vkCopyAccelerationStructureToMemoryKHR. 2247==== 2248 2249[NOTE] 2250.Note 2251==== 2252For efficient execution, acceleration structures manipulated using these 2253commands should always be bound to host cached memory, as the implementation 2254may need to repeatedly read and write this memory during the execution of 2255the command. 2256==== 2257 2258[open,refpage='vkBuildAccelerationStructuresKHR',desc='Build an acceleration structure on the host',type='protos'] 2259-- 2260:refpage: vkBuildAccelerationStructuresKHR 2261 2262To build acceleration structures on the host, call: 2263 2264include::{generated}/api/protos/vkBuildAccelerationStructuresKHR.adoc[] 2265 2266 * pname:device is the sname:VkDevice for which the acceleration structures 2267 are being built. 2268 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2269 <<deferred-host-operations-requesting, request deferral>> for this 2270 command. 2271 * pname:infoCount is the number of acceleration structures to build. 2272 It specifies the number of the pname:pInfos structures and 2273 pname:ppBuildRangeInfos pointers that must: be provided. 2274 * pname:pInfos is a pointer to an array of pname:infoCount 2275 slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining 2276 the geometry used to build each acceleration structure. 2277 * pname:ppBuildRangeInfos is a pointer to an array of pname:infoCount 2278 pointers to arrays of slink:VkAccelerationStructureBuildRangeInfoKHR 2279 structures. 2280 Each pname:ppBuildRangeInfos[i] is a pointer to an array of 2281 pname:pInfos[i].pname:geometryCount 2282 slink:VkAccelerationStructureBuildRangeInfoKHR structures defining 2283 dynamic offsets to the addresses where geometry data is stored, as 2284 defined by pname:pInfos[i]. 2285 2286This command fulfills the same task as 2287flink:vkCmdBuildAccelerationStructuresKHR but is executed by the host. 2288 2289The fname:vkBuildAccelerationStructuresKHR command provides the ability to 2290initiate multiple acceleration structures builds, however there is no 2291ordering or synchronization implied between any of the individual 2292acceleration structure builds. 2293 2294[NOTE] 2295.Note 2296==== 2297This means that an application cannot: build a top-level acceleration 2298structure in the same flink:vkBuildAccelerationStructuresKHR call as the 2299associated bottom-level or instance acceleration structures are being built. 2300There also cannot: be any memory aliasing between any acceleration structure 2301memories or scratch memories being used by any of the builds. 2302==== 2303 2304.Valid Usage 2305**** 2306 * [[VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581]] 2307 The <<features-accelerationStructureHostCommands, 2308 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2309 feature must: be enabled 2310 2311:maxinstancecheck: pname:ppBuildRangeInfos[i][j].pname:primitiveCount 2312include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] 2313include::{chapters}/commonvalidity/build_acceleration_structure_nonindirect_common.adoc[] 2314include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2315 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03722]] 2316 For each element of pname:pInfos, the pname:buffer used to create its 2317 pname:dstAccelerationStructure member must: be bound to host-visible 2318 device memory 2319 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03723]] 2320 For each element of pname:pInfos, if its pname:mode member is 2321 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer 2322 used to create its pname:srcAccelerationStructure member must: be bound 2323 to host-visible device memory 2324 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03724]] 2325 For each element of pname:pInfos, the pname:buffer used to create each 2326 acceleration structure referenced by the pname:geometry.instances.data 2327 member of any element of pname:pGeometries or pname:ppGeometries with a 2328 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be 2329 bound to host-visible device memory 2330 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03725]] 2331 If pname:pInfos[i].pname:mode is 2332 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses 2333 between pname:pInfos[i].pname:scratchData.hostAddress and 2334 pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid 2335 host memory, where N is given by the pname:buildScratchSize member of 2336 the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned 2337 from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an 2338 identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure 2339 and primitive count 2340 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03726]] 2341 If pname:pInfos[i].pname:mode is 2342 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses 2343 between pname:pInfos[i].pname:scratchData.hostAddress and 2344 pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid 2345 host memory, where N is given by the pname:updateScratchSize member of 2346 the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned 2347 from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an 2348 identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure 2349 and primitive count 2350 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03771]] 2351 For any element of pname:pInfos[i].pname:pGeometries or 2352 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2353 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, 2354 pname:geometry.triangles.vertexData.hostAddress must: be a valid host 2355 address 2356 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03772]] 2357 For any element of pname:pInfos[i].pname:pGeometries or 2358 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2359 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if 2360 pname:geometry.triangles.indexType is not ename:VK_INDEX_TYPE_NONE_KHR, 2361 pname:geometry.triangles.indexData.hostAddress must: be a valid host 2362 address 2363 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03773]] 2364 For any element of pname:pInfos[i].pname:pGeometries or 2365 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2366 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if 2367 pname:geometry.triangles.transformData.hostAddress is not `0`, it must: 2368 be a valid host address 2369 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03774]] 2370 For any element of pname:pInfos[i].pname:pGeometries or 2371 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2372 ename:VK_GEOMETRY_TYPE_AABBS_KHR, pname:geometry.aabbs.data.hostAddress 2373 must: be a valid host address 2374ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2375 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03775]] 2376 For each element of pname:pInfos, the pname:buffer used to create its 2377 pname:dstAccelerationStructure member must: be bound to memory that was 2378 not allocated with multiple instances 2379 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03776]] 2380 For each element of pname:pInfos, if its pname:mode member is 2381 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer 2382 used to create its pname:srcAccelerationStructure member must: be bound 2383 to memory that was not allocated with multiple instances 2384 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03777]] 2385 For each element of pname:pInfos, the pname:buffer used to create each 2386 acceleration structure referenced by the pname:geometry.instances.data 2387 member of any element of pname:pGeometries or pname:ppGeometries with a 2388 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be 2389 bound to memory that was not allocated with multiple instances 2390endif::VK_KHR_device_group,VK_VERSION_1_1[] 2391 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03778]] 2392 For any element of pname:pInfos[i].pname:pGeometries or 2393 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2394 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, 2395 pname:geometry.instances.data.hostAddress must: be a valid host address 2396 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03779]] 2397 For any element of pname:pInfos[i].pname:pGeometries or 2398 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2399 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each 2400 slink:VkAccelerationStructureInstanceKHR::pname:accelerationStructureReference 2401 value in pname:geometry.instances.data.hostAddress must: be a valid 2402 slink:VkAccelerationStructureKHR object 2403ifdef::VK_NV_ray_tracing_motion_blur[] 2404 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-04930]] 2405 For any element of pname:pInfos[i].pname:pGeometries or 2406 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2407 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR with 2408 ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV set, each 2409 pname:accelerationStructureReference in any structure in 2410 slink:VkAccelerationStructureMotionInstanceNV value in 2411 pname:geometry.instances.data.hostAddress must: be a valid 2412 slink:VkAccelerationStructureKHR object 2413endif::VK_NV_ray_tracing_motion_blur[] 2414**** 2415 2416include::{generated}/validity/protos/vkBuildAccelerationStructuresKHR.adoc[] 2417-- 2418 2419[open,refpage='vkCopyAccelerationStructureKHR',desc='Copy an acceleration structure on the host',type='protos'] 2420-- 2421:refpage: vkCopyAccelerationStructureKHR 2422 2423To copy or compact an acceleration structure on the host, call: 2424 2425include::{generated}/api/protos/vkCopyAccelerationStructureKHR.adoc[] 2426 2427 * pname:device is the device which owns the acceleration structures. 2428 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2429 <<deferred-host-operations-requesting, request deferral>> for this 2430 command. 2431 * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR 2432 structure defining the copy operation. 2433 2434This command fulfills the same task as 2435flink:vkCmdCopyAccelerationStructureKHR but is executed by the host. 2436 2437.Valid Usage 2438**** 2439 * [[VUID-vkCopyAccelerationStructureKHR-accelerationStructureHostCommands-03582]] 2440 The <<features-accelerationStructureHostCommands, 2441 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2442include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2443 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03727]] 2444 The pname:buffer used to create pname:pInfo->src must: be bound to 2445 host-visible device memory 2446 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03728]] 2447 The pname:buffer used to create pname:pInfo->dst must: be bound to 2448 host-visible device memory feature must: be enabled 2449ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2450 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03780]] 2451 The pname:buffer used to create pname:pInfo->src must: be bound to 2452 memory that was not allocated with multiple instances 2453 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03781]] 2454 The pname:buffer used to create pname:pInfo->dst must: be bound to 2455 memory that was not allocated with multiple instances 2456endif::VK_KHR_device_group,VK_VERSION_1_1[] 2457**** 2458 2459include::{generated}/validity/protos/vkCopyAccelerationStructureKHR.adoc[] 2460-- 2461 2462[open,refpage='vkCopyMemoryToAccelerationStructureKHR',desc='Deserialize an acceleration structure on the host',type='protos'] 2463-- 2464:refpage: vkCopyMemoryToAccelerationStructureKHR 2465 2466To copy host accessible memory to an acceleration structure, call: 2467 2468include::{generated}/api/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] 2469 2470 * pname:device is the device which owns pname:pInfo->dst. 2471 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2472 <<deferred-host-operations-requesting, request deferral>> for this 2473 command. 2474 * pname:pInfo is a pointer to a 2475 slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the 2476 copy operation. 2477 2478This command fulfills the same task as 2479flink:vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host. 2480 2481This command can accept acceleration structures produced by either 2482flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2483flink:vkCopyAccelerationStructureToMemoryKHR. 2484 2485.Valid Usage 2486**** 2487 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-accelerationStructureHostCommands-03583]] 2488 The <<features-accelerationStructureHostCommands, 2489 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2490 feature must: be enabled 2491include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2492 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03729]] 2493 pname:pInfo->src.hostAddress must: be a valid host pointer 2494 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03750]] 2495 pname:pInfo->src.hostAddress must: be aligned to 16 bytes 2496 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03730]] 2497 The pname:buffer used to create pname:pInfo->dst must: be bound to 2498 host-visible device memory 2499ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2500 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03782]] 2501 The pname:buffer used to create pname:pInfo->dst must: be bound to 2502 memory that was not allocated with multiple instances 2503endif::VK_KHR_device_group,VK_VERSION_1_1[] 2504**** 2505 2506include::{generated}/validity/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] 2507-- 2508 2509[open,refpage='vkCopyAccelerationStructureToMemoryKHR',desc='Serialize an acceleration structure on the host',type='protos'] 2510-- 2511:refpage: vkCopyAccelerationStructureToMemoryKHR 2512 2513To copy an acceleration structure to host accessible memory, call: 2514 2515include::{generated}/api/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] 2516 2517 * pname:device is the device which owns pname:pInfo->src. 2518 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2519 <<deferred-host-operations-requesting, request deferral>> for this 2520 command. 2521 * pname:pInfo is a pointer to a 2522 slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the 2523 copy operation. 2524 2525This command fulfills the same task as 2526flink:vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host. 2527 2528This command produces the same results as 2529flink:vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result 2530directly to a host pointer, and is executed on the host rather than the 2531device. 2532The output may: not necessarily be bit-for-bit identical, but it can be 2533equally used by either flink:vkCmdCopyMemoryToAccelerationStructureKHR or 2534flink:vkCopyMemoryToAccelerationStructureKHR. 2535 2536.Valid Usage 2537**** 2538 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-accelerationStructureHostCommands-03584]] 2539 The <<features-accelerationStructureHostCommands, 2540 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2541 feature must: be enabled 2542include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2543 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03731]] 2544 The pname:buffer used to create pname:pInfo->src must: be bound to 2545 host-visible device memory 2546 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03732]] 2547 pname:pInfo->dst.hostAddress must: be a valid host pointer 2548 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03751]] 2549 pname:pInfo->dst.hostAddress must: be aligned to 16 bytes 2550ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2551 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03783]] 2552 The pname:buffer used to create pname:pInfo->src must: be bound to 2553 memory that was not allocated with multiple instances 2554endif::VK_KHR_device_group,VK_VERSION_1_1[] 2555**** 2556 2557include::{generated}/validity/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] 2558-- 2559 2560[open,refpage='vkWriteAccelerationStructuresPropertiesKHR',desc='Query acceleration structure meta-data on the host',type='protos'] 2561-- 2562:refpage: vkWriteAccelerationStructuresPropertiesKHR 2563 2564To query acceleration structure size parameters on the host, call: 2565 2566include::{generated}/api/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] 2567 2568 * pname:device is the device which owns the acceleration structures in 2569 pname:pAccelerationStructures. 2570 * pname:accelerationStructureCount is the count of acceleration structures 2571 for which to query the property. 2572 * pname:pAccelerationStructures is a pointer to an array of existing 2573 previously built acceleration structures. 2574 * pname:queryType is a elink:VkQueryType value specifying the property to 2575 be queried. 2576 * pname:dataSize is the size in bytes of the buffer pointed to by 2577 pname:pData. 2578 * pname:pData is a pointer to a user-allocated buffer where the results 2579 will be written. 2580 * pname:stride is the stride in bytes between results for individual 2581 queries within pname:pData. 2582 2583This command fulfills the same task as 2584flink:vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the 2585host. 2586 2587.Valid Usage 2588**** 2589 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureHostCommands-03585]] 2590 The <<features-accelerationStructureHostCommands, 2591 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2592 feature must: be enabled 2593include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] 2594 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448]] 2595 If pname:queryType is 2596 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then 2597 pname:stride must: be a multiple of the size of basetype:VkDeviceSize 2598 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449]] 2599 If pname:queryType is 2600 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then 2601 pname:pData must: point to a basetype:VkDeviceSize 2602 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450]] 2603 If pname:queryType is 2604 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 2605 pname:stride must: be a multiple of the size of basetype:VkDeviceSize 2606 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451]] 2607 If pname:queryType is 2608 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 2609 pname:pData must: point to a basetype:VkDeviceSize 2610ifdef::VK_KHR_ray_tracing_maintenance1[] 2611 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06731]] 2612 If pname:queryType is 2613 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:stride 2614 must: be a multiple of the size of basetype:VkDeviceSize 2615 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06732]] 2616 If pname:queryType is 2617 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:pData 2618 must: point to a basetype:VkDeviceSize 2619 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06733]] 2620 If pname:queryType is 2621 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, 2622 then pname:stride must: be a multiple of the size of 2623 basetype:VkDeviceSize 2624 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06734]] 2625 If pname:queryType is 2626 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, 2627 then pname:pData must: point to a basetype:VkDeviceSize 2628endif::VK_KHR_ray_tracing_maintenance1[] 2629 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452]] 2630 pname:dataSize must: be greater than or equal to 2631 [eq]#pname:accelerationStructureCount*pname:stride# 2632 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03733]] 2633 The pname:buffer used to create each acceleration structure in 2634 pname:pAccelerationStructures must: be bound to host-visible device 2635 memory 2636ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2637 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03784]] 2638 The pname:buffer used to create each acceleration structure in 2639 pname:pAccelerationStructures must: be bound to memory that was not 2640 allocated with multiple instances 2641endif::VK_KHR_device_group,VK_VERSION_1_1[] 2642**** 2643 2644include::{generated}/validity/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] 2645-- 2646
