// Copyright 2017-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_ray_query.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2020-11-12
*Interactions and External Dependencies*::
  - This extension requires
    {spirv}/KHR/SPV_KHR_ray_query.html[`SPV_KHR_ray_query`]
  - This extension provides API support for
    {GLSLregistry}/ext/GLSL_EXT_ray_query.txt[`GLSL_EXT_ray_query`]
*Contributors*::
  - Matthäus Chajdas, AMD
  - Greg Grebe, AMD
  - Nicolai Hähnle, AMD
  - Tobias Hector, AMD
  - Dave Oldcorn, AMD
  - Skyler Saleh, AMD
  - Mathieu Robart, Arm
  - Marius Bjorge, Arm
  - Tom Olson, Arm
  - Sebastian Tafuri, EA
  - Henrik Rydgard, Embark
  - Juan Cañada, Epic Games
  - Patrick Kelly, Epic Games
  - Yuriy O'Donnell, Epic Games
  - Michael Doggett, Facebook/Oculus
  - Andrew Garrard, Imagination
  - Don Scorgie, Imagination
  - Dae Kim, Imagination
  - Joshua Barczak, Intel
  - Slawek Grajewski, Intel
  - Jeff Bolz, NVIDIA
  - Pascal Gautron, NVIDIA
  - Daniel Koch, NVIDIA
  - Christoph Kubisch, NVIDIA
  - Ashwin Lele, NVIDIA
  - Robert Stepinski, NVIDIA
  - Martin Stich, NVIDIA
  - Nuno Subtil, NVIDIA
  - Eric Werness, NVIDIA
  - Jon Leech, Khronos
  - Jeroen van Schijndel, OTOY
  - Juul Joosten, OTOY
  - Alex Bourd, Qualcomm
  - Roman Larionov, Qualcomm
  - David McAllister, Qualcomm
  - Spencer Fricke, Samsung
  - Lewis Gordon, Samsung
  - Ralph Potter, Samsung
  - Jasper Bekkers, Traverse Research
  - Jesse Barker, Unity
  - Baldur Karlsson, Valve

=== Description

Rasterization has been the dominant method to produce interactive graphics,
but increasing performance of graphics hardware has made ray tracing a
viable option for interactive rendering.
Being able to integrate ray tracing with traditional rasterization makes it
easier for applications to incrementally add ray traced effects to existing
applications or to do hybrid approaches with rasterization for primary
visibility and ray tracing for secondary queries.

Ray queries are available to all shader types, including graphics, compute
and ray tracing pipelines.
Ray queries are not able to launch additional shaders, instead returning
traversal results to the calling shader.

This extension adds support for the following SPIR-V extension in Vulkan:

  * `SPV_KHR_ray_query`

include::{generated}/interfaces/VK_KHR_ray_query.adoc[]


=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-RayQueryKHR, code:RayQueryKHR>>
  * <<spirvenv-capabilities-table-RayTraversalPrimitiveCullingKHR,
    code:RayTraversalPrimitiveCullingKHR>>


=== Sample Code

Example of ray query in a GLSL shader, illustrating how to use ray queries
to determine whether a given position (at ray origin) is in shadow or not,
by tracing a ray towards the light, and checking for any intersections with
geometry occluding the light.

[source,c]
----
rayQueryEXT rq;

rayQueryInitializeEXT(rq, accStruct, gl_RayFlagsTerminateOnFirstHitEXT, cullMask, origin, tMin, direction, tMax);

// Traverse the acceleration structure and store information about the first intersection (if any)
rayQueryProceedEXT(rq);

if (rayQueryGetIntersectionTypeEXT(rq, true) == gl_RayQueryCommittedIntersectionNoneEXT) {
    // Not in shadow
}
----

=== Issues

(1) What are the changes between the public provisional (VK_KHR_ray_tracing
v8) release and the final (VK_KHR_acceleration_structure v11 /
VK_KHR_ray_query v1) release?
--
  * refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation
    flexibility and decoupling ray query support from ray pipelines:
  ** `apiext:VK_KHR_acceleration_structure` (for acceleration structure
     operations)
  ** `apiext:VK_KHR_ray_tracing_pipeline` (for ray tracing pipeline and
     shader stages)
  ** `apiext:VK_KHR_ray_query` (for ray queries in existing shader stages)
  * Update SPIRV capabilities to use code:RayQueryKHR
  * extension is no longer provisional
--


=== Version History

  * Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Andrew Garrard)
  ** Decomposition of the specification, from VK_KHR_ray_tracing to
     VK_KHR_ray_query (#1918,!3912)
  ** update to use code:RayQueryKHR SPIR-V capability
  ** add numerical limits for ray parameters (#2235,!3960)
  ** relax formula for ray intersection candidate determination
     (#2322,!4080)
  ** restrict traces to TLAS (#2239,!4141)
  ** require code:HitT to be in ray interval for
     code:OpRayQueryGenerateIntersectionKHR (#2359,!4146)
  ** add ray query shader stages for AS read bit (#2407,!4203)