SPV_KHR_ray_tracing.asciidoc

SPV_KHR_ray_tracing

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. role=include

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.

(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

(Modify Section 3.21, Builtin, adding rows to the Builtin table)

(Modify the definition of following BuiltIns, allowing them to be used in IntersectionKHR, AnyHitKHR, or ClosestHitKHR Execution Models.)

(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

role=include

(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.

(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 Models	Shader role=include

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)

role=include

(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)

role=include

(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: RayTracingKHR

12

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

OpReportIntersectionKHR Reports an intersection back to the traversal infrastructure. If the intersection occurred within the current ray interval, the intersection confirmation is performed (see the API specification for more details). If the value of Hit falls outside the current ray interval, the hit is rejected. Returns True if the hit was accepted by the ray interval and the intersection was confirmed. Returns False otherwise. Hit is the floating point parametric value along ray for the intersection. Hit Kind is the integer hit kind reported back to other shaders and accessible by the hit kind builtin. Result Type must be a scalar boolean. Hit must be a 32-bit float type scalar. Hit Kind must be a 32-bit unsigned integer type scalar. This instruction is allowed only in IntersectionKHR execution model. This instruction is a shader call instruction which may invoke shaders with the AnyHitKHR execution model.					Capability: RayTracingKHR
5	5334	<id> Result Type	<id> Result	<id> Hit	<id> Hit Kind

OpIgnoreIntersectionKHR Ignores the current potential intersection, terminating the invocation that executes it, and continues the ray traversal. This instruction must be the last instruction in a block. This instruction is allowed only in AnyHitKHR execution model.	Capability: RayTracingKHR
1	4448

OpTerminateRayKHR Terminates the invocation that executes it, stops the ray traversal, accepts the current hit, and invokes the ClosestHitKHR execution model (if active). This instruction must be the last instruction in a block. This instruction is allowed only in AnyHitKHR execution model.	Capability: RayTracingKHR
1	4449

OpExecuteCallableKHR Invoke a callable shader SBT Index is the index into the SBT table to select callable shader to execute Callable Data is a pointer to the callable data to pass into the called shader. Callable Data must be the result of an OpVariable with a storage class of CallableDataKHR or IncomingCallableDataKHR. SBT Index must be a 32-bit unsigned integer type scalar. This instruction is allowed only in RayGenerationKHR, ClosestHitKHR, MissKHR and CallableKHR execution models. This instruction is a shader call instruction which will invoke a shader with the CallableKHR execution model.			Capability: RayTracingKHR
3	4446	<id> SBT Index	<id> Callable Data

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 SBT Index must be 32-bit unsigned integer (#156)