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