Name Strings
SPV_KHR_ray_tracing
Contact
See Issues list in the Khronos SPIRV-Registry repository: https://github.com/KhronosGroup/SPIRV-Registry
Contributors
-
Eric Werness, NVIDIA
-
Ashwin Lele, NVIDIA
-
Daniel Koch, NVIDIA
-
Tobias Hector, AMD
-
Nicolai Haehnle, AMD
-
David Neto, Google
-
Alan Baker, Google
-
John Kessenich, Google
-
Joshua Barczak, Intel
-
Faith Ekstrand, Intel
-
Hans-Kristian Arntzen, Valve
Status
-
Complete
-
Ratified by the Khronos Board 2020-11-20
Version
Last Modified Date |
2022-08-17 |
Revision |
24 |
Dependencies
This extension is written against the SPIR-V Specification, Version 1.5 Revision 1.
This extension requires SPIR-V 1.4.
This extension interacts with SPV_KHR_ray_query.
Overview
This extension adds new functionality to support the Vulkan VK_KHR_ray_tracing_pipeline extension in SPIR-V.
Extension Name
To use this extension within a SPIR-V module, the following OpExtension must be present in the module:
OpExtension "SPV_KHR_ray_tracing"
New Execution Models
This extension introduces new execution models:
RayGenerationKHR IntersectionKHR AnyHitKHR ClosestHitKHR MissKHR CallableKHR
these depend on the RayTracingKHR capability.
New Capabilities
This extension introduces new capabilities:
RayTracingKHR RayTraversalPrimitiveCullingKHR
New Storage Classes
Storage classes added under the RayTracingKHR capability
RayPayloadKHR IncomingRayPayloadKHR HitAttributeKHR CallableDataKHR IncomingCallableDataKHR ShaderRecordBufferKHR
New Builtins
Builtins added under the RayTracingKHR capability
LaunchIdKHR LaunchSizeKHR InstanceCustomIndexKHR RayGeometryIndexKHR WorldRayOriginKHR WorldRayDirectionKHR ObjectRayOriginKHR ObjectRayDirectionKHR RayTminKHR RayTmaxKHR ObjectToWorldKHR WorldToObjectKHR HitKindKHR IncomingRayFlagsKHR
New Instructions
Instructions added under the RayTracingKHR capability
OpReportIntersectionKHR OpIgnoreIntersectionKHR OpTerminateRayKHR OpTraceRayKHR OpTypeAccelerationStructureKHR OpExecuteCallableKHR OpConvertUToAccelerationStructureKHR
Modifications to the SPIR-V Specification
- (Modify Section 2.2.1, Instructions )
-
Shader Call Instruction: An instruction which may cause execution to continue elsewhere by creating one or more invocations that execute other shaders. The OpTraceRayKHR, OpExecuteCallableKHR, and OpReportIntersectionKHR instructions are shader call instructions.
- (Modify Section 2.2.2, Types )
-
add OpTypeAccelerationStructureKHR to list of opaque types
- (Modify Section 2.2.5, Control Flow)
-
Add OpIgnoreIntersectionKHR and OpTerminateRayKHR to the list of Termination Instructions.
- (Modify Section 2.16.1, Universal Validation Rules)
-
Modify the list following the statement:
A pointer operand to an OpFunctionCall must point into one of the following storage classes:
to include ShaderRecordBufferKHR.
Change the second bullet under "Any pointer operand to an OpFunctionCall must be" to include OpTypeAccelerationStructureKHR:
-
a pointer to an element in an array that is a memory object declaration, where the element type is OpTypeSampler, OpTypeImage, or OpTypeAccelerationStructureKHR.
Add a new bullet under "Data rules":
-
Instructions accessing a scalar acceleration structure out of a composite must only use dynamically-uniform indexes, unless the index is decorated with NonUniformEXT. They must be in the same block in which their Result <id> are consumed. Such Result <id> must not appear as operands to OpPhi or OpSelect instructions, or any instructions other than the ray tracing instructions specified to operate on them.
Modify the item under "Memory model":
Memory accesses that use NonPrivatePointer must use pointers in the Uniform, Workgroup, CrossWorkgroup, Generic, Image, or StorageBuffer storage classes.
to include ShaderRecordBufferKHR.
-
- (Modify Section 2.16.2, Universal Rules for Shader Capabilities)
-
Modify the item:
-
Composite objects in the StorageBuffer, PhysicalStorageBuffer, Uniform, and PushConstant Storage Classes must be explicitly laid out. …
to include ShaderRecordBufferKHR.
-
- (Modify Section 3.3, Execution Model, adding rows to the Execution Model table)
-
Execution Model Enabling Capabilities 5313
RayGenerationKHR
Ray generation shading stage.RayTracingKHR
5314
IntersectionKHR
Intersection shading stage.RayTracingKHR
5315
AnyHitKHR
Any hit shading stage.RayTracingKHR
5316
ClosestHitKHR
Closest hit shading stage.RayTracingKHR
5317
MissKHR
Miss shading stage.RayTracingKHR
5318
CallableKHR
Ray callable shading stage.RayTracingKHR
- (Modify Section 3.7, Storage Class, adding rows to the Storage Class table)
-
Storage Class Enabling Capabilities Enabled by Extension 5328
CallableDataKHR
Used for storing arbitrary data associated with a ray to pass to callables. Visible across all functions in the current invocation. Not shared externally. Variables declared with this storage class can be both read and written to, but cannot have initializers. Only allowed in RayGenerationKHR, ClosestHitKHR, CallableKHR, and MissKHR execution models.RayTracingKHR
SPV_KHR_ray_tracing
5329
IncomingCallableDataKHR
Used for storing arbitrary data from parent sent to current callable stage invoked from OpExecuteCallable. Visible across all functions in current invocation. Not shared externally. Variables declared with the storage class are allowed only in CallableKHR execution models. Can be both read and written to in above execution models, but cannot have initializers.RayTracingKHR
SPV_KHR_ray_tracing
5338
RayPayloadKHR
Used for storing payload data associated with a ray. Visible across all functions in the current invocation. Not shared externally. Variables declared with this storage class can be both read and written to, but cannot have initializers. Only allowed in RayGenerationKHR, ClosestHitKHR and MissKHR execution models.RayTracingKHR
SPV_KHR_ray_tracing
5339
HitAttributeKHR
Used for storing attributes of geometry intersected by a ray. Visible across all functions in the current invocation. Not shared externally. Variables declared with this storage class are allowed only in IntersectionKHR, AnyHitKHR and ClosestHitKHR execution models. They can be written to only in IntersectionKHR execution model and read from only in AnyHitKHR and ClosestHitKHR execution models. They cannot have initializers.RayTracingKHR
SPV_KHR_ray_tracing
5342
IncomingRayPayloadKHR
Used for storing parent payload data associated with a ray in current stage invoked from a trace call. Visible across all functions in current invocation. Not shared externally. Variables declared with the storage class are allowed only in AnyHitKHR, ClosestHitKHR and MissKHR execution models. Can be both read and written to in above execution models, but cannot have initializers.RayTracingKHR
SPV_KHR_ray_tracing
5343
ShaderRecordBufferKHR
Used for storing data in shader record associated with each unique shader in ray_tracing pipeline. Visible across all functions in current invocation. Can be initialized externally via API. Variables declared with this storage class are allowed in RayGenerationKHR, IntersectionKHR, AnyHitKHR, ClosestHitKHR, MissKHR and CallableKHR execution models, are read-only, and cannot have initializers. Refer to the client API for details on shader records.RayTracingKHR
SPV_KHR_ray_tracing
- (Modify Section 3.21, Builtin, adding rows to the Builtin table)
-
Decoration Enabling Capabilities 5319
LaunchIdKHR
Index of work item being processed in current invocation of ray tracing shader stage. Allowed in all ray tracing execution models.
Refer to the client API specification for more details.RayTracingKHR
5320
LaunchSizeKHR
Width and height dimensions passed to vkCmdTraceRaysKHR call which resulted in invocation of current ray tracing shader stage. Allowed in all ray tracing execution models.
Refer to the client API specification for more details.RayTracingKHR
5321
WorldRayOriginKHR
World-space origin coordinates for the ray being traced in the IntersectionKHR, AnyHitKHR, ClosestHitKHR, or MissKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5322
WorldRayDirectionKHR
World-space direction for the ray being traced in the IntersectionKHR, AnyHitKHR, ClosestHitKHR, or MissKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5323
ObjectRayOriginKHR
Object-space origin coordinates for the ray being traced in the IntersectionKHR, AnyHitKHR, or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5324
ObjectRayDirectionKHR
Object-space direction for the ray being traced in the IntersectionKHR, AnyHitKHR, or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5325
RayTminKHR
The current Tmin parametric value for the ray being traced in the IntersectionKHR, AnyHitKHR, ClosestHitKHR, or MissKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5326
RayTmaxKHR
The current Tmax parametric value for the ray being traced in the IntersectionKHR, AnyHitKHR, ClosestHitKHR, or MissKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5327
InstanceCustomIndexKHR
Application specified value associated with the instance that was hit by the current ray in the IntersectionKHR, AnyHitKHR, ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5330
ObjectToWorldKHR
The 4x3 object to world transformation matrix for the ray being traced in the IntersectionKHR, AnyHitKHR, or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5331
WorldToObjectKHR
The 4x3 world to object transformation matrix for the ray being traced in the IntersectionKHR, AnyHitKHR, or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5333
HitKindKHR
The hit kind of the hit for the ray being traced in the AnyHitKHR or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
5351
IncomingRayFlagsKHR
The ray flags in current stage as passed in through trace call in parent. Available in AnyHitKHR, ClosestHitKHR, IntersectionKHR, and MissKHR stage
Refer to the client API specification for more details.RayTracingKHR
5352
RayGeometryIndexKHR
Implementation defined index corresponding to the geometry that was hit by the current ray in the IntersectionKHR, AnyHitKHR, or ClosestHitKHR execution models.
Refer to the client API specification for more details.RayTracingKHR
- (Modify the definition of following BuiltIns, allowing them to be used in IntersectionKHR, AnyHitKHR, or ClosestHitKHR Execution Models.)
-
BuiltIn Enabling Capabilities Enabled by Extension 6
InstanceId
Input Instance identifier. See the client API specifications for more detail.Instance ID in a Vertex Execution Model
Shader
Instance ID in an IntersectionKHR, AnyHitKHR, or ClosestHitKHR Execution Model
RayTracingKHR
SPV_KHR_ray_tracing
7
PrimitiveId
Primitive identifier. See the client API specifications for more detail.Primitive ID in a Geometry Execution Model
Geometry
Primitive ID in a Tessellation Execution Model
Tessellation
Primitive ID in an IntersectionKHR, AnyHitKHR, or ClosestHitKHR Execution Model
RayTracingKHR
SPV_KHR_ray_tracing
- (Modify Section 3.25, Memory Semantics <id>)
-
Modify the UniformMemory cell:
Apply the memory-ordering constraints to StorageBuffer, PhysicalStorageBuffer, or Uniform Storage Class memory.
to include ShaderRecordBufferKHR.
- (Modify Section 3.27, Scope <id>, adding a new row to the Scope table)
-
Scope Enabling Capabilities 6
ShaderCallKHR
Scope is the set of invocations that are shader-call-related in a ray tracing Execution Model. Set the client API specification for details.RayTracingKHR
- (Add a new sub-section 3.RF, Ray Flags, adding a new table)
-
3.RF, Ray Flags
Flags controlling the properties of an OpTraceRayKHR instruction or for comparing against the IncomingRayFlagsKHR builtin. See the client API specification for more details.
Despite being a mask and allowing multiple bits to be combined, the following combinations are invalid:
-
if more than one of these four bits are set: OpaqueKHR, NoOpaqueKHR, CullOpaqueKHR, CullNoOpaqueKHR.
-
if more than one of these three bits are set: SkipTrianglesKHR, CullBackFacingTrianglesKHR, CullFrontFacingTrianglesKHR.
-
if more than one of these two bits are set: SkipTrianglesKHR, SkipAABBsKHR.
Ray Flags Enabling Capabilities 0
NoneKHR
No flags specified.RayTracingKHR
1
OpaqueKHR
Force all intersections with the trace to be opaque.
See the Ray Opacity Culling section in the Vulkan API specification.RayTracingKHR
2
NoOpaqueKHR
Force all intersections with the trace to be non-opaque.
See the Ray Opacity Culling section in the Vulkan API specification.RayTracingKHR
4
TerminateOnFirstHitKHR
Accept the first hit discovered.
See the Ray Closest Hit Determination section in the Vulkan API specification.RayTracingKHR
8
SkipClosestHitShaderKHR
Do not execute a closest hit shader.
See the Ray Result Determination section in the Vulkan API specification.RayTracingKHR
16
CullBackFacingTrianglesKHR
Do not intersect with the back face of triangles.
See the Ray Face Culling section in the Vulkan API specification.RayTracingKHR
32
CullFrontFacingTrianglesKHR
Do not intersect with the front face of triangles.
See the Ray Face Culling section in the Vulkan API specification.RayTracingKHR
64
CullOpaqueKHR
Do not intersect with opaque geometry.
See the Ray Opacity Culling section in the Vulkan API specification.RayTracingKHR
128
CullNoOpaqueKHR
Do not intersect with non-opaque geometry.
See the Ray Opacity Culling section in the Vulkan API specification.RayTracingKHR
256
SkipTrianglesKHR
Do not intersect with any triangle geometries. See the Ray Primitive Culling section in the Vulkan API specification.RayTraversalPrimitiveCullingKHR
512
SkipAABBsKHR
Do not intersect with any aabb geometries. See the Ray Primitive Culling section in the Vulkan API specification.RayTraversalPrimitiveCullingKHR
-
- (Add a new sub-section 3.HK, Hit Kinds, adding a new table)
-
3.HK, Hit Kinds
Values returned in the variable decorated as HitKindKHR from built-in intersections with triangle geometry. See the Ray Face Culling section in the Vulkan API specification.
Hit Kind Enabling Capabilities 0xFE
HitKindFrontFacingTriangleKHR
The intersection was with front-facing geometry.RayTracingKHR
0xFF
HitKindBackFacingTriangleKHR
The intersection was with back-facing geometry.RayTracingKHR
- (Modify Section 3.31, Capability, adding a row to the Capability table)
-
Capability Implicitly Declares 4479
RayTracingKHR
Uses the RayGenerationKHR, IntersectionKHR, AnyHitKHR, ClosestHitKHR, MissKHR, or CallableKHR Execution ModelsShader
4478
RayTraversalPrimitiveCullingKHR
Uses SkipAABBsKHR or SkipTrianglesKHRRayTracingKHR
Modify the StorageBuffer16BitAccess cell to include ShaderRecordBufferKHR.
Modify the UniformAndStorageBuffer16BitAccess cell to include ShaderRecordBufferKHR.
Modify the StorageBuffer8BitAccess cell to include ShaderRecordBufferKHR.
Modify the UniformAndStorageBuffer8BitAccess cell to include ShaderRecordBufferKHR.
- (Modify Section 3.36.6, Type-Declaration Instructions, adding a new table)
-
OpTypeAccelerationStructureKHR
Declares an acceleration structure type which is an opaque reference to acceleration structure handle as defined in the client API specification.Consumed by OpRayQueryInitializeKHR and OpTraceRayKHR
This type is opaque: values of this type have no defined physical size or bit pattern.
Capability:
RayTracingKHR2
5341
<id> Result
- (Modify Section 3.36.8, Memory Instructions)
-
Modify the following sentence in the description of OpPtrAccessChain
For objects in the Uniform, StorageBuffer, or PushConstant storage classes, the element’s address or location is calculated using a stride, which will be the Base-type’s Array Stride when the Base type is decorated with ArrayStride.
to include ShaderRecordBufferKHR.
- (Modify Section 3.36.11, Conversion Instructions, adding a new table)
-
- (Add a new sub section 3.36.RT, Ray Tracing Instructions, adding to end of list of instructions)
-
OpTraceRayKHR
Trace a ray into the acceleration structure.
Acceleration Structure is the descriptor for the acceleration structure to trace into.
Ray Flags contains one or more of the Ray Flag values.
Cull Mask is the mask to test against the instance mask.
SBT Offset and SBT Stride control indexing into the SBT for hit shaders called from this trace. SBT stands for Shader Binding Table. Refer to the client API specification for details.
Miss Index is the index of the miss shader to be called from this trace call.
Ray Origin, Ray Tmin, Ray Direction, and Ray Tmax control the basic parameters of the ray to be traced.
Payload is a pointer to the ray payload structure to use for this trace. Payload must be the result of an OpVariable with a storage class of RayPayloadKHR or IncomingRayPayloadKHR.
Ray Flags, Cull Mask, SBT Offset, SBT Stride, and Miss Index must be a 32-bit integer type scalar.
Only the 8 least-significant bits of Cull Mask are used by this instruction - other bits are ignored.
Only the 4 least-significant bits of SBT Offset and SBT Stride are used by this instruction - other bits are ignored.
Only the 16 least-significant bits of Miss Index are used by this instruction - other bits are ignored.
Ray Origin and Ray Direction must be a 32-bit float type 3-component vector.
Ray Tmin and Ray Tmax must be a 32-bit float type scalar.
This instruction is allowed only in RayGenerationKHR, ClosestHitKHR and MissKHR execution models.
This instruction is a shader call instruction which may invoke shaders with the IntersectionKHR, AnyHitKHR, ClosestHitKHR, and MissKHR execution models.
Capability:
RayTracingKHR12
4445
<id> Acceleration Structure
<id> Ray Flags
<id> Cull Mask
<id> SBT Offset
<id> SBT Stride
<id> Miss Index
<id> Ray Origin
<id> Ray Tmin
<id> Ray Direction
<id> Ray Tmax
<id> Payload
Validation Rules
An OpExtension must be added to the SPIR-V for validation layers to check legal use of this extension:
OpExtension "SPV_KHR_ray_tracing"
Interactions with SPV_KHR_ray_query
OpTypeAccelerationStructureKHR, RayTraversalPrimitiveCullingKHR,
OpConvertUToAccelerationStructureKHR and the Ray Flags
are added by both
this extension and SPV_KHR_ray_query
; they
are intended to have identical definitions, and can be enabled by either
extension’s capability, for use with the instructions under that same
capability.
If SPV_KHR_ray_query
is not supported, ignore any references to
OpRayQueryInitializeKHR.
Issues
1) Should the global variables be listed in the entrypoint interface?
Discussion: This makes the consumer lives easier in the presence of multiple entry points. This is already required in SPIR-V 1.4, but if using an earlier version of SPIR-V it is actually illegal.
Resolved: Require SPIR-V 1.4 to make it simpler for consumers. SPV_NV_ray_tracing needs to work both ways since it pre-dates SPIR-V 1.4, but implementations which only support SPV_KHR_ray_tracing will benefit from this requirement.
2) What are the differences between provisional and final?
Discussion:
-
change RayTracingProvisionalKHR to RayTracingKHR and assign new token (4479)
-
change ray payloads and callable data to pointers rather than integer locations (this resulted in new opcodes for OpTraceRayKHR (4445) and OpExecuteCallableKHR (4446))
-
added OpConvertUToAccelerationStructureKHR (4447) instruction to convert from a 64-bit acceleration structure pointer to an OpTypeAccelerationStructureKHR to enable tracing by handle
-
Assign new opcodes for OpIgnoreIntersectionKHR (4448) and OpTerminateRayKHR (4449) and specify that they are termination instructions.
3) Are OpReportIntersectionKHR and OpIgnoreIntersectionKHR terminators like OpTerminateInvocation or just OpKill?
Resolved: They are meant to unambiguously end execution similarly to OpTerminateInvocation. We are trying to avoid the mess caused by OpKill.
Revision History
Rev | Date | Author | Changes |
---|---|---|---|
1 |
2019-04-30 |
Daniel Koch |
Fork from SPV_NV_ray_tracing rev 4. |
2 |
2019-04-30 |
Daniel Koch |
Add Ray Flags documentation. |
3 |
2019-06-20 |
Tobias Hector |
Add RayGeometryIndexKHR. |
4 |
2019-10-25 |
Tobias Hector |
Add description to ray flags. |
5 |
2019-11-20 |
Daniel Koch |
OpTraceKHR → OpTraceRayKHR. Add references to API spec for ray flags. Add Hit Kind documentation. |
6 |
2019-11-25 |
Daniel Koch |
Add ShaderCallKHR scope. Document payload for OpTraceRayKHR. |
7 |
2019-11-27 |
Daniel Koch |
Disallow initializers on all new storage classes. |
8 |
2019-12-03 |
Tobias Hector |
Add interactions with SPV_KHR_ray_query. |
9 |
2019-12-05 |
Tobias Hector |
Add RayTraversalPrimitiveCullingKHR capability and the SkipAABBsKHR/SkipTrianglesKHR ray flags. |
10 |
2019-12-05 |
Daniel Koch |
Base on SPIR-V 1.5 |
11 |
2019-12-11 |
Daniel Koch |
add Provisional string to capabilities, and reassign token for RayTracingProvisionalKHR. |
12 |
2020-02-20 |
Eric Werness |
Miss does not have object parameters. |
13 |
2020-02-22 |
Tobias Hector |
Removed HitTKHR alias of RayTmaxKHR |
14 |
2020-04-22 |
Daniel Koch |
Require SPIR-V 1.4. |
15 |
2020-06-03 |
Daniel Koch |
Update capabilities tables to match SPIR-V 1.5. |
16 |
2020-06-04 |
Faith Ekstrand |
Make ray payloads and callable data pointers rather than integer locations |
17 |
2020-06-05 |
Hans-Kristian Arntzen |
Add conversion from 64-bit acceleration structure pointer to OpTypeAccelerationStructureKHR |
18 |
2020-07-03 |
Daniel Koch |
Remove provisional notices and update capabilities |
19 |
2020-07-10 |
Tobias Hector |
Clarify that subset of bits are used for trace operation |
20 |
2020-09-25 |
Daniel Koch |
Require explicit layouts for ShaderRecordBufferKHR and otherwise just generally treat it as the StorageBuffer storage class. Clarify OpReportIntersection behavior if out of range Hit (vulkan#2359). |
21 |
2020-10-01 |
Daniel Koch |
Update OpIgnoreIntersectionKHR and OpTerminateRayKHR behavior (they are terminators) and assign new opcodes (vulkan#2374). |
22 |
2021-05-13 |
Eric Werness |
Fix ray payload allowed execution models to exclude any hit. |
23 |
2022-05-27 |
Daniel Koch |
disallow more combinations of ray flags (vk-gl-cts#3647) |
24 |
2022-08-17 |
Daniel Koch |
OpExecuteCallableKHR |