1// Copyright 2017-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_KHR_ray_tracing_pipeline.adoc[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2020-11-12 11*Interactions and External Dependencies*:: 12 - This extension provides API support for 13 {GLSLregistry}/ext/GLSL_EXT_ray_tracing.txt[`GLSL_EXT_ray_tracing`] 14 - This extension interacts with <<versions-1.2, Vulkan 1.2>> and 15 `apiext:VK_KHR_vulkan_memory_model`, adding the <<shader-call-related, 16 shader-call-related>> relation of invocations, <<shader-call-order, 17 shader-call-order>> partial order of dynamic instances of instructions, 18 and the <<shaders-scope-shadercall, code:ShaderCallKHR>> scope. 19 - This extension interacts with `apiext:VK_KHR_pipeline_library`, enabling 20 pipeline libraries to be used with ray tracing pipelines and enabling 21 usage of slink:VkRayTracingPipelineInterfaceCreateInfoKHR. 22*Contributors*:: 23 - Matthäus Chajdas, AMD 24 - Greg Grebe, AMD 25 - Nicolai Hähnle, AMD 26 - Tobias Hector, AMD 27 - Dave Oldcorn, AMD 28 - Skyler Saleh, AMD 29 - Mathieu Robart, Arm 30 - Marius Bjorge, Arm 31 - Tom Olson, Arm 32 - Sebastian Tafuri, EA 33 - Henrik Rydgard, Embark 34 - Juan Cañada, Epic Games 35 - Patrick Kelly, Epic Games 36 - Yuriy O'Donnell, Epic Games 37 - Michael Doggett, Facebook/Oculus 38 - Andrew Garrard, Imagination 39 - Don Scorgie, Imagination 40 - Dae Kim, Imagination 41 - Joshua Barczak, Intel 42 - Slawek Grajewski, Intel 43 - Jeff Bolz, NVIDIA 44 - Pascal Gautron, NVIDIA 45 - Daniel Koch, NVIDIA 46 - Christoph Kubisch, NVIDIA 47 - Ashwin Lele, NVIDIA 48 - Robert Stepinski, NVIDIA 49 - Martin Stich, NVIDIA 50 - Nuno Subtil, NVIDIA 51 - Eric Werness, NVIDIA 52 - Jon Leech, Khronos 53 - Jeroen van Schijndel, OTOY 54 - Juul Joosten, OTOY 55 - Alex Bourd, Qualcomm 56 - Roman Larionov, Qualcomm 57 - David McAllister, Qualcomm 58 - Spencer Fricke, Samsung 59 - Lewis Gordon, Samsung 60 - Ralph Potter, Samsung 61 - Jasper Bekkers, Traverse Research 62 - Jesse Barker, Unity 63 - Baldur Karlsson, Valve 64 65=== Description 66 67Rasterization has been the dominant method to produce interactive graphics, 68but increasing performance of graphics hardware has made ray tracing a 69viable option for interactive rendering. 70Being able to integrate ray tracing with traditional rasterization makes it 71easier for applications to incrementally add ray traced effects to existing 72applications or to do hybrid approaches with rasterization for primary 73visibility and ray tracing for secondary queries. 74 75To enable ray tracing, this extension adds a few different categories of new 76functionality: 77 78 * A new ray tracing pipeline type with new shader domains: ray generation, 79 intersection, any-hit, closest hit, miss, and callable 80 * A shader binding indirection table to link shader groups with 81 acceleration structure items 82 * Ray tracing commands which initiate the ray pipeline traversal and 83 invocation of the various new shader domains depending on which 84 traversal conditions are met 85 86This extension adds support for the following SPIR-V extension in Vulkan: 87 88 * `SPV_KHR_ray_tracing` 89 90include::{generated}/interfaces/VK_KHR_ray_tracing_pipeline.adoc[] 91 92=== New or Modified Built-In Variables 93 94 * <<interfaces-builtin-variables-launchid,code:LaunchIdKHR>> 95 * <<interfaces-builtin-variables-launchsize,code:LaunchSizeKHR>> 96 * <<interfaces-builtin-variables-worldrayorigin,code:WorldRayOriginKHR>> 97 * <<interfaces-builtin-variables-worldraydirection,code:WorldRayDirectionKHR>> 98 * <<interfaces-builtin-variables-objectrayorigin,code:ObjectRayOriginKHR>> 99 * <<interfaces-builtin-variables-objectraydirection,code:ObjectRayDirectionKHR>> 100 * <<interfaces-builtin-variables-raytmin,code:RayTminKHR>> 101 * <<interfaces-builtin-variables-raytmax,code:RayTmaxKHR>> 102 * <<interfaces-builtin-variables-instancecustomindex,code:InstanceCustomIndexKHR>> 103 * <<interfaces-builtin-variables-instanceid,code:InstanceId>> 104 * <<interfaces-builtin-variables-objecttoworld,code:ObjectToWorldKHR>> 105 * <<interfaces-builtin-variables-worldtoobject,code:WorldToObjectKHR>> 106 * <<interfaces-builtin-variables-hitkind,code:HitKindKHR>> 107 * <<interfaces-builtin-variables-incomingrayflags,code:IncomingRayFlagsKHR>> 108 * <<interfaces-builtin-variables-raygeometryindex,code:RayGeometryIndexKHR>> 109 * (modified)code:PrimitiveId 110 111=== New SPIR-V Capabilities 112 113 * <<spirvenv-capabilities-table-RayTracingKHR, code:RayTracingKHR>> 114 * <<spirvenv-capabilities-table-RayTraversalPrimitiveCullingKHR, 115 code:RayTraversalPrimitiveCullingKHR>> 116 117=== Issues 118 119(1) How does this extension differ from VK_NV_ray_tracing? 120-- 121*DISCUSSION*: 122 123The following is a summary of the main functional differences between 124VK_KHR_ray_tracing_pipeline and VK_NV_ray_tracing: 125 126 * added support for indirect ray tracing (flink:vkCmdTraceRaysIndirectKHR) 127 * uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing 128 ** refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are 129 functionally equivalent and aliased to the same values). 130 ** added code:RayGeometryIndexKHR built-in 131 * removed vkCompileDeferredNV compilation functionality and replaced with 132 <<deferred-host-operations, deferred host operations>> interactions for 133 ray tracing 134 * added slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure 135 * extended slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure 136 ** renamed pname:maxRecursionDepth to pname:maxRayRecursionDepth and it 137 has a minimum of 1 instead of 31 138 ** require pname:shaderGroupHandleSize to be 32 bytes 139 ** added pname:maxRayDispatchInvocationCount, 140 pname:shaderGroupHandleAlignment and pname:maxRayHitAttributeSize 141 * reworked geometry structures so they could be better shared between 142 device, host, and indirect builds 143 * changed SBT parameters to a structure and added size 144 (slink:VkStridedDeviceAddressRegionKHR) 145 * add parameter for requesting memory requirements for host and/or device 146 build 147 * added <<pipelines-library,pipeline library>> support for ray tracing 148 * added <<ray-traversal-watertight, watertightness guarantees>> 149 * added no-null-shader pipeline flags 150 (etext:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR) 151 * added <<ray-tracing-shader-call,memory model interactions>> with ray 152 tracing and define how subgroups work and can be repacked 153-- 154 155ifdef::VK_NV_ray_tracing[] 156(2) Can you give a more detailed comparison of differences and similarities 157between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline? 158-- 159*DISCUSSION*: 160 161The following is a more detailed comparison of which commands, structures, 162and enums are aliased, changed, or removed. 163 164 * Aliased functionality -- enums, structures, and commands that are 165 considered equivalent: 166 ** elink:VkRayTracingShaderGroupTypeNV {harr} 167 elink:VkRayTracingShaderGroupTypeKHR 168 ** flink:vkGetRayTracingShaderGroupHandlesNV {harr} 169 flink:vkGetRayTracingShaderGroupHandlesKHR 170 171 * Changed enums, structures, and commands: 172 ** slink:VkRayTracingShaderGroupCreateInfoNV -> 173 slink:VkRayTracingShaderGroupCreateInfoKHR (added 174 pname:pShaderGroupCaptureReplayHandle) 175 ** slink:VkRayTracingPipelineCreateInfoNV -> 176 slink:VkRayTracingPipelineCreateInfoKHR (changed type of pname:pGroups, 177 added pname:libraries, pname:pLibraryInterface, and 178 pname:pDynamicState) 179 ** slink:VkPhysicalDeviceRayTracingPropertiesNV -> 180 VkPhysicalDeviceRayTracingPropertiesKHR (renamed pname:maxTriangleCount 181 to pname:maxPrimitiveCount, added 182 pname:shaderGroupHandleCaptureReplaySize) 183 ** flink:vkCmdTraceRaysNV -> flink:vkCmdTraceRaysKHR (params to struct) 184 ** flink:vkCreateRayTracingPipelinesNV -> 185 flink:vkCreateRayTracingPipelinesKHR (different struct, changed 186 functionality) 187 188 * Added enums, structures and commands: 189 ** ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 190 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, 191 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, 192 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, 193 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, 194 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR to 195 elink:VkPipelineCreateFlagBits 196 ** slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure 197 ** slink:VkDeviceOrHostAddressKHR and slink:VkDeviceOrHostAddressConstKHR 198 unions 199 ** slink:VkPipelineLibraryCreateInfoKHR struct 200 ** slink:VkRayTracingPipelineInterfaceCreateInfoKHR struct 201 ** slink:VkStridedDeviceAddressRegionKHR struct 202 ** flink:vkCmdTraceRaysIndirectKHR command and 203 slink:VkTraceRaysIndirectCommandKHR struct 204 ** flink:vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group 205 capture/replay) 206 ** flink:vkCmdSetRayTracingPipelineStackSizeKHR and 207 flink:vkGetRayTracingShaderGroupStackSizeKHR commands for stack size 208 control 209 210 * Functionality removed: 211 ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV 212 ** flink:vkCompileDeferredNV command (replaced with 213 `apiext:VK_KHR_deferred_host_operations`) 214-- 215endif::VK_NV_ray_tracing[] 216 217(3) What are the changes between the public provisional (VK_KHR_ray_tracing 218v8) release and the internal provisional (VK_KHR_ray_tracing v9) release? 219-- 220 * Require Vulkan 1.1 and SPIR-V 1.4 221 * Added interactions with Vulkan 1.2 and 222 `apiext:VK_KHR_vulkan_memory_model` 223 * added creation time capture and replay flags 224 ** added 225 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 226 to elink:VkPipelineCreateFlagBits 227 * replace stext:VkStridedBufferRegionKHR with 228 slink:VkStridedDeviceAddressRegionKHR and change 229 flink:vkCmdTraceRaysKHR, flink:vkCmdTraceRaysIndirectKHR, to take these 230 for the shader binding table and use device addresses instead of 231 buffers. 232 * require the shader binding table buffers to have the 233 etext:VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR set 234 * make `apiext:VK_KHR_pipeline_library` an interaction instead of required 235 extension 236 * rename the pname:libraries member of 237 slink:VkRayTracingPipelineCreateInfoKHR to pname:pLibraryInfo and make 238 it a pointer 239 * make `apiext:VK_KHR_deferred_host_operations` an interaction instead of 240 a required extension (later went back on this) 241 * added explicit stack size management for ray tracing pipelines 242 ** removed the pname:maxCallableSize member of 243 slink:VkRayTracingPipelineInterfaceCreateInfoKHR 244 ** added the pname:pDynamicState member to 245 slink:VkRayTracingPipelineCreateInfoKHR 246 ** added ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR 247 dynamic state for ray tracing pipelines 248 ** added flink:vkGetRayTracingShaderGroupStackSizeKHR and 249 flink:vkCmdSetRayTracingPipelineStackSizeKHR commands 250 ** added elink:VkShaderGroupShaderKHR enum 251 * Added pname:maxRayDispatchInvocationCount limit to 252 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 253 * Added pname:shaderGroupHandleAlignment property to 254 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 255 * Added pname:maxRayHitAttributeSize property to 256 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 257 * Clarify deferred host ops for pipeline creation 258 ** slink:VkDeferredOperationKHR is now a top-level parameter for 259 flink:vkCreateRayTracingPipelinesKHR 260 ** removed stext:VkDeferredOperationInfoKHR structure 261 ** change deferred host creation/return parameter behavior such that the 262 implementation can modify such parameters until the deferred host 263 operation completes 264 ** `apiext:VK_KHR_deferred_host_operations` is required again 265-- 266 267(4) What are the changes between the internal provisional 268(VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure 269v11 / VK_KHR_ray_tracing_pipeline v1) release? 270-- 271 * refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation 272 flexibility and decoupling ray query support from ray pipelines: 273 ** `apiext:VK_KHR_acceleration_structure` (for acceleration structure 274 operations) 275 ** `apiext:VK_KHR_ray_tracing_pipeline` (for ray tracing pipeline and 276 shader stages) 277 ** `apiext:VK_KHR_ray_query` (for ray queries in existing shader stages) 278 * Require code:Volatile for the following builtins in the ray generation, 279 closest hit, miss, intersection, and callable shader stages: 280 ** code:SubgroupSize, code:SubgroupLocalInvocationId, code:SubgroupEqMask, 281 code:SubgroupGeMask, code:SubgroupGtMask, code:SubgroupLeMask, 282 code:SubgroupLtMask 283 ** code:SMIDNV, code:WarpIDNV 284 * clarify buffer usage flags for ray tracing 285 ** ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR is added as an alias 286 of ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV and is required on shader 287 binding table buffers 288 ** ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT is used in 289 `apiext:VK_KHR_acceleration_structure` for pname:scratchData 290 * rename pname:maxRecursionDepth to pname:maxRayPipelineRecursionDepth 291 (pipeline creation) and pname:maxRayRecursionDepth (limit) to reduce 292 confusion 293 * Add queryable pname:maxRayHitAttributeSize limit and rename members of 294 slink:VkRayTracingPipelineInterfaceCreateInfoKHR to 295 pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize 296 for clarity 297 * Update SPIRV capabilities to use code:RayTracingKHR 298 * extension is no longer provisional 299 * define synchronization requirements for indirect trace rays and indirect 300 buffer 301-- 302 303(5) This extension adds gl_InstanceID for the intersection, any-hit, and 304closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced with 305gl_InstanceIndex. 306Which should be used for Vulkan in this extension? 307-- 308*RESOLVED*: This extension uses gl_InstanceID and maps it to code:InstanceId 309in SPIR-V. 310It is acknowledged that this is different than other shader stages in 311Vulkan. 312There are two main reasons for the difference here: 313 314 * symmetry with gl_PrimitiveID which is also available in these shaders 315 * there is no "`baseInstance`" relevant for these shaders, and so ID makes 316 it more obvious that this is zero-based. 317-- 318 319(6) Why is `apiext:VK_KHR_pipeline_library` an interaction instead of a 320required dependency, particularly when the "`Feature Requirements`" section 321says it is required to be supported anyhow? 322-- 323*RESOLVED*: If `apiext:VK_KHR_pipeline_library` were a required extension 324dependency, then every application would need to enable the extension 325whether or not they actually want to use the pipeline library functionality. 326Developers found this to be annoying and unfriendly behavior. 327We do wish to require all *implementations* to support it though, and thus 328it is listed in the feature requirements section. 329-- 330 331 332=== Sample Code 333 334Example ray generation GLSL shader 335 336[source,c] 337---- 338#version 450 core 339#extension GL_EXT_ray_tracing : require 340layout(set = 0, binding = 0, rgba8) uniform image2D image; 341layout(set = 0, binding = 1) uniform accelerationStructureEXT as; 342layout(location = 0) rayPayloadEXT float payload; 343 344void main() 345{ 346 vec4 col = vec4(0, 0, 0, 1); 347 348 vec3 origin = vec3(float(gl_LaunchIDEXT.x)/float(gl_LaunchSizeEXT.x), float(gl_LaunchIDEXT.y)/float(gl_LaunchSizeEXT.y), 1.0); 349 vec3 dir = vec3(0.0, 0.0, -1.0); 350 351 traceRayEXT(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0); 352 353 col.y = payload; 354 355 imageStore(image, ivec2(gl_LaunchIDEXT.xy), col); 356} 357---- 358 359=== Version History 360 361 * Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness, 362 Tobias Hector) 363 ** Decomposition of the specification, from VK_KHR_ray_tracing to 364 VK_KHR_ray_tracing_pipeline (#1918,!3912) 365 ** require certain subgroup and sm_shader_builtin shader builtins to be 366 decorated as volatile in the ray generation, closest hit, miss, 367 intersection, and callable stages (#1924,!3903,!3954) 368 ** clarify buffer usage flags for ray tracing (#2181,!3939) 369 ** rename maxRecursionDepth to maxRayPipelineRecursionDepth and 370 maxRayRecursionDepth (#2203,!3937) 371 ** add queryable maxRayHitAttributeSize and rename members of 372 VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966) 373 ** update to use code:RayTracingKHR SPIR-V capability 374 ** add VUs for matching hit group type against geometry type (#2245,!3994) 375 ** require code:RayTMaxKHR be volatile in intersection shaders 376 (#2268,!4030) 377 ** add numerical limits for ray parameters (#2235,!3960) 378 ** fix SBT indexing rules for device addresses (#2308,!4079) 379 ** relax formula for ray intersection candidate determination 380 (#2322,!4080) 381 ** add more details on code:ShaderRecordBufferKHR variables (#2230,!4083) 382 ** clarify valid bits for code:InstanceCustomIndexKHR (GLSL/GLSL#19,!4128) 383 ** allow at most one code:IncomingRayPayloadKHR, 384 code:IncomingCallableDataKHR, and code:HitAttributeKHR (!4129) 385 ** add minimum for maxShaderGroupStride (#2353,!4131) 386 ** require VK_KHR_pipeline_library extension to be supported (#2348,!4135) 387 ** clarify meaning of 'geometry index' (#2272,!4137) 388 ** restrict traces to TLAS (#2239,!4141) 389 ** add note about maxPipelineRayPayloadSize (#2383,!4172) 390 ** do not require raygen shader in pipeline libraries (!4185) 391 ** define sync for indirect trace rays and indirect buffer (#2407,!4208) 392 393