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

include::{generated}/meta/{refprefix}VK_KHR_ray_tracing_pipeline.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2020-11-12
*Interactions and External Dependencies*::
  - This extension requires
    https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/KHR/SPV_KHR_ray_tracing.html[`SPV_KHR_ray_tracing`]
  - This extension provides API support for
    https://github.com/KhronosGroup/GLSL/blob/master/extensions/ext/GLSL_EXT_ray_tracing.txt[`GLSL_EXT_ray_tracing`]
  - This extension interacts with <<versions-1.2, Vulkan 1.2>> and
    `apiext:VK_KHR_vulkan_memory_model`, adding the <<shader-call-related,
    shader-call-related>> relation of invocations, <<shader-call-order,
    shader-call-order>> partial order of dynamic instances of instructions,
    and the <<shaders-scope-shadercall, code:ShaderCallKHR>> scope.
  - This extension interacts with `apiext:VK_KHR_pipeline_library`, enabling
    pipeline libraries to be used with ray tracing pipelines and enabling
    usage of slink:VkRayTracingPipelineInterfaceCreateInfoKHR.
*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.

To enable ray tracing, this extension adds a few different categories of new
functionality:

  * A new ray tracing pipeline type with new shader domains: ray generation,
    intersection, any-hit, closest hit, miss, and callable
  * A shader binding indirection table to link shader groups with
    acceleration structure items
  * Ray tracing commands which initiate the ray pipeline traversal and
    invocation of the various new shader domains depending on which
    traversal conditions are met

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

  * `SPV_KHR_ray_tracing`

include::{generated}/interfaces/VK_KHR_ray_tracing_pipeline.txt[]

=== New or Modified Built-In Variables

  * <<interfaces-builtin-variables-launchid,code:LaunchIdKHR>>
  * <<interfaces-builtin-variables-launchsize,code:LaunchSizeKHR>>
  * <<interfaces-builtin-variables-worldrayorigin,code:WorldRayOriginKHR>>
  * <<interfaces-builtin-variables-worldraydirection,code:WorldRayDirectionKHR>>
  * <<interfaces-builtin-variables-objectrayorigin,code:ObjectRayOriginKHR>>
  * <<interfaces-builtin-variables-objectraydirection,code:ObjectRayDirectionKHR>>
  * <<interfaces-builtin-variables-raytmin,code:RayTminKHR>>
  * <<interfaces-builtin-variables-raytmax,code:RayTmaxKHR>>
  * <<interfaces-builtin-variables-instancecustomindex,code:InstanceCustomIndexKHR>>
  * <<interfaces-builtin-variables-instanceid,code:InstanceId>>
  * <<interfaces-builtin-variables-objecttoworld,code:ObjectToWorldKHR>>
  * <<interfaces-builtin-variables-worldtoobject,code:WorldToObjectKHR>>
  * <<interfaces-builtin-variables-hitkind,code:HitKindKHR>>
  * <<interfaces-builtin-variables-incomingrayflags,code:IncomingRayFlagsKHR>>
  * <<interfaces-builtin-variables-raygeometryindex,code:RayGeometryIndexKHR>>
  * (modified)code:PrimitiveId

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-RayTracingKHR,RayTracingKHR>>
  * <<spirvenv-capabilities-table-RayTraversalPrimitiveCullingKHR,RayTraversalPrimitiveCullingKHR>>

=== Issues

(1) How does this extension differ from VK_NV_ray_tracing?
--
*DISCUSSION*:

The following is a summary of the main functional differences between
VK_KHR_ray_tracing_pipeline and VK_NV_ray_tracing:

  * added support for indirect ray tracing (flink:vkCmdTraceRaysIndirectKHR)
  * uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing
  ** refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are
     functionally equivalent and aliased to the same values).
  ** added code:RayGeometryIndexKHR built-in
  * removed vkCompileDeferredNV compilation functionality and replaced with
    <<deferred-host-operations, deferred host operations>> interactions for
    ray tracing
  * added slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure
  * extended slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure
  ** renamed pname:maxRecursionDepth to pname:maxRayRecursionDepth and it
     has a minimum of 1 instead of 31
  ** require pname:shaderGroupHandleSize to be 32 bytes
  ** added pname:maxRayDispatchInvocationCount,
     pname:shaderGroupHandleAlignment and pname:maxRayHitAttributeSize
  * reworked geometry structures so they could be better shared between
    device, host, and indirect builds
  * changed SBT parameters to a structure and added size
    (slink:VkStridedDeviceAddressRegionKHR)
  * add parameter for requesting memory requirements for host and/or device
    build
  * added <<pipeline-library,pipeline library>> support for ray tracing
  * added <<ray-traversal-watertight, watertightness guarantees>>
  * added no-null-shader pipeline flags
    (etext:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR)
  * added <<ray-tracing-shader-call,memory model interactions>> with ray
    tracing and define how subgroups work and can be repacked
--

ifdef::VK_NV_ray_tracing[]
(2) Can you give a more detailed comparision of differences and similarities
between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline?
--
*DISCUSSION*:

The following is a more detailed comparision of which commands, structures,
and enums are aliased, changed, or removed.

  * Aliased functionality -- enums, structures, and commands that are
    considered equivalent:
  ** elink:VkRayTracingShaderGroupTypeNV {harr}
     elink:VkRayTracingShaderGroupTypeKHR
  ** flink:vkGetRayTracingShaderGroupHandlesNV {harr}
     flink:vkGetRayTracingShaderGroupHandlesKHR

  * Changed enums, structures, and commands:
  ** slink:VkRayTracingShaderGroupCreateInfoNV ->
     slink:VkRayTracingShaderGroupCreateInfoKHR (added
     pname:pShaderGroupCaptureReplayHandle)
  ** slink:VkRayTracingPipelineCreateInfoNV ->
     slink:VkRayTracingPipelineCreateInfoKHR (changed type of pname:pGroups,
     added pname:libraries, pname:pLibraryInterface, and
     pname:pDynamicState)
  ** slink:VkPhysicalDeviceRayTracingPropertiesNV ->
     VkPhysicalDeviceRayTracingPropertiesKHR (renamed pname:maxTriangleCount
     to pname:maxPrimitiveCount, added
     pname:shaderGroupHandleCaptureReplaySize)
  ** flink:vkCmdTraceRaysNV -> flink:vkCmdTraceRaysKHR (params to struct)
  ** flink:vkCreateRayTracingPipelinesNV ->
     flink:vkCreateRayTracingPipelinesKHR (different struct, changed
     functionality)

  * Added enums, structures and commands:
  ** ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
     ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR,
     ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR,
     ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR,
     ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR,
     ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR to
     elink:VkPipelineCreateFlagBits
  ** slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure
  ** slink:VkDeviceOrHostAddressKHR and slink:VkDeviceOrHostAddressConstKHR
     unions
  ** slink:VkPipelineLibraryCreateInfoKHR struct
  ** slink:VkRayTracingPipelineInterfaceCreateInfoKHR struct
  ** slink:VkStridedDeviceAddressRegionKHR struct
  ** flink:vkCmdTraceRaysIndirectKHR command and
     slink:VkTraceRaysIndirectCommandKHR struct
  ** flink:vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group
     capture/replay)
  ** flink:vkCmdSetRayTracingPipelineStackSizeKHR and
     flink:vkGetRayTracingShaderGroupStackSizeKHR commands for stack size
     control

  * Functionality removed:
  ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV
  ** flink:vkCompileDeferredNV command (replaced with
     `apiext:VK_KHR_deferred_host_operations`)
--
endif::VK_NV_ray_tracing[]

(3) What are the changes between the public provisional (VK_KHR_ray_tracing
v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?
--
  * Require Vulkan 1.1 and SPIR-V 1.4
  * Added interactions with Vulkan 1.2 and
    `apiext:VK_KHR_vulkan_memory_model`
  * added creation time capture and replay flags
  ** added
     ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
     to elink:VkPipelineCreateFlagBits
  * replace stext:VkStridedBufferRegionKHR with
    slink:VkStridedDeviceAddressRegionKHR and change
    flink:vkCmdTraceRaysKHR, flink:vkCmdTraceRaysIndirectKHR, to take these
    for the shader binding table and use device addresses instead of
    buffers.
  * require the shader binding table buffers to have the
    etext:VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR set
  * make `apiext:VK_KHR_pipeline_library` an interaction instead of required
    extension
  * rename the pname:libraries member of
    slink:VkRayTracingPipelineCreateInfoKHR to pname:pLibraryInfo and make
    it a pointer
  * make `apiext:VK_KHR_deferred_host_operations` an interaction instead of
    a required extension (later went back on this)
  * added explicit stack size management for ray tracing pipelines
  ** removed the pname:maxCallableSize member of
     slink:VkRayTracingPipelineInterfaceCreateInfoKHR
  ** added the pname:pDynamicState member to
     slink:VkRayTracingPipelineCreateInfoKHR
  ** added ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR
     dynamic state for ray tracing pipelines
  ** added flink:vkGetRayTracingShaderGroupStackSizeKHR and
     flink:vkCmdSetRayTracingPipelineStackSizeKHR commands
  ** added elink:VkShaderGroupShaderKHR enum
  * Added pname:maxRayDispatchInvocationCount limit to
    slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR
  * Added pname:shaderGroupHandleAlignment property to
    slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR
  * Added pname:maxRayHitAttributeSize property to
    slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR
  * Clarify deferred host ops for pipeline creation
  ** slink:VkDeferredOperationKHR is now a top-level parameter for
     flink:vkCreateRayTracingPipelinesKHR
  ** removed stext:VkDeferredOperationInfoKHR structure
  ** change deferred host creation/return parameter behavior such that the
     implementation can modify such parameters until the deferred host
     operation completes
  ** `apiext:VK_KHR_deferred_host_operations` is required again
--

(4) What are the changes between the internal provisional
(VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure
v11 / VK_KHR_ray_tracing_pipeline 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)
  * Require code:Volatile for the following builtins in the ray generation,
    closest hit, miss, intersection, and callable shader stages:
  ** code:SubgroupSize, code:SubgroupLocalInvocationId, code:SubgroupEqMask,
     code:SubgroupGeMask, code:SubgroupGtMask, code:SubgroupLeMask,
     code:SubgroupLtMask
  ** code:SMIDNV, code:WarpIDNV
  * clarify buffer usage flags for ray tracing
  ** ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR is added as an alias
     of ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV and is required on shader
     binding table buffers
  ** ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT is used in
     `apiext:VK_KHR_acceleration_structure` for pname:scratchData
  * rename pname:maxRecursionDepth to pname:maxRayPipelineRecursionDepth
    (pipeline creation) and pname:maxRayRecursionDepth (limit) to reduce
    confusion
  * Add queryable pname:maxRayHitAttributeSize limit and rename members of
    slink:VkRayTracingPipelineInterfaceCreateInfoKHR to
    pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize
    for clarity
  * Update SPIRV capabilities to use code:RayTracingKHR
  * extension is no longer provisional
  * define synchronization requirements for indirect trace rays and indirect
    buffer
--

(5) This extension adds gl_InstanceID for the intersection, any-hit, and
    closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced
    with gl_InstanceIndex.
    Which should be used for Vulkan in this extension?
--
*RESOLVED*: This extension uses gl_InstanceID and maps it to code:InstanceId
in SPIR-V.
It is acknowledged that this is different than other shader stages in
Vulkan.
There are two main reasons for the difference here:

  * symmetry with gl_PrimitiveID which is also available in these shaders
  * there is no "`baseInstance`" relevant for these shaders, and so ID makes
    it more obvious that this is zero-based.
--

=== Sample Code

Example ray generation GLSL shader

[source,c]
---------------------------------------------------
#version 450 core
#extension GL_EXT_ray_tracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureEXT as;
layout(location = 0) rayPayloadEXT float payload;

void main()
{
   vec4 col = vec4(0, 0, 0, 1);

   vec3 origin = vec3(float(gl_LaunchIDEXT.x)/float(gl_LaunchSizeEXT.x), float(gl_LaunchIDEXT.y)/float(gl_LaunchSizeEXT.y), 1.0);
   vec3 dir = vec3(0.0, 0.0, -1.0);

   traceRayEXT(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);

   col.y = payload;

   imageStore(image, ivec2(gl_LaunchIDEXT.xy), col);
}
---------------------------------------------------

=== Version History

  * Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness,
    Tobias Hector)
    - Decomposition of the specification, from VK_KHR_ray_tracing to
      VK_KHR_ray_tracing_pipeline (#1918,!3912)
    - require certain subgroup and sm_shader_builtin shader builtins to be
      decorated as volatile in the ray generation, closest hit, miss,
      intersection, and callable stages (#1924,!3903,!3954)
    - clarify buffer usage flags for ray tracing (#2181,!3939)
    - rename maxRecursionDepth to maxRayPipelineRecursionDepth and
      maxRayRecursionDepth (#2203,!3937)
    - add queriable maxRayHitAttributeSize and rename members of
      VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966)
    - update to use code:RayTracingKHR SPIR-V capability
    - add VUs for matching hit group type against geometry type
      (#2245,!3994)
    - require code:RayTMaxKHR be volatile in intersection shaders
      (#2268,!4030)
    - add numerical limits for ray parameters (#2235,!3960)
    - fix SBT indexing rules for device addresses (#2308,!4079)
    - relax formula for ray intersection candidate determination
      (#2322,!4080)
    - add more details on code:ShaderRecordBufferKHR variables (#2230,!4083)
    - clarify valid bits for code:InstanceCustomIndexKHR
      (GLSL/GLSL#19,!4128)
    - allow at most one code:IncomingRayPayloadKHR,
      code:IncomingCallableDataKHR, and code:HitAttributeKHR (!4129)
    - add minimum for maxShaderGroupStride (#2353,!4131)
    - require VK_KHR_pipeline_library extension to be supported
      (#2348,!4135)
    - clarify meaning of 'geometry index' (#2272,!4137)
    - restrict traces to TLAS (#2239,!4141)
    - add note about maxPipelineRayPayloadSize (#2383,!4172)
    - do not require raygen shader in pipeline libraries (!4185)
    - define sync for indirect trace rays and indirect buffer (#2407,!4208)