1// Copyright 2017-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5include::{generated}/meta/{refprefix}VK_KHR_ray_query.adoc[]
6
7=== Other Extension Metadata
8
9*Last Modified Date*::
10    2020-11-12
11*Interactions and External Dependencies*::
12  - This extension requires
13    {spirv}/KHR/SPV_KHR_ray_query.html[`SPV_KHR_ray_query`]
14  - This extension provides API support for
15    {GLSLregistry}/ext/GLSL_EXT_ray_query.txt[`GLSL_EXT_ray_query`]
16*Contributors*::
17  - Matthäus Chajdas, AMD
18  - Greg Grebe, AMD
19  - Nicolai Hähnle, AMD
20  - Tobias Hector, AMD
21  - Dave Oldcorn, AMD
22  - Skyler Saleh, AMD
23  - Mathieu Robart, Arm
24  - Marius Bjorge, Arm
25  - Tom Olson, Arm
26  - Sebastian Tafuri, EA
27  - Henrik Rydgard, Embark
28  - Juan Cañada, Epic Games
29  - Patrick Kelly, Epic Games
30  - Yuriy O'Donnell, Epic Games
31  - Michael Doggett, Facebook/Oculus
32  - Andrew Garrard, Imagination
33  - Don Scorgie, Imagination
34  - Dae Kim, Imagination
35  - Joshua Barczak, Intel
36  - Slawek Grajewski, Intel
37  - Jeff Bolz, NVIDIA
38  - Pascal Gautron, NVIDIA
39  - Daniel Koch, NVIDIA
40  - Christoph Kubisch, NVIDIA
41  - Ashwin Lele, NVIDIA
42  - Robert Stepinski, NVIDIA
43  - Martin Stich, NVIDIA
44  - Nuno Subtil, NVIDIA
45  - Eric Werness, NVIDIA
46  - Jon Leech, Khronos
47  - Jeroen van Schijndel, OTOY
48  - Juul Joosten, OTOY
49  - Alex Bourd, Qualcomm
50  - Roman Larionov, Qualcomm
51  - David McAllister, Qualcomm
52  - Spencer Fricke, Samsung
53  - Lewis Gordon, Samsung
54  - Ralph Potter, Samsung
55  - Jasper Bekkers, Traverse Research
56  - Jesse Barker, Unity
57  - Baldur Karlsson, Valve
58
59=== Description
60
61Rasterization has been the dominant method to produce interactive graphics,
62but increasing performance of graphics hardware has made ray tracing a
63viable option for interactive rendering.
64Being able to integrate ray tracing with traditional rasterization makes it
65easier for applications to incrementally add ray traced effects to existing
66applications or to do hybrid approaches with rasterization for primary
67visibility and ray tracing for secondary queries.
68
69Ray queries are available to all shader types, including graphics, compute
70and ray tracing pipelines.
71Ray queries are not able to launch additional shaders, instead returning
72traversal results to the calling shader.
73
74This extension adds support for the following SPIR-V extension in Vulkan:
75
76  * `SPV_KHR_ray_query`
77
78include::{generated}/interfaces/VK_KHR_ray_query.adoc[]
79
80
81=== New SPIR-V Capabilities
82
83  * <<spirvenv-capabilities-table-RayQueryKHR, code:RayQueryKHR>>
84  * <<spirvenv-capabilities-table-RayTraversalPrimitiveCullingKHR,
85    code:RayTraversalPrimitiveCullingKHR>>
86
87
88=== Sample Code
89
90Example of ray query in a GLSL shader, illustrating how to use ray queries
91to determine whether a given position (at ray origin) is in shadow or not,
92by tracing a ray towards the light, and checking for any intersections with
93geometry occluding the light.
94
95[source,c]
96----
97rayQueryEXT rq;
98
99rayQueryInitializeEXT(rq, accStruct, gl_RayFlagsTerminateOnFirstHitEXT, cullMask, origin, tMin, direction, tMax);
100
101// Traverse the acceleration structure and store information about the first intersection (if any)
102rayQueryProceedEXT(rq);
103
104if (rayQueryGetIntersectionTypeEXT(rq, true) == gl_RayQueryCommittedIntersectionNoneEXT) {
105    // Not in shadow
106}
107----
108
109=== Issues
110
111(1) What are the changes between the public provisional (VK_KHR_ray_tracing
112v8) release and the final (VK_KHR_acceleration_structure v11 /
113VK_KHR_ray_query v1) release?
114--
115  * refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation
116    flexibility and decoupling ray query support from ray pipelines:
117  ** `apiext:VK_KHR_acceleration_structure` (for acceleration structure
118     operations)
119  ** `apiext:VK_KHR_ray_tracing_pipeline` (for ray tracing pipeline and
120     shader stages)
121  ** `apiext:VK_KHR_ray_query` (for ray queries in existing shader stages)
122  * Update SPIRV capabilities to use code:RayQueryKHR
123  * extension is no longer provisional
124--
125
126
127=== Version History
128
129  * Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Andrew Garrard)
130  ** Decomposition of the specification, from VK_KHR_ray_tracing to
131     VK_KHR_ray_query (#1918,!3912)
132  ** update to use code:RayQueryKHR SPIR-V capability
133  ** add numerical limits for ray parameters (#2235,!3960)
134  ** relax formula for ray intersection candidate determination
135     (#2322,!4080)
136  ** restrict traces to TLAS (#2239,!4141)
137  ** require code:HitT to be in ray interval for
138     code:OpRayQueryGenerateIntersectionKHR (#2359,!4146)
139  ** add ray query shader stages for AS read bit (#2407,!4203)
140