1// Copyright 2017-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_KHR_ray_tracing_pipeline.txt[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2020-11-12 11*Interactions and External Dependencies*:: 12 - This extension requires 13 https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/KHR/SPV_KHR_ray_tracing.html[`SPV_KHR_ray_tracing`] 14 - This extension provides API support for 15 https://github.com/KhronosGroup/GLSL/blob/master/extensions/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.txt[] 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,RayTracingKHR>> 116 * <<spirvenv-capabilities-table-RayTraversalPrimitiveCullingKHR,RayTraversalPrimitiveCullingKHR>> 117 118=== Issues 119 120(1) How does this extension differ from VK_NV_ray_tracing? 121-- 122*DISCUSSION*: 123 124The following is a summary of the main functional differences between 125VK_KHR_ray_tracing_pipeline and VK_NV_ray_tracing: 126 127 * added support for indirect ray tracing (flink:vkCmdTraceRaysIndirectKHR) 128 * uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing 129 ** refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are 130 functionally equivalent and aliased to the same values). 131 ** added code:RayGeometryIndexKHR built-in 132 * removed vkCompileDeferredNV compilation functionality and replaced with 133 <<deferred-host-operations, deferred host operations>> interactions for 134 ray tracing 135 * added slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure 136 * extended slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR structure 137 ** renamed pname:maxRecursionDepth to pname:maxRayRecursionDepth and it 138 has a minimum of 1 instead of 31 139 ** require pname:shaderGroupHandleSize to be 32 bytes 140 ** added pname:maxRayDispatchInvocationCount, 141 pname:shaderGroupHandleAlignment and pname:maxRayHitAttributeSize 142 * reworked geometry structures so they could be better shared between 143 device, host, and indirect builds 144 * changed SBT parameters to a structure and added size 145 (slink:VkStridedDeviceAddressRegionKHR) 146 * add parameter for requesting memory requirements for host and/or device 147 build 148 * added <<pipeline-library,pipeline library>> support for ray tracing 149 * added <<ray-traversal-watertight, watertightness guarantees>> 150 * added no-null-shader pipeline flags 151 (etext:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR) 152 * added <<ray-tracing-shader-call,memory model interactions>> with ray 153 tracing and define how subgroups work and can be repacked 154-- 155 156ifdef::VK_NV_ray_tracing[] 157(2) Can you give a more detailed comparision of differences and similarities 158between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline? 159-- 160*DISCUSSION*: 161 162The following is a more detailed comparision of which commands, structures, 163and enums are aliased, changed, or removed. 164 165 * Aliased functionality -- enums, structures, and commands that are 166 considered equivalent: 167 ** elink:VkRayTracingShaderGroupTypeNV {harr} 168 elink:VkRayTracingShaderGroupTypeKHR 169 ** flink:vkGetRayTracingShaderGroupHandlesNV {harr} 170 flink:vkGetRayTracingShaderGroupHandlesKHR 171 172 * Changed enums, structures, and commands: 173 ** slink:VkRayTracingShaderGroupCreateInfoNV -> 174 slink:VkRayTracingShaderGroupCreateInfoKHR (added 175 pname:pShaderGroupCaptureReplayHandle) 176 ** slink:VkRayTracingPipelineCreateInfoNV -> 177 slink:VkRayTracingPipelineCreateInfoKHR (changed type of pname:pGroups, 178 added pname:libraries, pname:pLibraryInterface, and 179 pname:pDynamicState) 180 ** slink:VkPhysicalDeviceRayTracingPropertiesNV -> 181 VkPhysicalDeviceRayTracingPropertiesKHR (renamed pname:maxTriangleCount 182 to pname:maxPrimitiveCount, added 183 pname:shaderGroupHandleCaptureReplaySize) 184 ** flink:vkCmdTraceRaysNV -> flink:vkCmdTraceRaysKHR (params to struct) 185 ** flink:vkCreateRayTracingPipelinesNV -> 186 flink:vkCreateRayTracingPipelinesKHR (different struct, changed 187 functionality) 188 189 * Added enums, structures and commands: 190 ** ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR 191 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, 192 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, 193 ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, 194 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, 195 ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR to 196 elink:VkPipelineCreateFlagBits 197 ** slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR structure 198 ** slink:VkDeviceOrHostAddressKHR and slink:VkDeviceOrHostAddressConstKHR 199 unions 200 ** slink:VkPipelineLibraryCreateInfoKHR struct 201 ** slink:VkRayTracingPipelineInterfaceCreateInfoKHR struct 202 ** slink:VkStridedDeviceAddressRegionKHR struct 203 ** flink:vkCmdTraceRaysIndirectKHR command and 204 slink:VkTraceRaysIndirectCommandKHR struct 205 ** flink:vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group 206 capture/replay) 207 ** flink:vkCmdSetRayTracingPipelineStackSizeKHR and 208 flink:vkGetRayTracingShaderGroupStackSizeKHR commands for stack size 209 control 210 211 * Functionality removed: 212 ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV 213 ** flink:vkCompileDeferredNV command (replaced with 214 `apiext:VK_KHR_deferred_host_operations`) 215-- 216endif::VK_NV_ray_tracing[] 217 218(3) What are the changes between the public provisional (VK_KHR_ray_tracing 219v8) release and the internal provisional (VK_KHR_ray_tracing v9) release? 220-- 221 * Require Vulkan 1.1 and SPIR-V 1.4 222 * Added interactions with Vulkan 1.2 and 223 `apiext:VK_KHR_vulkan_memory_model` 224 * added creation time capture and replay flags 225 ** added 226 ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR 227 to elink:VkPipelineCreateFlagBits 228 * replace stext:VkStridedBufferRegionKHR with 229 slink:VkStridedDeviceAddressRegionKHR and change 230 flink:vkCmdTraceRaysKHR, flink:vkCmdTraceRaysIndirectKHR, to take these 231 for the shader binding table and use device addresses instead of 232 buffers. 233 * require the shader binding table buffers to have the 234 etext:VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR set 235 * make `apiext:VK_KHR_pipeline_library` an interaction instead of required 236 extension 237 * rename the pname:libraries member of 238 slink:VkRayTracingPipelineCreateInfoKHR to pname:pLibraryInfo and make 239 it a pointer 240 * make `apiext:VK_KHR_deferred_host_operations` an interaction instead of 241 a required extension (later went back on this) 242 * added explicit stack size management for ray tracing pipelines 243 ** removed the pname:maxCallableSize member of 244 slink:VkRayTracingPipelineInterfaceCreateInfoKHR 245 ** added the pname:pDynamicState member to 246 slink:VkRayTracingPipelineCreateInfoKHR 247 ** added ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR 248 dynamic state for ray tracing pipelines 249 ** added flink:vkGetRayTracingShaderGroupStackSizeKHR and 250 flink:vkCmdSetRayTracingPipelineStackSizeKHR commands 251 ** added elink:VkShaderGroupShaderKHR enum 252 * Added pname:maxRayDispatchInvocationCount limit to 253 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 254 * Added pname:shaderGroupHandleAlignment property to 255 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 256 * Added pname:maxRayHitAttributeSize property to 257 slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR 258 * Clarify deferred host ops for pipeline creation 259 ** slink:VkDeferredOperationKHR is now a top-level parameter for 260 flink:vkCreateRayTracingPipelinesKHR 261 ** removed stext:VkDeferredOperationInfoKHR structure 262 ** change deferred host creation/return parameter behavior such that the 263 implementation can modify such parameters until the deferred host 264 operation completes 265 ** `apiext:VK_KHR_deferred_host_operations` is required again 266-- 267 268(4) What are the changes between the internal provisional 269(VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure 270v11 / VK_KHR_ray_tracing_pipeline v1) release? 271-- 272 * refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation 273 flexibility and decoupling ray query support from ray pipelines: 274 ** `apiext:VK_KHR_acceleration_structure` (for acceleration structure 275 operations) 276 ** `apiext:VK_KHR_ray_tracing_pipeline` (for ray tracing pipeline and 277 shader stages) 278 ** `apiext:VK_KHR_ray_query` (for ray queries in existing shader stages) 279 * Require code:Volatile for the following builtins in the ray generation, 280 closest hit, miss, intersection, and callable shader stages: 281 ** code:SubgroupSize, code:SubgroupLocalInvocationId, code:SubgroupEqMask, 282 code:SubgroupGeMask, code:SubgroupGtMask, code:SubgroupLeMask, 283 code:SubgroupLtMask 284 ** code:SMIDNV, code:WarpIDNV 285 * clarify buffer usage flags for ray tracing 286 ** ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR is added as an alias 287 of ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV and is required on shader 288 binding table buffers 289 ** ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT is used in 290 `apiext:VK_KHR_acceleration_structure` for pname:scratchData 291 * rename pname:maxRecursionDepth to pname:maxRayPipelineRecursionDepth 292 (pipeline creation) and pname:maxRayRecursionDepth (limit) to reduce 293 confusion 294 * Add queryable pname:maxRayHitAttributeSize limit and rename members of 295 slink:VkRayTracingPipelineInterfaceCreateInfoKHR to 296 pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize 297 for clarity 298 * Update SPIRV capabilities to use code:RayTracingKHR 299 * extension is no longer provisional 300 * define synchronization requirements for indirect trace rays and indirect 301 buffer 302-- 303 304(5) This extension adds gl_InstanceID for the intersection, any-hit, and 305 closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced 306 with gl_InstanceIndex. 307 Which should be used for Vulkan in this extension? 308-- 309*RESOLVED*: This extension uses gl_InstanceID and maps it to code:InstanceId 310in SPIR-V. 311It is acknowledged that this is different than other shader stages in 312Vulkan. 313There are two main reasons for the difference here: 314 315 * symmetry with gl_PrimitiveID which is also available in these shaders 316 * there is no "`baseInstance`" relevant for these shaders, and so ID makes 317 it more obvious that this is zero-based. 318-- 319 320=== Sample Code 321 322Example ray generation GLSL shader 323 324[source,c] 325--------------------------------------------------- 326#version 450 core 327#extension GL_EXT_ray_tracing : require 328layout(set = 0, binding = 0, rgba8) uniform image2D image; 329layout(set = 0, binding = 1) uniform accelerationStructureEXT as; 330layout(location = 0) rayPayloadEXT float payload; 331 332void main() 333{ 334 vec4 col = vec4(0, 0, 0, 1); 335 336 vec3 origin = vec3(float(gl_LaunchIDEXT.x)/float(gl_LaunchSizeEXT.x), float(gl_LaunchIDEXT.y)/float(gl_LaunchSizeEXT.y), 1.0); 337 vec3 dir = vec3(0.0, 0.0, -1.0); 338 339 traceRayEXT(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0); 340 341 col.y = payload; 342 343 imageStore(image, ivec2(gl_LaunchIDEXT.xy), col); 344} 345--------------------------------------------------- 346 347=== Version History 348 349 * Revision 1, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness, 350 Tobias Hector) 351 - Decomposition of the specification, from VK_KHR_ray_tracing to 352 VK_KHR_ray_tracing_pipeline (#1918,!3912) 353 - require certain subgroup and sm_shader_builtin shader builtins to be 354 decorated as volatile in the ray generation, closest hit, miss, 355 intersection, and callable stages (#1924,!3903,!3954) 356 - clarify buffer usage flags for ray tracing (#2181,!3939) 357 - rename maxRecursionDepth to maxRayPipelineRecursionDepth and 358 maxRayRecursionDepth (#2203,!3937) 359 - add queriable maxRayHitAttributeSize and rename members of 360 VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966) 361 - update to use code:RayTracingKHR SPIR-V capability 362 - add VUs for matching hit group type against geometry type 363 (#2245,!3994) 364 - require code:RayTMaxKHR be volatile in intersection shaders 365 (#2268,!4030) 366 - add numerical limits for ray parameters (#2235,!3960) 367 - fix SBT indexing rules for device addresses (#2308,!4079) 368 - relax formula for ray intersection candidate determination 369 (#2322,!4080) 370 - add more details on code:ShaderRecordBufferKHR variables (#2230,!4083) 371 - clarify valid bits for code:InstanceCustomIndexKHR 372 (GLSL/GLSL#19,!4128) 373 - allow at most one code:IncomingRayPayloadKHR, 374 code:IncomingCallableDataKHR, and code:HitAttributeKHR (!4129) 375 - add minimum for maxShaderGroupStride (#2353,!4131) 376 - require VK_KHR_pipeline_library extension to be supported 377 (#2348,!4135) 378 - clarify meaning of 'geometry index' (#2272,!4137) 379 - restrict traces to TLAS (#2239,!4141) 380 - add note about maxPipelineRayPayloadSize (#2383,!4172) 381 - do not require raygen shader in pipeline libraries (!4185) 382 - define sync for indirect trace rays and indirect buffer (#2407,!4208) 383 384