1  [[raytracing]]
  2  = Ray Tracing
  3  
  4  Unlike draw commands, which use rasterization, ray tracing is a rendering
  5  method that generates an image by tracing the path of rays which have a
  6  single origin and using shaders to determine the final colour of an image
  7  plane.
  8  
  9  Ray tracing uses a separate rendering pipeline from both the graphics and
 10  compute pipelines (see <<pipelines-raytracing,Ray tracing Pipeline>>).
 11  It has a unique set of programmable and fixed function stages.
 12  
 13  [[fig-raypipe]]
 14  image::{images}/raypipe.svg[align="center",title="Ray tracing Pipeline",opts="{imageopts}"]
 15  
 16  .Caption
 17  ****
 18  Interaction between the different shader stages in the ray tracing pipeline
 19  ****
 20  
 21  
 22  [[raytracing-commands]]
 23  == Ray Tracing Commands
 24  _Ray tracing commands_ provoke work in the ray tracing pipeline.
 25  Ray tracing commands are recorded into a command buffer and when executed by
 26  a queue will produce work that executes according to the currently bound ray
 27  tracing pipeline.
 28  A ray tracing pipeline must: be bound to a command buffer before any ray
 29  tracing commands are recorded in that command buffer.
 30  
 31  Each ray tracing call operates on a set of shader stages that are specific
 32  to the ray tracing pipeline as well as a set of
 33  sname:VkAccelerationStructureNV objects, which describe the scene geometry
 34  in an implementation-specific way.
 35  The relationship between the ray tracing pipeline object and the
 36  acceleration structures is passed into the ray tracing command in a
 37  slink:VkBuffer object known as a _shader binding table_.
 38  
 39  During execution, control alternates between scheduling and other
 40  operations.
 41  The scheduling functionality is implementation-specific and is responsible
 42  for workload execution.
 43  The shader stages are programmable.
 44  _Traversal_, which refers to the process of traversing acceleration
 45  structures to find potential intersections of rays with geometry, is fixed
 46  function.
 47  
 48  The programmable portions of the pipeline are exposed in a single-ray
 49  programming model.
 50  Each GPU thread handles one ray at a time.
 51  Memory operations can: be synchronized using standard memory barriers.
 52  However, communication and synchronization between threads is not allowed.
 53  In particular, the use of compute pipeline synchronization functions is not
 54  supported in the ray tracing pipeline.
 55  
 56  [open,refpage='vkCmdTraceRaysNV',desc='Initialize a ray tracing dispatch',type='protos']
 57  --
 58  :refpage: vkCmdTraceRaysNV
 59  
 60  To dispatch a ray tracing call use:
 61  
 62  include::{generated}/api/protos/vkCmdTraceRaysNV.txt[]
 63  
 64    * pname:commandBuffer is the command buffer into which the command will be
 65      recorded.
 66    * pname:raygenShaderBindingTableBuffer is the buffer object that holds the
 67      shader binding table data for the ray generation shader stage.
 68    * pname:raygenShaderBindingOffset is the offset in bytes (relative to
 69      pname:raygenShaderBindingTableBuffer) of the ray generation shader being
 70      used for the trace.
 71    * pname:missShaderBindingTableBuffer is the buffer object that holds the
 72      shader binding table data for the miss shader stage.
 73    * pname:missShaderBindingOffset is the offset in bytes (relative to
 74      pname:missShaderBindingTableBuffer) of the miss shader being used for
 75      the trace.
 76    * pname:missShaderBindingStride is the size in bytes of each shader
 77      binding table record in pname:missShaderBindingTableBuffer.
 78    * pname:hitShaderBindingTableBuffer is the buffer object that holds the
 79      shader binding table data for the hit shader stages.
 80    * pname:hitShaderBindingOffset is the offset in bytes (relative to
 81      pname:hitShaderBindingTableBuffer) of the hit shader group being used
 82      for the trace.
 83    * pname:hitShaderBindingStride is the size in bytes of each shader binding
 84      table record in pname:hitShaderBindingTableBuffer.
 85    * pname:callableShaderBindingTableBuffer is the buffer object that holds
 86      the shader binding table data for the callable shader stage.
 87    * pname:callableShaderBindingOffset is the offset in bytes (relative to
 88      pname:callableShaderBindingTableBuffer) of the callable shader being
 89      used for the trace.
 90    * pname:callableShaderBindingStride is the size in bytes of each shader
 91      binding table record in pname:callableShaderBindingTableBuffer.
 92    * pname:width is the width of the ray trace query dimensions.
 93    * pname:height is height of the ray trace query dimensions.
 94    * pname:depth is depth of the ray trace query dimensions.
 95  
 96  When the command is executed, a ray generation group of [eq]#pname:width
 97  {times} pname:height {times} pname:depth# rays is assembled.
 98  
 99  .Valid Usage
100  ****
101  include::{chapters}/commonvalidity/draw_dispatch_common.txt[]
102  include::{chapters}/commonvalidity/draw_dispatch_nonindirect_common.txt[]
103    * [[VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02455]]
104      pname:raygenShaderBindingOffset must: be less than the size of
105      pname:raygenShaderBindingTableBuffer
106    * [[VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02456]]
107      pname:raygenShaderBindingOffset must: be a multiple of
108      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment
109    * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02457]]
110      pname:missShaderBindingOffset must: be less than the size of
111      pname:missShaderBindingTableBuffer
112    * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02458]]
113      pname:missShaderBindingOffset must: be a multiple of
114      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment
115    * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02459]]
116      pname:hitShaderBindingOffset must: be less than the size of
117      pname:hitShaderBindingTableBuffer
118    * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02460]]
119      pname:hitShaderBindingOffset must: be a multiple of
120      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment
121    * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02461]]
122      pname:callableShaderBindingOffset must: be less than the size of
123      pname:callableShaderBindingTableBuffer
124    * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02462]]
125      pname:callableShaderBindingOffset must: be a multiple of
126      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment
127    * [[VUID-vkCmdTraceRaysNV-missShaderBindingStride-02463]]
128      pname:missShaderBindingStride must: be a multiple of
129      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize
130    * [[VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02464]]
131      pname:hitShaderBindingStride must: be a multiple of
132      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize
133    * [[VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02465]]
134      pname:callableShaderBindingStride must: be a multiple of
135      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize
136    * [[VUID-vkCmdTraceRaysNV-missShaderBindingStride-02466]]
137      pname:missShaderBindingStride must: be a less than or equal to
138      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride
139    * [[VUID-vkCmdTraceRaysNV-hitShaderBindingStride-02467]]
140      pname:hitShaderBindingStride must: be a less than or equal to
141      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride
142    * [[VUID-vkCmdTraceRaysNV-callableShaderBindingStride-02468]]
143      pname:callableShaderBindingStride must: be a less than or equal to
144      sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxShaderGroupStride
145    * [[VUID-vkCmdTraceRaysNV-width-02469]]
146      pname:width must: be less than or equal to
147      sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[0]
148    * [[VUID-vkCmdTraceRaysNV-height-02470]]
149      pname:height must: be less than or equal to
150      sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[1]
151    * [[VUID-vkCmdTraceRaysNV-depth-02471]]
152      pname:depth must: be less than or equal to
153      sname:VkPhysicalDeviceLimits::pname:maxComputeWorkGroupCount[2]
154  ****
155  
156  include::{generated}/validity/protos/vkCmdTraceRaysNV.txt[]
157  --
158  
159  
160  [[shader-binding-table]]
161  == Shader Binding Table
162  
163  A _shader binding table_ is a resource which establishes the relationship
164  between the ray tracing pipeline and the acceleration structures that were
165  built for the ray tracing query.
166  It indicates the shaders that operate on each geometry in an acceleration
167  structure.
168  In addition, it contains the resources accessed by each shader, including
169  indices of textures and constants.
170  The application allocates and manages _shader binding tables_ as
171  slink:VkBuffer objects.
172  
173  Each entry in the shader binding table consists of
174  pname:shaderGroupHandleSize bytes of data as queried by
175  flink:vkGetRayTracingShaderGroupHandlesNV to refer to the shader that it
176  invokes.
177  The remainder of the data specified by the stride is application-visible
178  data that can be referenced by a code:shaderRecordNV block in the shader.
179  
180  The shader binding tables to use in a ray tracing query are passed to
181  flink:vkCmdTraceRaysNV.
182  Shader binding tables are read-only in shaders that are executing on the ray
183  tracing pipeline.
184  
185  
186  [[shader-binding-table-indexing-rules]]
187  === Indexing Rules
188  
189  In order to execute the correct shaders and access the correct resources
190  during a ray tracing dispatch, the implementation must: be able to locate
191  shader binding table entries at various stages of execution.
192  This is accomplished by defining a set of indexing rules that compute shader
193  binding table record positions relative to the buffer's base address in
194  memory.
195  The application must: organize the contents of the shader binding table's
196  memory in a way that application of the indexing rules will lead to correct
197  records.
198  
199  
200  ==== Ray Generation Shaders
201  
202  Only one ray generation shader is executed per ray tracing dispatch.
203  Its location is passed into flink:vkCmdTraceRaysNV using the
204  pname:raygenShaderBindingTableBuffer and
205  pname:raygenShaderBindingTableOffset parameters -- there is no indexing.
206  
207  
208  ==== Hit Shaders
209  
210  The base for the computation of intersection, any-hit and closest hit shader
211  locations is the code:instanceShaderBindingTableRecordOffset value stored
212  with each instance of a top-level acceleration structure.
213  This value determines the beginning of the shader binding table records for
214  a given instance.
215  Each geometry in the instance must: have at least one hit program record.
216  
217  In the following rule, _geometryIndex_ refers to the location of the
218  geometry within the instance.
219  
220  The code:sbtRecordStride and code:sbtRecordOffset values are passed in as
221  parameters to code:traceNV() calls made in the shaders.
222  See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
223  Specification for more details.
224  In SPIR-V, these correspond to the code:SBTOffset and code:SBTStride
225  parameters to the code:OpTraceNV instruction.
226  
227  The result of this computation is then added to
228  pname:hitShaderBindingOffset, a base offset passed to
229  flink:vkCmdTraceRaysNV.
230  
231  The complete rule to compute a hit shader binding table record address in
232  the pname:hitShaderBindingTableBuffer is:
233  
234   :: [eq]#pname:hitShaderBindingOffset {plus} pname:hitShaderBindingStride
235       {times} ( code:instanceShaderBindingTableRecordOffset {plus}
236       _geometryIndex_ {times} code:sbtRecordStride {plus}
237       code:sbtRecordOffset )#
238  
239  
240  ==== Miss Shaders
241  
242  A miss shader is executed whenever a ray query fails to find an intersection
243  for the given scene geometry.
244  Multiple miss shaders may: be executed throughout a ray tracing dispatch.
245  
246  The base for the computation of miss shader locations is
247  pname:missShaderBindingOffset, a base offset passed into
248  flink:vkCmdTraceRaysNV.
249  
250  The code:missIndex value is passed in as parameters to code:traceNV() calls
251  made in the shaders.
252  See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
253  Specification for more details.
254  In SPIR-V, this corresponds to the code:MissIndex parameter to the
255  code:OpTraceNV instruction.
256  
257  The complete rule to compute a miss shader binding table record address in
258  the pname:missShaderBindingTableBuffer is:
259  
260   :: [eq]#pname:missShaderBindingOffset {plus} pname:missShaderBindingStride
261        {times} code:missIndex#
262  
263  
264  ==== Callable Shaders
265  
266  A callable shader is executed when requested by a ray tracing shader.
267  Multiple callable shaders may: be executed throughout a ray tracing
268  dispatch.
269  
270  The base for the computation of callable shader locations is
271  code:callableShaderBindingOffset, a base offset passed into
272  flink:vkCmdTraceRaysNV.
273  
274  The code:sbtRecordIndex value is passed in as a parameter to
275  code:executeCallableNV() calls made in the shaders.
276  See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language
277  Specification for more details.
278  In SPIR-V, this corresponds to the code:SBTIndex parameter to the
279  code:OpExecuteCallableNV instruction.
280  
281  The complete rule to compute a callable shader binding table record address
282  in the pname:callableShaderBindingTableBuffer is:
283  
284   :: [eq]#code:callableShaderBindingOffset {plus}
285        pname:callableShaderBindingStride {times} code:sbtRecordIndex#
286  
287  
288  [[acceleration-structure]]
289  == Acceleration Structures
290  
291  _Acceleration structures_ are data structures used by the implementation to
292  efficiently manage the scene geometry as it is traversed during a ray
293  tracing query.
294  The application is responsible for managing acceleration structure objects
295  (see <<resources-acceleration-structures,Acceleration Structures>>,
296  including allocation, destruction, executing builds or updates, and
297  synchronizing resources used during ray tracing queries.
298  
299  There are two types of acceleration structures, _top level acceleration
300  structures_ and _bottom level acceleration structures_.
301  
302  [[fig-accelstruct]]
303  image::{images}/accelstruct.svg[align="center",title="Acceleration Structure",opts="{imageopts}"]
304  
305  .Caption
306  ****
307  The diagram shows the relationship between top and bottom level acceleration
308  structures.
309  ****
310  
311  
312  [[acceleration-structure-instance]]
313  === Instances
314  
315  _Instances_ are found in top level acceleration structures and contain data
316  that refer to a single bottom-level acceleration structure, a transform
317  matrix, and shading information.
318  Multiple instances can: point to a single bottom level acceleration
319  structure.
320  
321  An instance is defined in a slink:VkBuffer by a structure consisting of 64
322  bytes of data.
323  
324    * pname:transform is 12 floats representing a 4x3 transform matrix in
325      row-major order
326    * pname:instanceCustomIndex The low 24 bits of a 32-bit integer after the
327      transform.
328      This value appears in the builtin code:gl_InstanceCustomIndexNV
329    * pname:mask The high 8 bits of the same integer as
330      pname:instanceCustomIndex.
331      This is the visibility mask.
332      The instance may: only be hit if `rayMask & instance.mask != 0`
333    * pname:instanceOffset The low 24 bits of the next 32-bit integer.
334      The value contributed by this instance to the hit shader binding table
335      index computation as code:instanceShaderBindingTableRecordOffset.
336    * pname:flags The high 8 bits of the same integer as pname:instanceOffset.
337      elink:VkGeometryInstanceFlagBitsNV values that apply to this instance.
338    * pname:accelerationStructure.
339      The 8 byte value returned by flink:vkGetAccelerationStructureHandleNV
340      for the bottom level acceleration structure referred to by this
341      instance.
342  
343  [NOTE]
344  .Note
345  ====
346  The C language spec does not define the ordering of bit-fields, but in
347  practice, this struct produces the layout described above:
348  
349  [source,c]
350  ---------------------------------------------------
351  struct VkGeometryInstanceNV {
352      float          transform[12];
353      uint32_t       instanceCustomIndex : 24;
354      uint32_t       mask : 8;
355      uint32_t       instanceOffset : 24;
356      uint32_t       flags : 8;
357      uint64_t       accelerationStructureHandle;
358  };
359  ---------------------------------------------------
360  
361  ====
362  
363  [open,refpage='VkGeometryInstanceFlagBitsNV',desc='Instance flag bits',type='enums']
364  --
365  
366  Possible values of pname:flags in the instance modifying the behavior of
367  that instance are:,
368  
369  include::{generated}/api/enums/VkGeometryInstanceFlagBitsNV.txt[]
370  
371    * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV disables face
372      culling for this instance.
373    * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV
374      indicates that the front face of the triangle for culling purposes is
375      the face that is counter clockwise in object space relative to the ray
376      origin.
377      Because the facing is determined in object space, an instance transform
378      matrix does not change the winding, but a geometry transform does.
379    * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV causes this instance to
380      act as though ename:VK_GEOMETRY_OPAQUE_BIT_NV were specified on all
381      geometries referenced by this instance.
382      This behavior can: be overridden by the ray flag
383      code:gl_RayFlagsNoOpaqueNV.
384    * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV causes this instance
385      to act as though ename:VK_GEOMETRY_OPAQUE_BIT_NV were not specified on
386      all geometries referenced by this instance.
387      This behavior can: be overridden by the ray flag
388      code:gl_RayFlagsOpaqueNV.
389  
390  ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV and
391  ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV must: not be used in the same
392  flag.
393  
394  --
395  
396  [open,refpage='VkGeometryInstanceFlagsNV',desc='Bitmask of VkGeometryInstanceFlagBitsNV',type='flags']
397  --
398  include::{generated}/api/flags/VkGeometryInstanceFlagsNV.txt[]
399  
400  tname:VkGeometryInstanceFlagsNV is a bitmask type for setting a mask of zero
401  or more elink:VkGeometryInstanceFlagBitsNV.
402  --
403  
404  
405  [[acceleration-structure-geometry]]
406  === Geometry
407  
408  _Geometries_ refer to a triangle or axis-aligned bounding box.
409  
410  
411  [[acceleration-structure-top-level]]
412  === Top Level Acceleration Structures
413  
414  Opaque acceleration structure for an array of instances.
415  The descriptor referencing this is the starting point for tracing
416  
417  
418  [[acceleration-structure-bottom-level]]
419  === Bottom Level Acceleration Structures
420  
421  Opaque acceleration structure for an array of geometries.
422  
423  
424  [[acceleration-structure-building]]
425  === Building Acceleration Structures
426  
427  [open,refpage='vkCmdBuildAccelerationStructureNV',desc='Build an acceleration structure',type='protos']
428  --
429  
430  To build an acceleration structure call:
431  
432  include::{generated}/api/protos/vkCmdBuildAccelerationStructureNV.txt[]
433  
434    * pname:commandBuffer is the command buffer into which the command will be
435      recorded.
436    * pname:pInfo contains the shared information for the acceleration
437      structure's structure.
438    * pname:instanceData is the buffer containing instance data that will be
439      used to build the acceleration structure as described in
440      <<acceleration-structure-instance, Accelerator structure instances.>>
441      This parameter must: be `NULL` for bottom level acceleration structures.
442    * pname:instanceOffset is the offset in bytes (relative to the start of
443      pname:instanceData) at which the instance data is located.
444    * pname:update specifies whether to update the pname:dst acceleration
445      structure with the data in pname:src.
446    * pname:dst points to the target acceleration structure for the build.
447    * pname:src points to an existing acceleration structure that is to be
448      used to update the pname:dst acceleration structure.
449    * pname:scratch is the slink:VkBuffer that will be used as scratch memory
450      for the build.
451    * pname:scratchOffset is the offset in bytes relative to the start of
452      pname:scratch that will be used as a scratch memory.
453  
454  .Valid Usage
455  ****
456    * [[VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241]]
457      pname:geometryCount must: be less than or equal to
458      slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount
459    * [[VUID-vkCmdBuildAccelerationStructureNV-dst-02488]]
460      pname:dst must: have been created with compatible
461      slink:VkAccelerationStructureInfoNV where
462      slink:VkAccelerationStructureInfoNV::pname:type and
463      slink:VkAccelerationStructureInfoNV::pname:flags are identical,
464      slink:VkAccelerationStructureInfoNV::pname:instanceCount and
465      slink:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst
466      are greater than or equal to the build size and each geometry in
467      slink:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has
468      greater than or equal to the number of vertices, indices, and AABBs.
469    * [[VUID-vkCmdBuildAccelerationStructureNV-update-02489]]
470      If pname:update is ename:VK_TRUE, pname:src must: not be
471      dlink:VK_NULL_HANDLE
472    * [[VUID-vkCmdBuildAccelerationStructureNV-update-02490]]
473      If pname:update is ename:VK_TRUE, pname:src must: have been built before
474      with ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in
475      slink:VkAccelerationStructureInfoNV::pname:flags
476    * [[VUID-vkCmdBuildAccelerationStructureNV-update-02491]]
477      If pname:update is ename:VK_FALSE, The pname:size member of the
478      slink:VkMemoryRequirements structure returned from a call to
479      flink:vkGetAccelerationStructureMemoryRequirementsNV with
480      slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure
481      set to pname:dst and
482      slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to
483      ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV
484      must: be less than or equal to the size of pname:scratch minus
485      pname:scratchOffset
486    * [[VUID-vkCmdBuildAccelerationStructureNV-update-02492]]
487      If pname:update is ename:VK_TRUE, The pname:size member of the
488      slink:VkMemoryRequirements structure returned from a call to
489      flink:vkGetAccelerationStructureMemoryRequirementsNV with
490      slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure
491      set to pname:dst and
492      slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to
493      ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV
494      must: be less than or equal to the size of pname:scratch minus
495      pname:scratchOffset
496  ****
497  
498  include::{generated}/validity/protos/vkCmdBuildAccelerationStructureNV.txt[]
499  --
500  
501  
502  [[acceleration-structure-copying]]
503  === Copying Acceleration Structures
504  
505  An additional command exists for copying acceleration structures without
506  updating their contents.
507  The acceleration structure object can: be compacted in order to improve
508  performance.
509  Before copying, an application must: query the size of the resulting
510  acceleration structure.
511  
512  [open,refpage='vkCmdWriteAccelerationStructuresPropertiesNV',desc='Write acceleration structure result parameters to query results.',type='protos']
513  --
514  
515  
516  To query acceleration structure size parameters call:
517  
518  include::{generated}/api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.txt[]
519  
520    * pname:commandBuffer is the command buffer into which the command will be
521      recorded.
522    * pname:accelerationStructureCount is the count of acceleration structures
523      for which to query the property.
524    * pname:pAccelerationStructures points to an array of existing previously
525      built acceleration structures.
526    * pname:queryType is a elink:VkQueryType value specifying the type of
527      queries managed by the pool.
528    * pname:queryPool is the query pool that will manage the results of the
529      query.
530    * pname:firstQuery is the first query index within the query pool that
531      will contain the pname:accelerationStructureCount number of results.
532  
533  .Valid Usage
534  ****
535    * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryType-02242]]
536      pname:queryType must: be
537      ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV
538    * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-02493]]
539      pname:queryPool must: have been created with a pname:queryType matching
540      pname:queryType
541    * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-queryPool-02494]]
542      The queries identified by pname:queryPool and pname:firstQuery must: be
543      _unavailable_
544    * [[VUID-vkCmdWriteAccelerationStructuresPropertiesNV-accelerationStructures-02495]]
545      All acceleration structures in pname:accelerationStructures must: have
546      been built with
547      ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV if
548      pname:queryType is
549      ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV
550  ****
551  
552  include::{generated}/validity/protos/vkCmdWriteAccelerationStructuresPropertiesNV.txt[]
553  
554  --
555  
556  
557  [open,refpage='vkCmdCopyAccelerationStructureNV',desc='Copy an acceleration structure',type='protos']
558  --
559  
560  To copy an acceleration structure call:
561  
562  include::{generated}/api/protos/vkCmdCopyAccelerationStructureNV.txt[]
563  
564    * pname:commandBuffer is the command buffer into which the command will be
565      recorded.
566    * pname:dst points to the target acceleration structure for the copy.
567    * pname:src points to the source acceleration structure for the copy.
568    * pname:mode is a elink:VkCopyAccelerationStructureModeNV value that
569      specifies additional operations to perform during the copy.
570  
571  .Valid Usage
572  ****
573    * [[VUID-vkCmdCopyAccelerationStructureNV-mode-02496]]
574      pname:mode must: be ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV
575      or ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV
576    * [[VUID-vkCmdCopyAccelerationStructureNV-src-02497]]
577      pname:src must: have been built with
578      ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV if
579      pname:mode is ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV
580  ****
581  
582  include::{generated}/validity/protos/vkCmdCopyAccelerationStructureNV.txt[]
583  
584  --
585  
586  [open,refpage='VkCopyAccelerationStructureModeNV',desc='Acceleration structure copy mode',type='enums']
587  --
588  
589  Possible values of flink:vkCmdCopyAccelerationStructureNV::pname:mode,
590  specifying additional operations to perform during the copy, are:
591  
592  include::{generated}/api/enums/VkCopyAccelerationStructureModeNV.txt[]
593  
594    * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV creates a direct copy
595      of the acceleration structure specified in pname:src into the one
596      specified by pname:dst.
597      The pname:dst acceleration structure must: have been created with the
598      same parameters as pname:src.
599    * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV creates a more
600      compact version of an acceleration structure pname:src into pname:dst.
601      The acceleration structure pname:dst must: have been created with a
602      pname:compactedSize corresponding to the one returned by
603      flink:vkCmdWriteAccelerationStructuresPropertiesNV after the build of
604      the acceleration structure specified by pname:src.
605  
606  --