1// Copyright 2020-2023 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 1050 * pname:minX is the x position of one opposing corner of a bounding box. 1051 * pname:minY is the y position of one opposing corner of a bounding box. 1052 * pname:minZ is the z position of one opposing corner of a bounding box. 1053 * pname:maxX is the x position of the other opposing corner of a bounding 1054 box. 1055 * pname:maxY is the y position of the other opposing corner of a bounding 1056 box. 1057 * pname:maxZ is the z position of the other opposing corner of a bounding 1058 box. 1059 1060.Valid Usage 1061**** 1062 * [[VUID-VkAabbPositionsKHR-minX-03546]] 1063 pname:minX must: be less than or equal to pname:maxX 1064 * [[VUID-VkAabbPositionsKHR-minY-03547]] 1065 pname:minY must: be less than or equal to pname:maxY 1066 * [[VUID-VkAabbPositionsKHR-minZ-03548]] 1067 pname:minZ must: be less than or equal to pname:maxZ 1068**** 1069 1070include::{generated}/validity/structs/VkAabbPositionsKHR.adoc[] 1071-- 1072 1073ifdef::VK_KHR_acceleration_structure[] 1074[open,refpage='VkAccelerationStructureGeometryInstancesDataKHR',desc='Structure specifying a geometry consisting of instances of other acceleration structures',type='structs'] 1075-- 1076:refpage: VkAccelerationStructureGeometryInstancesDataKHR 1077 1078The sname:VkAccelerationStructureGeometryInstancesDataKHR structure is 1079defined as: 1080 1081include::{generated}/api/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] 1082 1083 * pname:sType is a elink:VkStructureType value identifying this structure. 1084 * pname:pNext is `NULL` or a pointer to a structure extending this 1085 structure. 1086 * pname:arrayOfPointers specifies whether pname:data is used as an array 1087 of addresses or just an array. 1088 * pname:data is either the address of an array of device or host addresses 1089 referencing individual slink:VkAccelerationStructureInstanceKHR 1090 structures 1091ifdef::VK_NV_ray_tracing_motion_blur[] 1092 or packed motion instance information as described in 1093 <<acceleration-structure-motion-instances, motion instances>> 1094endif::VK_NV_ray_tracing_motion_blur[] 1095 if pname:arrayOfPointers is ename:VK_TRUE, or the address of an array of 1096 slink:VkAccelerationStructureInstanceKHR 1097ifdef::VK_NV_ray_tracing_motion_blur[] 1098 or slink:VkAccelerationStructureMotionInstanceNV 1099endif::VK_NV_ray_tracing_motion_blur[] 1100 structures. 1101 Addresses and slink:VkAccelerationStructureInstanceKHR structures are 1102 tightly packed. 1103ifdef::VK_NV_ray_tracing_motion_blur[] 1104 slink:VkAccelerationStructureMotionInstanceNV structures have a stride 1105 of 160 bytes. 1106endif::VK_NV_ray_tracing_motion_blur[] 1107 1108include::{generated}/validity/structs/VkAccelerationStructureGeometryInstancesDataKHR.adoc[] 1109-- 1110endif::VK_KHR_acceleration_structure[] 1111 1112[open,refpage='VkAccelerationStructureInstanceKHR',desc='Structure specifying a single acceleration structure instance for building into an acceleration structure geometry',type='structs',alias='VkAccelerationStructureInstanceNV'] 1113-- 1114:refpage: VkAccelerationStructureInstanceKHR 1115 1116_Acceleration structure instances_ can: be built into top-level acceleration 1117structures. 1118Each acceleration structure instance is a separate entry in the top-level 1119acceleration structure which includes all the geometry of a bottom-level 1120acceleration structure at a transformed location. 1121Multiple instances can: point to the same bottom level acceleration 1122structure. 1123 1124An acceleration structure instance is defined by the structure: 1125 1126include::{generated}/api/structs/VkAccelerationStructureInstanceKHR.adoc[] 1127 1128ifdef::VK_NV_ray_tracing[] 1129or the equivalent 1130 1131include::{generated}/api/structs/VkAccelerationStructureInstanceNV.adoc[] 1132endif::VK_NV_ray_tracing[] 1133 1134 * pname:transform is a slink:VkTransformMatrixKHR structure describing a 1135 transformation to be applied to the acceleration structure. 1136 * pname:instanceCustomIndex is a 24-bit user-specified index value 1137 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1138 * pname:mask is an 8-bit visibility mask for the geometry. 1139 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1140 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1141 calculating the hit shader binding table index. 1142 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1143 values to apply to this instance. 1144 * pname:accelerationStructureReference is either: 1145 ** a device address containing the value obtained from 1146ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1147ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1148ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1149 (used by device operations which reference acceleration structures) or, 1150 ** a slink:VkAccelerationStructureKHR object (used by host operations 1151 which reference acceleration structures). 1152 1153The C language specification does not define the ordering of bit-fields, but 1154in practice, this struct produces the correct layout with existing 1155compilers. 1156The intended bit pattern is for the following: 1157 1158 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1159 single code:uint32_t was specified in their place 1160 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1161 that memory 1162 ** pname:mask occupies the 8 most significant bits of that memory 1163 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1164 same memory as if a single code:uint32_t was specified in their place 1165 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1166 significant bits of that memory 1167 ** pname:flags occupies the 8 most significant bits of that memory 1168 1169If a compiler produces code that diverges from that pattern, applications 1170must: employ another method to set values according to the correct bit 1171pattern. 1172 1173include::{generated}/validity/structs/VkAccelerationStructureInstanceKHR.adoc[] 1174-- 1175 1176[open,refpage='VkGeometryInstanceFlagBitsKHR',desc='Instance flag bits',type='enums',alias='VkGeometryInstanceFlagBitsNV'] 1177-- 1178:refpage: VkGeometryInstanceFlagBitsKHR 1179 1180Possible values of pname:flags in the instance modifying the behavior of 1181that instance are: 1182 1183include::{generated}/api/enums/VkGeometryInstanceFlagBitsKHR.adoc[] 1184 1185ifdef::VK_NV_ray_tracing[] 1186or the equivalent 1187 1188include::{generated}/api/enums/VkGeometryInstanceFlagBitsNV.adoc[] 1189endif::VK_NV_ray_tracing[] 1190 1191 * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR disables 1192 face culling for this instance. 1193 * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FLIP_FACING_BIT_KHR indicates that 1194 the <<ray-traversal-culling-face, facing determination>> for geometry in 1195 this instance is inverted. 1196 Because the facing is determined in object space, an instance transform 1197 does not change the winding, but a geometry transform does. 1198 * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR causes this instance to 1199 act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were specified on all 1200 geometries referenced by this instance. 1201 This behavior can: be overridden by the SPIR-V code:NoOpaqueKHR ray 1202 flag. 1203 * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR causes this instance 1204 to act as though ename:VK_GEOMETRY_OPAQUE_BIT_KHR were not specified on 1205 all geometries referenced by this instance. 1206 This behavior can: be overridden by the SPIR-V code:OpaqueKHR ray flag. 1207 1208ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and 1209ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must: not be used in the 1210same flag. 1211-- 1212 1213[open,refpage='VkGeometryInstanceFlagsKHR',desc='Bitmask of VkGeometryInstanceFlagBitsKHR',type='flags',alias='VkGeometryInstanceFlagsNV'] 1214-- 1215:refpage: VkGeometryInstanceFlagsKHR 1216 1217include::{generated}/api/flags/VkGeometryInstanceFlagsKHR.adoc[] 1218 1219ifdef::VK_NV_ray_tracing[] 1220or the equivalent 1221 1222include::{generated}/api/flags/VkGeometryInstanceFlagsNV.adoc[] 1223endif::VK_NV_ray_tracing[] 1224 1225tname:VkGeometryInstanceFlagsKHR is a bitmask type for setting a mask of 1226zero or more elink:VkGeometryInstanceFlagBitsKHR. 1227-- 1228 1229ifdef::VK_NV_ray_tracing_motion_blur[] 1230[open,refpage='VkAccelerationStructureMotionInstanceNV',desc='Structure specifying a single acceleration structure motion instance for building into an acceleration structure geometry',type='structs'] 1231-- 1232:refpage: VkAccelerationStructureMotionInstanceNV 1233 1234_Acceleration structure motion instances_ can: be built into top-level 1235acceleration structures. 1236Each acceleration structure instance is a separate entry in the top-level 1237acceleration structure which includes all the geometry of a bottom-level 1238acceleration structure at a transformed location including a type of motion 1239and parameters to determine the motion of the instance over time. 1240 1241An acceleration structure motion instance is defined by the structure: 1242 1243include::{generated}/api/structs/VkAccelerationStructureMotionInstanceNV.adoc[] 1244 1245 * pname:type is a elink:VkAccelerationStructureMotionInstanceTypeNV 1246 enumerant identifying which type of motion instance this is and which 1247 type of the union is valid. 1248 * pname:flags is currently unused, but is required to keep natural 1249 alignment of pname:data. 1250 * pname:data is a slink:VkAccelerationStructureMotionInstanceDataNV 1251 containing motion instance data for this instance. 1252 1253[NOTE] 1254.Note 1255==== 1256If writing this other than with a standard C compiler, note that the final 1257structure should be 152 bytes in size. 1258==== 1259 1260include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceNV.adoc[] 1261-- 1262 1263[open,refpage='VkAccelerationStructureMotionInstanceDataNV',desc='Union specifying a acceleration structure motion instance data for building into an acceleration structure geometry',type='structs'] 1264-- 1265:refpage: VkAccelerationStructureMotionInstanceDataNV 1266 1267Acceleration structure motion instance is defined by the union: 1268 1269include::{generated}/api/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] 1270 1271 * pname:staticInstance is a slink:VkAccelerationStructureInstanceKHR 1272 structure containing data for a static instance. 1273 * pname:matrixMotionInstance is a 1274 slink:VkAccelerationStructureMatrixMotionInstanceNV structure containing 1275 data for a matrix motion instance. 1276 * pname:srtMotionInstance is a 1277 slink:VkAccelerationStructureSRTMotionInstanceNV structure containing 1278 data for an SRT motion instance. 1279 1280include::{generated}/validity/structs/VkAccelerationStructureMotionInstanceDataNV.adoc[] 1281-- 1282 1283[open,refpage='VkAccelerationStructureMotionInstanceFlagsNV',desc='Reserved for future use',type='flags'] 1284-- 1285include::{generated}/api/flags/VkAccelerationStructureMotionInstanceFlagsNV.adoc[] 1286 1287tname:VkAccelerationStructureMotionInstanceFlagsNV is a bitmask type for 1288setting a mask, but is currently reserved for future use. 1289-- 1290 1291[open,refpage='VkAccelerationStructureMotionInstanceTypeNV',desc='Enum specifying a type of acceleration structure motion instance data for building into an acceleration structure geometry',type='enums'] 1292-- 1293:refpage: VkAccelerationStructureMotionInstanceTypeNV 1294 1295The ename:VkAccelerationStructureMotionInstanceTypeNV enumeration is defined 1296as: 1297 1298include::{generated}/api/enums/VkAccelerationStructureMotionInstanceTypeNV.adoc[] 1299 1300 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_STATIC_NV specifies 1301 that the instance is a static instance with no instance motion. 1302 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_MATRIX_MOTION_NV 1303 specifies that the instance is a motion instance with motion specified 1304 by interpolation between two matrices. 1305 * ename:VK_ACCELERATION_STRUCTURE_MOTION_INSTANCE_TYPE_SRT_MOTION_NV 1306 specifies that the instance is a motion instance with motion specified 1307 by interpolation in the SRT decomposition. 1308-- 1309 1310[open,refpage='VkAccelerationStructureMatrixMotionInstanceNV',desc='Structure specifying a single acceleration structure matrix motion instance for building into an acceleration structure geometry',type='structs'] 1311-- 1312:refpage: VkAccelerationStructureMatrixMotionInstanceNV 1313 1314An acceleration structure matrix motion instance is defined by the 1315structure: 1316 1317include::{generated}/api/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] 1318 1319 * pname:transformT0 is a slink:VkTransformMatrixKHR structure describing a 1320 transformation to be applied to the acceleration structure at time 0. 1321 * pname:transformT1 is a slink:VkTransformMatrixKHR structure describing a 1322 transformation to be applied to the acceleration structure at time 1. 1323 * pname:instanceCustomIndex is a 24-bit user-specified index value 1324 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1325 * pname:mask is an 8-bit visibility mask for the geometry. 1326 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1327 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1328 calculating the hit shader binding table index. 1329 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1330 values to apply to this instance. 1331 * pname:accelerationStructureReference is either: 1332 ** a device address containing the value obtained from 1333ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1334ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1335ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1336 (used by device operations which reference acceleration structures) or, 1337 ** a slink:VkAccelerationStructureKHR object (used by host operations 1338 which reference acceleration structures). 1339 1340The C language specification does not define the ordering of bit-fields, but 1341in practice, this struct produces the correct layout with existing 1342compilers. 1343The intended bit pattern is for the following: 1344 1345 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1346 single code:uint32_t was specified in their place 1347 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1348 that memory 1349 ** pname:mask occupies the 8 most significant bits of that memory 1350 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1351 same memory as if a single code:uint32_t was specified in their place 1352 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1353 significant bits of that memory 1354 ** pname:flags occupies the 8 most significant bits of that memory 1355 1356If a compiler produces code that diverges from that pattern, applications 1357must: employ another method to set values according to the correct bit 1358pattern. 1359 1360The transform for a matrix motion instance at a point in time is derived by 1361component-wise linear interpolation of the two transforms. 1362That is, for a code:time in [0,1] the resulting transform is 1363 1364 {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} 1365 pname:transformT1 {times} code:time# 1366 1367include::{generated}/validity/structs/VkAccelerationStructureMatrixMotionInstanceNV.adoc[] 1368-- 1369 1370[open,refpage='VkAccelerationStructureSRTMotionInstanceNV',desc='Structure specifying a single acceleration structure SRT motion instance for building into an acceleration structure geometry',type='structs'] 1371-- 1372:refpage: VkAccelerationStructureSRTMotionInstanceNV 1373 1374An acceleration structure SRT motion instance is defined by the structure: 1375 1376include::{generated}/api/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] 1377 1378 * pname:transformT0 is a slink:VkSRTDataNV structure describing a 1379 transformation to be applied to the acceleration structure at time 0. 1380 * pname:transformT1 is a slink:VkSRTDataNV structure describing a 1381 transformation to be applied to the acceleration structure at time 1. 1382 * pname:instanceCustomIndex is a 24-bit user-specified index value 1383 accessible to ray shaders in the code:InstanceCustomIndexKHR built-in. 1384 * pname:mask is an 8-bit visibility mask for the geometry. 1385 The instance may: only be hit if `Cull Mask & instance.mask != 0` 1386 * pname:instanceShaderBindingTableRecordOffset is a 24-bit offset used in 1387 calculating the hit shader binding table index. 1388 * pname:flags is an 8-bit mask of elink:VkGeometryInstanceFlagBitsKHR 1389 values to apply to this instance. 1390 * pname:accelerationStructureReference is either: 1391 ** a device address containing the value obtained from 1392ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1393ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1394ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1395 (used by device operations which reference acceleration structures) or, 1396 ** a slink:VkAccelerationStructureKHR object (used by host operations 1397 which reference acceleration structures). 1398 1399The C language specification does not define the ordering of bit-fields, but 1400in practice, this struct produces the correct layout with existing 1401compilers. 1402The intended bit pattern is for the following: 1403 1404 * pname:instanceCustomIndex and pname:mask occupy the same memory as if a 1405 single code:uint32_t was specified in their place 1406 ** pname:instanceCustomIndex occupies the 24 least significant bits of 1407 that memory 1408 ** pname:mask occupies the 8 most significant bits of that memory 1409 * pname:instanceShaderBindingTableRecordOffset and pname:flags occupy the 1410 same memory as if a single code:uint32_t was specified in their place 1411 ** pname:instanceShaderBindingTableRecordOffset occupies the 24 least 1412 significant bits of that memory 1413 ** pname:flags occupies the 8 most significant bits of that memory 1414 1415If a compiler produces code that diverges from that pattern, applications 1416must: employ another method to set values according to the correct bit 1417pattern. 1418 1419The transform for a SRT motion instance at a point in time is derived from 1420component-wise linear interpolation of the two SRT transforms. 1421That is, for a code:time in [0,1] the resulting transform is 1422 1423 {empty}:: [eq]#pname:transformT0 {times} (1 - code:time) {plus} 1424 pname:transformT1 {times} code:time# 1425 1426include::{generated}/validity/structs/VkAccelerationStructureSRTMotionInstanceNV.adoc[] 1427-- 1428 1429[open,refpage='VkSRTDataNV',desc='Structure specifying a transform in SRT decomposition',type='structs'] 1430-- 1431:refpage: VkSRTDataNV 1432 1433An acceleration structure SRT transform is defined by the structure: 1434 1435include::{generated}/api/structs/VkSRTDataNV.adoc[] 1436 1437 * pname:sx is the x component of the scale of the transform 1438 * pname:a is one component of the shear for the transform 1439 * pname:b is one component of the shear for the transform 1440 * pname:pvx is the x component of the pivot point of the transform 1441 * pname:sy is the y component of the scale of the transform 1442 * pname:c is one component of the shear for the transform 1443 * pname:pvy is the y component of the pivot point of the transform 1444 * pname:sz is the z component of the scale of the transform 1445 * pname:pvz is the z component of the pivot point of the transform 1446 * pname:qx is the x component of the rotation quaternion 1447 * pname:qy is the y component of the rotation quaternion 1448 * pname:qz is the z component of the rotation quaternion 1449 * pname:qw is the w component of the rotation quaternion 1450 * pname:tx is the x component of the post-rotation translation 1451 * pname:ty is the y component of the post-rotation translation 1452 * pname:tz is the z component of the post-rotation translation 1453 1454This transform decomposition consists of three elements. 1455The first is a matrix S, consisting of a scale, shear, and translation, 1456usually used to define the pivot point of the following rotation. 1457This matrix is constructed from the parameters above by: 1458 1459[latexmath] 1460++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1461S = 1462\left( 1463 \begin{matrix} 1464 sx & a & b & pvx \\ 1465 0 & sy & c & pvy \\ 1466 0 & 0 & sz & pvz 1467 \end{matrix} 1468\right) 1469++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1470 1471The rotation quaternion is defined as: 1472 1473 {empty}:: [eq]#code:R = [ pname:qx, pname:qy, pname:qz, pname:qw ]# 1474 1475This is a rotation around a conceptual normalized axis [eq]#[ ax, ay, az ]# 1476of amount code:theta such that: 1477 1478 {empty}:: [eq]#[ pname:qx, pname:qy, pname:qz ] = sin(code:theta/2) 1479 {times} [ code:ax, code:ay, code:az ]# 1480 1481and 1482 1483 {empty}:: [eq]#pname:qw = cos(code:theta/2)# 1484 1485Finally, the transform has a translation T constructed from the parameters 1486above by: 1487 1488[latexmath] 1489++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1490T = 1491\left( 1492 \begin{matrix} 1493 1 & 0 & 0 & tx \\ 1494 0 & 1 & 0 & ty \\ 1495 0 & 0 & 1 & tz 1496 \end{matrix} 1497\right) 1498++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1499 1500The effective derived transform is then given by 1501 1502 {empty}:: [eq]#code:T {times} code:R {times} code:S# 1503 1504include::{generated}/validity/structs/VkSRTDataNV.adoc[] 1505-- 1506endif::VK_NV_ray_tracing_motion_blur[] 1507 1508ifdef::VK_KHR_acceleration_structure[] 1509[open,refpage='VkAccelerationStructureBuildRangeInfoKHR',desc='Structure specifying build offsets and counts for acceleration structure builds',type='structs'] 1510-- 1511:refpage: VkAccelerationStructureBuildOffsetInfoKHR 1512 1513sname:VkAccelerationStructureBuildRangeInfoKHR is defined as: 1514 1515include::{generated}/api/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] 1516 1517 * pname:primitiveCount defines the number of primitives for a 1518 corresponding acceleration structure geometry. 1519 * pname:primitiveOffset defines an offset in bytes into the memory where 1520 primitive data is defined. 1521 * pname:firstVertex is the index of the first vertex to build from for 1522 triangle geometry. 1523 * pname:transformOffset defines an offset in bytes into the memory where a 1524 transform matrix is defined. 1525 1526The primitive count and primitive offset are interpreted differently 1527depending on the elink:VkGeometryTypeKHR used: 1528 1529 * For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, 1530 pname:primitiveCount is the number of triangles to be built, where each 1531 triangle is treated as 3 vertices. 1532 ** If the geometry uses indices, [eq]#pname:primitiveCount {times} 3# 1533 indices are consumed from 1534 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData, 1535 starting at an offset of pname:primitiveOffset. 1536 The value of pname:firstVertex is added to the index values before 1537 fetching vertices. 1538 ** If the geometry does not use indices, [eq]#pname:primitiveCount {times} 1539 3# vertices are consumed from 1540 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData, 1541 starting at an offset of [eq]#pname:primitiveOffset {plus} 1542 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexStride 1543 {times} pname:firstVertex#. 1544 ** If 1545 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 1546 is not `NULL`, a single slink:VkTransformMatrixKHR structure is 1547 consumed from 1548 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData, 1549 at an offset of pname:transformOffset. 1550 This matrix describes a transformation from the space in which the 1551 vertices for all triangles in this geometry are described to the space 1552 in which the acceleration structure is defined. 1553 * For geometries of type ename:VK_GEOMETRY_TYPE_AABBS_KHR, 1554 pname:primitiveCount is the number of axis-aligned bounding boxes. 1555 pname:primitiveCount slink:VkAabbPositionsKHR structures are consumed 1556 from slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data, 1557 starting at an offset of pname:primitiveOffset. 1558 * For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, 1559 pname:primitiveCount is the number of acceleration structures. 1560 pname:primitiveCount slink:VkAccelerationStructureInstanceKHR 1561ifdef::VK_NV_ray_tracing_motion_blur[] 1562 or slink:VkAccelerationStructureMotionInstanceNV 1563endif::VK_NV_ray_tracing_motion_blur[] 1564 structures are consumed from 1565 slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data, 1566 starting at an offset of pname:primitiveOffset. 1567 1568.Valid Usage 1569**** 1570 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03656]] 1571 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the 1572 geometry uses indices, the offset pname:primitiveOffset from 1573 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexData 1574 must: be a multiple of the element size of 1575 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:indexType 1576 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03657]] 1577 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the 1578 geometry does not use indices, the offset pname:primitiveOffset from 1579 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexData 1580 must: be a multiple of the component size of 1581 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:vertexFormat 1582 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-transformOffset-03658]] 1583 For geometries of type ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the offset 1584 pname:transformOffset from 1585 slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 1586 must: be a multiple of 16 1587 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03659]] 1588 For geometries of type ename:VK_GEOMETRY_TYPE_AABBS_KHR, the offset 1589 pname:primitiveOffset from 1590 slink:VkAccelerationStructureGeometryAabbsDataKHR::pname:data must: be a 1591 multiple of 8 1592 * [[VUID-VkAccelerationStructureBuildRangeInfoKHR-primitiveOffset-03660]] 1593 For geometries of type ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, the offset 1594 pname:primitiveOffset from 1595 slink:VkAccelerationStructureGeometryInstancesDataKHR::pname:data must: 1596 be a multiple of 16 1597**** 1598 1599include::{generated}/validity/structs/VkAccelerationStructureBuildRangeInfoKHR.adoc[] 1600-- 1601endif::VK_KHR_acceleration_structure[] 1602 1603 1604[[acceleration-structure-copying]] 1605=== Copying Acceleration Structures 1606 1607An additional command exists for copying acceleration structures without 1608updating their contents. 1609The acceleration structure object can: be compacted in order to improve 1610performance. 1611Before copying, an application must: query the size of the resulting 1612acceleration structure. 1613 1614[open,refpage='vkCmdWriteAccelerationStructuresPropertiesKHR',desc='Write acceleration structure result parameters to query results.',type='protos'] 1615-- 1616:refpage: vkCmdWriteAccelerationStructuresPropertiesKHR 1617 1618To query acceleration structure size parameters call: 1619 1620ifdef::VK_KHR_acceleration_structure[] 1621include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] 1622endif::VK_KHR_acceleration_structure[] 1623 1624 * pname:commandBuffer is the command buffer into which the command will be 1625 recorded. 1626 * pname:accelerationStructureCount is the count of acceleration structures 1627 for which to query the property. 1628 * pname:pAccelerationStructures is a pointer to an array of existing 1629 previously built acceleration structures. 1630 * pname:queryType is a elink:VkQueryType value specifying the type of 1631 queries managed by the pool. 1632 * pname:queryPool is the query pool that will manage the results of the 1633 query. 1634 * pname:firstQuery is the first query index within the query pool that 1635 will contain the pname:accelerationStructureCount number of results. 1636 1637Accesses to any of the acceleration structures listed in 1638pname:pAccelerationStructures must: be <<synchronization-dependencies, 1639synchronized>> with the 1640ifdef::VK_KHR_synchronization2[] 1641ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1642<<synchronization-pipeline-stages, pipeline stage>> or the 1643endif::VK_KHR_synchronization2[] 1644ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1645<<synchronization-pipeline-stages, pipeline stage>>, and an 1646<<synchronization-access-types, access type>> of 1647ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1648 1649 * If pname:queryType is 1650 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then the 1651 value written out is the number of bytes required by a compacted 1652 acceleration structure. 1653 * If pname:queryType is 1654 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 1655 the value written out is the number of bytes required by a serialized 1656 acceleration structure. 1657 1658.Valid Usage 1659**** 1660 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructure-08924]] 1661 The <<features-accelerationStructure, 1662 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1663 feature must: be enabled 1664 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493]] 1665 pname:queryPool must: have been created with a pname:queryType matching 1666 pname:queryType 1667 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494]] 1668 The queries identified by pname:queryPool and pname:firstQuery must: be 1669 _unavailable_ 1670 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-buffer-03736]] 1671 The pname:buffer used to create each acceleration structure in 1672 pname:pAccelerationStructures must: be bound to device memory 1673 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-query-04880]] 1674 The sum of pname:query plus pname:accelerationStructureCount must: be 1675 less than or equal to the number of queries in pname:queryPool 1676include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] 1677**** 1678 1679include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesKHR.adoc[] 1680-- 1681 1682ifdef::VK_NV_ray_tracing[] 1683[open,refpage='vkCmdWriteAccelerationStructuresPropertiesNV',desc='Write acceleration structure result parameters to query results.',type='protos'] 1684-- 1685:refpage: vkCmdWriteAccelerationStructuresPropertiesNV 1686 1687To query acceleration structure size parameters call: 1688 1689include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] 1690 1691 1692 * pname:commandBuffer is the command buffer into which the command will be 1693 recorded. 1694 * pname:accelerationStructureCount is the count of acceleration structures 1695 for which to query the property. 1696 * pname:pAccelerationStructures is a pointer to an array of existing 1697 previously built acceleration structures. 1698 * pname:queryType is a elink:VkQueryType value specifying the type of 1699 queries managed by the pool. 1700 * pname:queryPool is the query pool that will manage the results of the 1701 query. 1702 * pname:firstQuery is the first query index within the query pool that 1703 will contain the pname:accelerationStructureCount number of results. 1704 1705Accesses to any of the acceleration structures listed in 1706pname:pAccelerationStructures must: be <<synchronization-dependencies, 1707synchronized>> with the 1708ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1709<<synchronization-pipeline-stages, pipeline stage>> and an 1710<<synchronization-access-types, access type>> of 1711ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1712 1713.Valid Usage 1714**** 1715 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03755]] 1716 pname:queryPool must: have been created with a pname:queryType matching 1717 pname:queryType 1718 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-03756]] 1719 The queries identified by pname:queryPool and pname:firstQuery must: be 1720 _unavailable_ 1721 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructure-03757]] 1722 pname:accelerationStructure must: be bound completely and contiguously 1723 to a single sname:VkDeviceMemory object via 1724 flink:vkBindAccelerationStructureMemoryNV 1725 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-04958]] 1726 All acceleration structures in pname:pAccelerationStructures must: have 1727 been built prior to the execution of this command 1728 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-pAccelerationStructures-06215]] 1729 All acceleration structures in pname:pAccelerationStructures must: have 1730 been built with 1731 ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if 1732 pname:queryType is 1733 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV 1734 * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-06216]] 1735 pname:queryType must: be 1736 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV 1737**** 1738 1739include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesNV.adoc[] 1740-- 1741 1742[open,refpage='vkCmdCopyAccelerationStructureNV',desc='Copy an acceleration structure',type='protos'] 1743-- 1744:refpage: vkCmdCopyAccelerationStructureNV 1745 1746To copy an acceleration structure call: 1747 1748include::{generated}/api/protos/vkCmdCopyAccelerationStructureNV.adoc[] 1749 1750 * pname:commandBuffer is the command buffer into which the command will be 1751 recorded. 1752 * pname:dst is the target acceleration structure for the copy. 1753 * pname:src is the source acceleration structure for the copy. 1754 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 1755 specifying additional operations to perform during the copy. 1756 1757Accesses to pname:src and pname:dst must: be <<synchronization-dependencies, 1758synchronized>> with the 1759ifdef::VK_KHR_synchronization2[] 1760ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1761<<synchronization-pipeline-stages, pipeline stage>> or the 1762endif::VK_KHR_synchronization2[] 1763ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1764<<synchronization-pipeline-stages, pipeline stage>>, and an 1765<<synchronization-access-types, access type>> of 1766ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 1767ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. 1768 1769.Valid Usage 1770**** 1771include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] 1772**** 1773 1774include::{generated}/validity/protos/vkCmdCopyAccelerationStructureNV.adoc[] 1775-- 1776endif::VK_NV_ray_tracing[] 1777 1778ifdef::VK_KHR_acceleration_structure[] 1779[open,refpage='vkCmdCopyAccelerationStructureKHR',desc='Copy an acceleration structure',type='protos'] 1780-- 1781:refpage: vkCmdCopyAccelerationStructureKHR 1782 1783To copy an acceleration structure call: 1784 1785include::{generated}/api/protos/vkCmdCopyAccelerationStructureKHR.adoc[] 1786 1787 * pname:commandBuffer is the command buffer into which the command will be 1788 recorded. 1789 * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR 1790 structure defining the copy operation. 1791 1792This command copies the pname:pInfo->src acceleration structure to the 1793pname:pInfo->dst acceleration structure in the manner specified by 1794pname:pInfo->mode. 1795 1796Accesses to pname:pInfo->src and pname:pInfo->dst must: be 1797<<synchronization-dependencies, synchronized>> with the 1798ifdef::VK_KHR_synchronization2[] 1799ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1800<<synchronization-pipeline-stages, pipeline stage>> or the 1801endif::VK_KHR_synchronization2[] 1802ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1803<<synchronization-pipeline-stages, pipeline stage>>, and an 1804<<synchronization-access-types, access type>> of 1805ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR or 1806ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR as appropriate. 1807 1808.Valid Usage 1809**** 1810 * [[VUID-vkCmdCopyAccelerationStructureKHR-accelerationStructure-08925]] 1811 The <<features-accelerationStructure, 1812 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1813 feature must: be enabled 1814 * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03737]] 1815 The pname:buffer used to create pname:pInfo->src must: be bound to 1816 device memory 1817 * [[VUID-vkCmdCopyAccelerationStructureKHR-buffer-03738]] 1818 The pname:buffer used to create pname:pInfo->dst must: be bound to 1819 device memory 1820**** 1821 1822include::{generated}/validity/protos/vkCmdCopyAccelerationStructureKHR.adoc[] 1823-- 1824 1825[open,refpage='VkCopyAccelerationStructureInfoKHR',desc='Parameters for copying an acceleration structure',type='structs'] 1826-- 1827:refpage: VkCopyAccelerationStructureInfoKHR 1828 1829The sname:VkCopyAccelerationStructureInfoKHR structure is defined as: 1830 1831include::{generated}/api/structs/VkCopyAccelerationStructureInfoKHR.adoc[] 1832 1833 * pname:sType is a elink:VkStructureType value identifying this structure. 1834 * pname:pNext is `NULL` or a pointer to a structure extending this 1835 structure. 1836 * pname:src is the source acceleration structure for the copy. 1837 * pname:dst is the target acceleration structure for the copy. 1838 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 1839 specifying additional operations to perform during the copy. 1840 1841.Valid Usage 1842**** 1843include::{chapters}/commonvalidity/copy_acceleration_structure_common.adoc[] 1844**** 1845 1846include::{generated}/validity/structs/VkCopyAccelerationStructureInfoKHR.adoc[] 1847-- 1848endif::VK_KHR_acceleration_structure[] 1849 1850[open,refpage='VkCopyAccelerationStructureModeKHR',desc='Acceleration structure copy mode',type='enums',alias='VkCopyAccelerationStructureModeNV'] 1851-- 1852:refpage: VkCopyAccelerationStructureModeKHR 1853 1854Possible values of pname:mode specifying additional operations to perform 1855during the copy, are: 1856 1857include::{generated}/api/enums/VkCopyAccelerationStructureModeKHR.adoc[] 1858 1859ifdef::VK_NV_ray_tracing[] 1860or the equivalent 1861 1862include::{generated}/api/enums/VkCopyAccelerationStructureModeNV.adoc[] 1863endif::VK_NV_ray_tracing[] 1864 1865 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_KHR creates a direct 1866 copy of the acceleration structure specified in pname:src into the one 1867 specified by pname:dst. 1868 The pname:dst acceleration structure must: have been created with the 1869 same parameters as pname:src. 1870 If pname:src contains references to other acceleration structures, 1871 pname:dst will reference the same acceleration structures. 1872 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR creates a more 1873 compact version of an acceleration structure pname:src into pname:dst. 1874 The acceleration structure pname:dst must: have been created with a size 1875 at least as large as that returned by 1876 flink:vkCmdWriteAccelerationStructuresPropertiesKHR 1877ifdef::VK_KHR_acceleration_structure[] 1878 or flink:vkWriteAccelerationStructuresPropertiesKHR 1879endif::VK_KHR_acceleration_structure[] 1880 after the build of the acceleration structure specified by pname:src. 1881 If pname:src contains references to other acceleration structures, 1882 pname:dst will reference the same acceleration structures. 1883 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR serializes the 1884 acceleration structure to a semi-opaque format which can be reloaded on 1885 a compatible implementation. 1886 * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR deserializes 1887 the semi-opaque serialization format in the buffer to the acceleration 1888 structure. 1889-- 1890 1891[open,refpage='vkCmdCopyAccelerationStructureToMemoryKHR',desc='Copy an acceleration structure to device memory',type='protos'] 1892-- 1893:refpage: vkCmdCopyAccelerationStructureToMemoryKHR 1894 1895To copy an acceleration structure to device memory call: 1896 1897include::{generated}/api/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] 1898 1899 * pname:commandBuffer is the command buffer into which the command will be 1900 recorded. 1901 * pname:pInfo is an a pointer to a 1902 slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the 1903 copy operation. 1904 1905Accesses to pname:pInfo->src must: be <<synchronization-dependencies, 1906synchronized>> with the 1907ifdef::VK_KHR_synchronization2[] 1908ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1909<<synchronization-pipeline-stages, pipeline stage>> or the 1910endif::VK_KHR_synchronization2[] 1911ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1912<<synchronization-pipeline-stages, pipeline stage>>, and an 1913<<synchronization-access-types, access type>> of 1914ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR. 1915Accesses to the buffer indicated by pname:pInfo->dst.deviceAddress must: be 1916synchronized with the 1917ifdef::VK_KHR_synchronization2[] 1918ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 1919<<synchronization-pipeline-stages, pipeline stage>> or the 1920endif::VK_KHR_synchronization2[] 1921ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 1922<<synchronization-pipeline-stages, pipeline stage>>, and an and an access 1923type of ename:VK_ACCESS_TRANSFER_WRITE_BIT. 1924 1925This command produces the same results as 1926flink:vkCopyAccelerationStructureToMemoryKHR, but writes its result to a 1927device address, and is executed on the device rather than the host. 1928The output may: not necessarily be bit-for-bit identical, but it can be 1929equally used by either flink:vkCmdCopyMemoryToAccelerationStructureKHR or 1930flink:vkCopyMemoryToAccelerationStructureKHR. 1931 1932[[serialized-as-header]] 1933The defined header structure for the serialized data consists of: 1934 1935 * ename:VK_UUID_SIZE bytes of data matching 1936 sname:VkPhysicalDeviceIDProperties::pname:driverUUID 1937 * ename:VK_UUID_SIZE bytes of data identifying the compatibility for 1938 comparison using flink:vkGetDeviceAccelerationStructureCompatibilityKHR 1939 * A 64-bit integer of the total size matching the value queried using 1940 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 1941 * A 64-bit integer of the deserialized size to be passed in to 1942 sname:VkAccelerationStructureCreateInfoKHR::pname:size 1943 * A 64-bit integer of the count of the number of acceleration structure 1944 handles following. 1945ifdef::VK_KHR_ray_tracing_maintenance1[] 1946 This value matches the value queried using 1947 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR. 1948endif::VK_KHR_ray_tracing_maintenance1[] 1949 This will be zero for a bottom-level acceleration structure. 1950 For top-level acceleration structures this number is 1951 implementation-dependent; the number of and ordering of the handles may 1952 not match the instance descriptions which were used to build the 1953 acceleration structure. 1954 1955The corresponding handles matching the values returned by 1956ifdef::VK_KHR_acceleration_structure[flink:vkGetAccelerationStructureDeviceAddressKHR] 1957ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 1958ifdef::VK_NV_ray_tracing[flink:vkGetAccelerationStructureHandleNV] 1959are tightly packed in the buffer following the count. 1960The application is expected to store a mapping between those handles and the 1961original application-generated bottom-level acceleration structures to 1962provide when deserializing. 1963The serialized data is written to the buffer (or read from the buffer) 1964according to the host endianness. 1965 1966.Valid Usage 1967**** 1968 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-accelerationStructure-08926]] 1969 The <<features-accelerationStructure, 1970 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 1971 feature must: be enabled 1972 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03739]] 1973 pname:pInfo->dst.deviceAddress must: be a valid device address for a 1974 buffer bound to device memory 1975 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03740]] 1976 pname:pInfo->dst.deviceAddress must: be aligned to `256` bytes 1977 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-pInfo-03741]] 1978 If the buffer pointed to by pname:pInfo->dst.deviceAddress is non-sparse 1979 then it must: be bound completely and contiguously to a single 1980 slink:VkDeviceMemory object 1981 * [[VUID-vkCmdCopyAccelerationStructureToMemoryKHR-None-03559]] 1982 The pname:buffer used to create pname:pInfo->src must: be bound to 1983 device memory 1984**** 1985 1986include::{generated}/validity/protos/vkCmdCopyAccelerationStructureToMemoryKHR.adoc[] 1987-- 1988 1989[open,refpage='VkCopyAccelerationStructureToMemoryInfoKHR',desc='Parameters for serializing an acceleration structure',type='structs'] 1990-- 1991:refpage: VkCopyAccelerationStructureToMemoryInfoKHR 1992 1993include::{generated}/api/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] 1994 1995 * pname:sType is a elink:VkStructureType value identifying this structure. 1996 * pname:pNext is `NULL` or a pointer to a structure extending this 1997 structure. 1998 * pname:src is the source acceleration structure for the copy 1999 * pname:dst is the device or host address to memory which is the target 2000 for the copy 2001 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 2002 specifying additional operations to perform during the copy. 2003 2004.Valid Usage 2005**** 2006 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-src-04959]] 2007 The source acceleration structure pname:src must: have been constructed 2008 prior to the execution of this command 2009 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-dst-03561]] 2010 The memory pointed to by pname:dst must: be at least as large as the 2011 serialization size of pname:src, as reported by 2012 flink:vkWriteAccelerationStructuresPropertiesKHR or 2013 flink:vkCmdWriteAccelerationStructuresPropertiesKHR with a query type of 2014 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR 2015 * [[VUID-VkCopyAccelerationStructureToMemoryInfoKHR-mode-03412]] 2016 pname:mode must: be 2017 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR 2018**** 2019 2020include::{generated}/validity/structs/VkCopyAccelerationStructureToMemoryInfoKHR.adoc[] 2021-- 2022 2023[open,refpage='vkCmdCopyMemoryToAccelerationStructureKHR',desc='Copy device memory to an acceleration structure',type='protos'] 2024-- 2025:refpage: vkCmdCopyMemoryToAccelerationStructureKHR 2026 2027To copy device memory to an acceleration structure call: 2028 2029include::{generated}/api/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] 2030 2031 * pname:commandBuffer is the command buffer into which the command will be 2032 recorded. 2033 * pname:pInfo is a pointer to a 2034 slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the 2035 copy operation. 2036 2037Accesses to pname:pInfo->dst must: be <<synchronization-dependencies, 2038synchronized>> with the 2039ifdef::VK_KHR_synchronization2[] 2040ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 2041<<synchronization-pipeline-stages, pipeline stage>> or the 2042endif::VK_KHR_synchronization2[] 2043ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 2044<<synchronization-pipeline-stages, pipeline stage>>, and an 2045<<synchronization-access-types, access type>> of 2046ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR. 2047Accesses to the buffer indicated by pname:pInfo->src.deviceAddress must: be 2048synchronized with the 2049ifdef::VK_KHR_synchronization2[] 2050ename:VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR 2051<<synchronization-pipeline-stages, pipeline stage>> or the 2052endif::VK_KHR_synchronization2[] 2053ename:VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR 2054<<synchronization-pipeline-stages, pipeline stage>>, and an access type of 2055ename:VK_ACCESS_TRANSFER_READ_BIT. 2056 2057This command can accept acceleration structures produced by either 2058flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2059flink:vkCopyAccelerationStructureToMemoryKHR. 2060 2061The structure provided as input to deserialize is as described in 2062flink:vkCmdCopyAccelerationStructureToMemoryKHR, with any acceleration 2063structure handles filled in with the newly-queried handles to bottom level 2064acceleration structures created before deserialization. 2065These do not need to be built at deserialize time, but must: be created. 2066 2067.Valid Usage 2068**** 2069 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-accelerationStructure-08927]] 2070 The <<features-accelerationStructure, 2071 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 2072 feature must: be enabled 2073 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03742]] 2074 pname:pInfo->src.deviceAddress must: be a valid device address for a 2075 buffer bound to device memory 2076 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03743]] 2077 pname:pInfo->src.deviceAddress must: be aligned to `256` bytes 2078 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-pInfo-03744]] 2079 If the buffer pointed to by pname:pInfo->src.deviceAddress is non-sparse 2080 then it must: be bound completely and contiguously to a single 2081 slink:VkDeviceMemory object 2082 * [[VUID-vkCmdCopyMemoryToAccelerationStructureKHR-buffer-03745]] 2083 The pname:buffer used to create pname:pInfo->dst must: be bound to 2084 device memory 2085**** 2086 2087include::{generated}/validity/protos/vkCmdCopyMemoryToAccelerationStructureKHR.adoc[] 2088-- 2089 2090[open,refpage='VkCopyMemoryToAccelerationStructureInfoKHR',desc='Parameters for deserializing an acceleration structure',type='structs'] 2091-- 2092:refpage: VkCopyMemoryToAccelerationStructureInfoKHR 2093 2094The sname:VkCopyMemoryToAccelerationStructureInfoKHR structure is defined 2095as: 2096 2097include::{generated}/api/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] 2098 2099 * pname:sType is a elink:VkStructureType value identifying this structure. 2100 * pname:pNext is `NULL` or a pointer to a structure extending this 2101 structure. 2102 * pname:src is the device or host address to memory containing the source 2103 data for the copy. 2104 * pname:dst is the target acceleration structure for the copy. 2105 * pname:mode is a elink:VkCopyAccelerationStructureModeKHR value 2106 specifying additional operations to perform during the copy. 2107 2108.Valid Usage 2109**** 2110 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-src-04960]] 2111 The source memory pointed to by pname:src must: contain data previously 2112 serialized using flink:vkCmdCopyAccelerationStructureToMemoryKHR, 2113 potentially modified to relocate acceleration structure references as 2114 described in that command 2115 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-mode-03413]] 2116 pname:mode must: be 2117 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR 2118 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-pInfo-03414]] 2119 The data in pname:src must: have a format compatible with the 2120 destination physical device as returned by 2121 flink:vkGetDeviceAccelerationStructureCompatibilityKHR 2122 * [[VUID-VkCopyMemoryToAccelerationStructureInfoKHR-dst-03746]] 2123 pname:dst must: have been created with a pname:size greater than or 2124 equal to that used to serialize the data in pname:src 2125**** 2126 2127include::{generated}/validity/structs/VkCopyMemoryToAccelerationStructureInfoKHR.adoc[] 2128-- 2129 2130[open,refpage='vkGetDeviceAccelerationStructureCompatibilityKHR',desc='Check if a serialized acceleration structure is compatible with the current device',type='protos'] 2131-- 2132:refpage: vkGetDeviceAccelerationStructureCompatibilityKHR 2133 2134To check if a serialized acceleration structure is compatible with the 2135current device call: 2136 2137include::{generated}/api/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] 2138 2139 * pname:device is the device to check the version against. 2140 * pname:pVersionInfo is a pointer to a 2141 slink:VkAccelerationStructureVersionInfoKHR structure specifying version 2142 information to check against the device. 2143 * pname:pCompatibility is a pointer to a 2144 elink:VkAccelerationStructureCompatibilityKHR value in which 2145 compatibility information is returned. 2146 2147.Valid Usage 2148**** 2149 * [[VUID-vkGetDeviceAccelerationStructureCompatibilityKHR-accelerationStructure-08928]] 2150 The <<features-accelerationStructure, 2151 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 2152 feature must: be enabled 2153**** 2154 2155include::{generated}/validity/protos/vkGetDeviceAccelerationStructureCompatibilityKHR.adoc[] 2156-- 2157 2158[open,refpage='VkAccelerationStructureVersionInfoKHR',desc='Acceleration structure version information',type='structs'] 2159-- 2160:refpage: VkAccelerationStructureVersionKHR 2161 2162The sname:VkAccelerationStructureVersionInfoKHR structure is defined as: 2163 2164include::{generated}/api/structs/VkAccelerationStructureVersionInfoKHR.adoc[] 2165 2166 * pname:sType is a elink:VkStructureType value identifying this structure. 2167 * pname:pNext is `NULL` or a pointer to a structure extending this 2168 structure. 2169 * pname:pVersionData is a pointer to the version header of an acceleration 2170 structure as defined in flink:vkCmdCopyAccelerationStructureToMemoryKHR 2171 2172[NOTE] 2173.Note 2174==== 2175pname:pVersionData is a _pointer_ to an array of 2{times}ename:VK_UUID_SIZE 2176code:uint8_t values instead of two ename:VK_UUID_SIZE arrays as the expected 2177use case for this member is to be pointed at the header of a previously 2178serialized acceleration structure (via 2179flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2180flink:vkCopyAccelerationStructureToMemoryKHR) that is loaded in memory. 2181Using arrays would necessitate extra memory copies of the UUIDs. 2182==== 2183 2184include::{generated}/validity/structs/VkAccelerationStructureVersionInfoKHR.adoc[] 2185-- 2186 2187[open,refpage='VkAccelerationStructureCompatibilityKHR',desc='Acceleration structure compatibility',type='enums'] 2188-- 2189Possible values of pname:pCompatibility returned by 2190flink:vkGetDeviceAccelerationStructureCompatibilityKHR are: 2191 2192include::{generated}/api/enums/VkAccelerationStructureCompatibilityKHR.adoc[] 2193 2194 * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_COMPATIBLE_KHR if the 2195 pname:pVersionData version acceleration structure is compatible with 2196 pname:device. 2197 * ename:VK_ACCELERATION_STRUCTURE_COMPATIBILITY_INCOMPATIBLE_KHR if the 2198 pname:pVersionData version acceleration structure is not compatible with 2199 pname:device. 2200-- 2201 2202 2203[[host-acceleration-structure]] 2204== Host Acceleration Structure Operations 2205 2206Implementations are also required to provide host implementations of the 2207acceleration structure operations if the 2208<<features-accelerationStructureHostCommands, 2209pname:accelerationStructureHostCommands>> feature is enabled: 2210 2211 * flink:vkBuildAccelerationStructuresKHR corresponding to 2212 flink:vkCmdBuildAccelerationStructuresKHR 2213 * flink:vkCopyAccelerationStructureKHR corresponding to 2214 flink:vkCmdCopyAccelerationStructureKHR 2215 * flink:vkCopyAccelerationStructureToMemoryKHR corresponding to 2216 flink:vkCmdCopyAccelerationStructureToMemoryKHR 2217 * flink:vkCopyMemoryToAccelerationStructureKHR corresponding to 2218 flink:vkCmdCopyMemoryToAccelerationStructureKHR 2219 * flink:vkWriteAccelerationStructuresPropertiesKHR corresponding to 2220 flink:vkCmdWriteAccelerationStructuresPropertiesKHR 2221 2222These commands are functionally equivalent to their device counterparts, 2223except that they are executed on the host timeline, rather than being 2224enqueued into command buffers. 2225 2226All acceleration structures used by the host commands must: be bound to 2227host-visible memory, and all input data for acceleration structure builds 2228must: be referenced using host addresses instead of device addresses. 2229Applications are not required to map acceleration structure memory when 2230using the host commands. 2231 2232 2233[NOTE] 2234.Note 2235==== 2236The flink:vkBuildAccelerationStructuresKHR and 2237flink:vkCmdBuildAccelerationStructuresKHR may: use different algorithms, and 2238thus are not required to produce identical structures. 2239The structures produced by these two commands may: exhibit different memory 2240footprints or traversal performance, but should strive to be similar where 2241possible. 2242 2243Apart from these details, the host and device operations are 2244interchangeable. 2245For example, an application can: use flink:vkBuildAccelerationStructuresKHR 2246to build a structure, compact it on the device using 2247flink:vkCmdCopyAccelerationStructureKHR, and serialize the result using 2248flink:vkCopyAccelerationStructureToMemoryKHR. 2249==== 2250 2251[NOTE] 2252.Note 2253==== 2254For efficient execution, acceleration structures manipulated using these 2255commands should always be bound to host cached memory, as the implementation 2256may need to repeatedly read and write this memory during the execution of 2257the command. 2258==== 2259 2260[open,refpage='vkBuildAccelerationStructuresKHR',desc='Build an acceleration structure on the host',type='protos'] 2261-- 2262:refpage: vkBuildAccelerationStructuresKHR 2263 2264To build acceleration structures on the host, call: 2265 2266include::{generated}/api/protos/vkBuildAccelerationStructuresKHR.adoc[] 2267 2268 * pname:device is the sname:VkDevice for which the acceleration structures 2269 are being built. 2270 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2271 <<deferred-host-operations-requesting, request deferral>> for this 2272 command. 2273 * pname:infoCount is the number of acceleration structures to build. 2274 It specifies the number of the pname:pInfos structures and 2275 pname:ppBuildRangeInfos pointers that must: be provided. 2276 * pname:pInfos is a pointer to an array of pname:infoCount 2277 slink:VkAccelerationStructureBuildGeometryInfoKHR structures defining 2278 the geometry used to build each acceleration structure. 2279 * pname:ppBuildRangeInfos is a pointer to an array of pname:infoCount 2280 pointers to arrays of slink:VkAccelerationStructureBuildRangeInfoKHR 2281 structures. 2282 Each pname:ppBuildRangeInfos[i] is a pointer to an array of 2283 pname:pInfos[i].pname:geometryCount 2284 slink:VkAccelerationStructureBuildRangeInfoKHR structures defining 2285 dynamic offsets to the addresses where geometry data is stored, as 2286 defined by pname:pInfos[i]. 2287 2288This command fulfills the same task as 2289flink:vkCmdBuildAccelerationStructuresKHR but is executed by the host. 2290 2291The fname:vkBuildAccelerationStructuresKHR command provides the ability to 2292initiate multiple acceleration structures builds, however there is no 2293ordering or synchronization implied between any of the individual 2294acceleration structure builds. 2295 2296[NOTE] 2297.Note 2298==== 2299This means that an application cannot: build a top-level acceleration 2300structure in the same flink:vkBuildAccelerationStructuresKHR call as the 2301associated bottom-level or instance acceleration structures are being built. 2302There also cannot: be any memory aliasing between any acceleration structure 2303memories or scratch memories being used by any of the builds. 2304==== 2305 2306.Valid Usage 2307**** 2308 * [[VUID-vkBuildAccelerationStructuresKHR-accelerationStructureHostCommands-03581]] 2309 The <<features-accelerationStructureHostCommands, 2310 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2311 feature must: be enabled 2312 2313:maxinstancecheck: pname:ppBuildRangeInfos[i][j].pname:primitiveCount 2314include::{chapters}/commonvalidity/build_acceleration_structure_common.adoc[] 2315include::{chapters}/commonvalidity/build_acceleration_structure_nonindirect_common.adoc[] 2316include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2317 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03722]] 2318 For each element of pname:pInfos, the pname:buffer used to create its 2319 pname:dstAccelerationStructure member must: be bound to host-visible 2320 device memory 2321 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03723]] 2322 For each element of pname:pInfos, if its pname:mode member is 2323 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer 2324 used to create its pname:srcAccelerationStructure member must: be bound 2325 to host-visible device memory 2326 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03724]] 2327 For each element of pname:pInfos, the pname:buffer used to create each 2328 acceleration structure referenced by the pname:geometry.instances.data 2329 member of any element of pname:pGeometries or pname:ppGeometries with a 2330 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be 2331 bound to host-visible device memory 2332 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03725]] 2333 If pname:pInfos[i].pname:mode is 2334 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR, all addresses 2335 between pname:pInfos[i].pname:scratchData.hostAddress and 2336 pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid 2337 host memory, where N is given by the pname:buildScratchSize member of 2338 the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned 2339 from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an 2340 identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure 2341 and primitive count 2342 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03726]] 2343 If pname:pInfos[i].pname:mode is 2344 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR, all addresses 2345 between pname:pInfos[i].pname:scratchData.hostAddress and 2346 pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid 2347 host memory, where N is given by the pname:updateScratchSize member of 2348 the slink:VkAccelerationStructureBuildSizesInfoKHR structure returned 2349 from a call to flink:vkGetAccelerationStructureBuildSizesKHR with an 2350 identical slink:VkAccelerationStructureBuildGeometryInfoKHR structure 2351 and primitive count 2352 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03771]] 2353 For any element of pname:pInfos[i].pname:pGeometries or 2354 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2355 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, 2356 pname:geometry.triangles.vertexData.hostAddress must: be a valid host 2357 address 2358 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03772]] 2359 For any element of pname:pInfos[i].pname:pGeometries or 2360 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2361 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if 2362 pname:geometry.triangles.indexType is not ename:VK_INDEX_TYPE_NONE_KHR, 2363 pname:geometry.triangles.indexData.hostAddress must: be a valid host 2364 address 2365 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03773]] 2366 For any element of pname:pInfos[i].pname:pGeometries or 2367 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2368 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if 2369 pname:geometry.triangles.transformData.hostAddress is not `0`, it must: 2370 be a valid host address 2371 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03774]] 2372 For any element of pname:pInfos[i].pname:pGeometries or 2373 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2374 ename:VK_GEOMETRY_TYPE_AABBS_KHR, pname:geometry.aabbs.data.hostAddress 2375 must: be a valid host address 2376ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2377 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03775]] 2378 For each element of pname:pInfos, the pname:buffer used to create its 2379 pname:dstAccelerationStructure member must: be bound to memory that was 2380 not allocated with multiple instances 2381 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03776]] 2382 For each element of pname:pInfos, if its pname:mode member is 2383 ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR the pname:buffer 2384 used to create its pname:srcAccelerationStructure member must: be bound 2385 to memory that was not allocated with multiple instances 2386 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03777]] 2387 For each element of pname:pInfos, the pname:buffer used to create each 2388 acceleration structure referenced by the pname:geometry.instances.data 2389 member of any element of pname:pGeometries or pname:ppGeometries with a 2390 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR must: be 2391 bound to memory that was not allocated with multiple instances 2392endif::VK_KHR_device_group,VK_VERSION_1_1[] 2393 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03778]] 2394 For any element of pname:pInfos[i].pname:pGeometries or 2395 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2396 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, 2397 pname:geometry.instances.data.hostAddress must: be a valid host address 2398 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-03779]] 2399 For any element of pname:pInfos[i].pname:pGeometries or 2400 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2401 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each 2402 slink:VkAccelerationStructureInstanceKHR::pname:accelerationStructureReference 2403 value in pname:geometry.instances.data.hostAddress must be a valid 2404 slink:VkAccelerationStructureKHR object 2405ifdef::VK_NV_ray_tracing_motion_blur[] 2406 * [[VUID-vkBuildAccelerationStructuresKHR-pInfos-04930]] 2407 For any element of pname:pInfos[i].pname:pGeometries or 2408 pname:pInfos[i].pname:ppGeometries with a pname:geometryType of 2409 ename:VK_GEOMETRY_TYPE_INSTANCES_KHR with 2410 ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV set, each 2411 pname:accelerationStructureReference in any structure in 2412 slink:VkAccelerationStructureMotionInstanceNV value in 2413 pname:geometry.instances.data.hostAddress must be a valid 2414 slink:VkAccelerationStructureKHR object 2415endif::VK_NV_ray_tracing_motion_blur[] 2416**** 2417 2418include::{generated}/validity/protos/vkBuildAccelerationStructuresKHR.adoc[] 2419-- 2420 2421[open,refpage='vkCopyAccelerationStructureKHR',desc='Copy an acceleration structure on the host',type='protos'] 2422-- 2423:refpage: vkCopyAccelerationStructureKHR 2424 2425To copy or compact an acceleration structure on the host, call: 2426 2427include::{generated}/api/protos/vkCopyAccelerationStructureKHR.adoc[] 2428 2429 * pname:device is the device which owns the acceleration structures. 2430 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2431 <<deferred-host-operations-requesting, request deferral>> for this 2432 command. 2433 * pname:pInfo is a pointer to a slink:VkCopyAccelerationStructureInfoKHR 2434 structure defining the copy operation. 2435 2436This command fulfills the same task as 2437flink:vkCmdCopyAccelerationStructureKHR but is executed by the host. 2438 2439.Valid Usage 2440**** 2441 * [[VUID-vkCopyAccelerationStructureKHR-accelerationStructureHostCommands-03582]] 2442 The <<features-accelerationStructureHostCommands, 2443 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2444include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2445 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03727]] 2446 The pname:buffer used to create pname:pInfo->src must: be bound to 2447 host-visible device memory 2448 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03728]] 2449 The pname:buffer used to create pname:pInfo->dst must: be bound to 2450 host-visible device memory feature must: be enabled 2451ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2452 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03780]] 2453 The pname:buffer used to create pname:pInfo->src must: be bound to 2454 memory that was not allocated with multiple instances 2455 * [[VUID-vkCopyAccelerationStructureKHR-buffer-03781]] 2456 The pname:buffer used to create pname:pInfo->dst must: be bound to 2457 memory that was not allocated with multiple instances 2458endif::VK_KHR_device_group,VK_VERSION_1_1[] 2459**** 2460 2461include::{generated}/validity/protos/vkCopyAccelerationStructureKHR.adoc[] 2462-- 2463 2464[open,refpage='vkCopyMemoryToAccelerationStructureKHR',desc='Deserialize an acceleration structure on the host',type='protos'] 2465-- 2466:refpage: vkCopyMemoryToAccelerationStructureKHR 2467 2468To copy host accessible memory to an acceleration structure, call: 2469 2470include::{generated}/api/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] 2471 2472 * pname:device is the device which owns pname:pInfo->dst. 2473 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2474 <<deferred-host-operations-requesting, request deferral>> for this 2475 command. 2476 * pname:pInfo is a pointer to a 2477 slink:VkCopyMemoryToAccelerationStructureInfoKHR structure defining the 2478 copy operation. 2479 2480This command fulfills the same task as 2481flink:vkCmdCopyMemoryToAccelerationStructureKHR but is executed by the host. 2482 2483This command can accept acceleration structures produced by either 2484flink:vkCmdCopyAccelerationStructureToMemoryKHR or 2485flink:vkCopyAccelerationStructureToMemoryKHR. 2486 2487.Valid Usage 2488**** 2489 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-accelerationStructureHostCommands-03583]] 2490 The <<features-accelerationStructureHostCommands, 2491 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2492 feature must: be enabled 2493include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2494 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03729]] 2495 pname:pInfo->src.hostAddress must: be a valid host pointer 2496 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-pInfo-03750]] 2497 pname:pInfo->src.hostAddress must: be aligned to 16 bytes 2498 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03730]] 2499 The pname:buffer used to create pname:pInfo->dst must: be bound to 2500 host-visible device memory 2501ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2502 * [[VUID-vkCopyMemoryToAccelerationStructureKHR-buffer-03782]] 2503 The pname:buffer used to create pname:pInfo->dst must: be bound to 2504 memory that was not allocated with multiple instances 2505endif::VK_KHR_device_group,VK_VERSION_1_1[] 2506**** 2507 2508include::{generated}/validity/protos/vkCopyMemoryToAccelerationStructureKHR.adoc[] 2509-- 2510 2511[open,refpage='vkCopyAccelerationStructureToMemoryKHR',desc='Serialize an acceleration structure on the host',type='protos'] 2512-- 2513:refpage: vkCopyAccelerationStructureToMemoryKHR 2514 2515To copy an acceleration structure to host accessible memory, call: 2516 2517include::{generated}/api/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] 2518 2519 * pname:device is the device which owns pname:pInfo->src. 2520 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 2521 <<deferred-host-operations-requesting, request deferral>> for this 2522 command. 2523 * pname:pInfo is a pointer to a 2524 slink:VkCopyAccelerationStructureToMemoryInfoKHR structure defining the 2525 copy operation. 2526 2527This command fulfills the same task as 2528flink:vkCmdCopyAccelerationStructureToMemoryKHR but is executed by the host. 2529 2530This command produces the same results as 2531flink:vkCmdCopyAccelerationStructureToMemoryKHR, but writes its result 2532directly to a host pointer, and is executed on the host rather than the 2533device. 2534The output may: not necessarily be bit-for-bit identical, but it can be 2535equally used by either flink:vkCmdCopyMemoryToAccelerationStructureKHR or 2536flink:vkCopyMemoryToAccelerationStructureKHR. 2537 2538.Valid Usage 2539**** 2540 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-accelerationStructureHostCommands-03584]] 2541 The <<features-accelerationStructureHostCommands, 2542 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2543 feature must: be enabled 2544include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 2545 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03731]] 2546 The pname:buffer used to create pname:pInfo->src must: be bound to 2547 host-visible device memory 2548 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03732]] 2549 pname:pInfo->dst.hostAddress must: be a valid host pointer 2550 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-pInfo-03751]] 2551 pname:pInfo->dst.hostAddress must: be aligned to 16 bytes 2552ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2553 * [[VUID-vkCopyAccelerationStructureToMemoryKHR-buffer-03783]] 2554 The pname:buffer used to create pname:pInfo->src must: be bound to 2555 memory that was not allocated with multiple instances 2556endif::VK_KHR_device_group,VK_VERSION_1_1[] 2557**** 2558 2559include::{generated}/validity/protos/vkCopyAccelerationStructureToMemoryKHR.adoc[] 2560-- 2561 2562[open,refpage='vkWriteAccelerationStructuresPropertiesKHR',desc='Query acceleration structure meta-data on the host',type='protos'] 2563-- 2564:refpage: vkWriteAccelerationStructuresPropertiesKHR 2565 2566To query acceleration structure size parameters on the host, call: 2567 2568include::{generated}/api/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] 2569 2570 * pname:device is the device which owns the acceleration structures in 2571 pname:pAccelerationStructures. 2572 * pname:accelerationStructureCount is the count of acceleration structures 2573 for which to query the property. 2574 * pname:pAccelerationStructures is a pointer to an array of existing 2575 previously built acceleration structures. 2576 * pname:queryType is a elink:VkQueryType value specifying the property to 2577 be queried. 2578 * pname:dataSize is the size in bytes of the buffer pointed to by 2579 pname:pData. 2580 * pname:pData is a pointer to a user-allocated buffer where the results 2581 will be written. 2582 * pname:stride is the stride in bytes between results for individual 2583 queries within pname:pData. 2584 2585This command fulfills the same task as 2586flink:vkCmdWriteAccelerationStructuresPropertiesKHR but is executed by the 2587host. 2588 2589.Valid Usage 2590**** 2591 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureHostCommands-03585]] 2592 The <<features-accelerationStructureHostCommands, 2593 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureHostCommands>> 2594 feature must: be enabled 2595include::{chapters}/commonvalidity/write_acceleration_structure_properties_common.adoc[] 2596 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448]] 2597 If pname:queryType is 2598 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then 2599 pname:stride must: be a multiple of the size of basetype:VkDeviceSize 2600 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449]] 2601 If pname:queryType is 2602 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then 2603 pname:pData must: point to a basetype:VkDeviceSize 2604 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450]] 2605 If pname:queryType is 2606 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 2607 pname:stride must: be a multiple of the size of basetype:VkDeviceSize 2608 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451]] 2609 If pname:queryType is 2610 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then 2611 pname:pData must: point to a basetype:VkDeviceSize 2612ifdef::VK_KHR_ray_tracing_maintenance1[] 2613 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06731]] 2614 If pname:queryType is 2615 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:stride 2616 must: be a multiple of the size of basetype:VkDeviceSize 2617 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06732]] 2618 If pname:queryType is 2619 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pname:pData 2620 must: point to a basetype:VkDeviceSize 2621 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06733]] 2622 If pname:queryType is 2623 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, 2624 then pname:stride must: be a multiple of the size of 2625 basetype:VkDeviceSize 2626 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06734]] 2627 If pname:queryType is 2628 ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, 2629 then pname:pData must: point to a basetype:VkDeviceSize 2630endif::VK_KHR_ray_tracing_maintenance1[] 2631 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452]] 2632 pname:dataSize must: be greater than or equal to 2633 [eq]#pname:accelerationStructureCount*pname:stride# 2634 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03733]] 2635 The pname:buffer used to create each acceleration structure in 2636 pname:pAccelerationStructures must: be bound to host-visible device 2637 memory 2638ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 2639 * [[VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03784]] 2640 The pname:buffer used to create each acceleration structure in 2641 pname:pAccelerationStructures must: be bound to memory that was not 2642 allocated with multiple instances 2643endif::VK_KHR_device_group,VK_VERSION_1_1[] 2644**** 2645 2646include::{generated}/validity/protos/vkWriteAccelerationStructuresPropertiesKHR.adoc[] 2647-- 2648
