SPV_NV_ray_tracing.asciidoc

SPV_NV_ray_tracing

Name Strings

SPV_NV_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

Status

• Complete

Version

Last Modified Date	2020-09-17
Revision	5

Dependencies

This extension is written against the SPIR-V Specification, Version 1.1 Revision 4.

This extension requires SPIR-V 1.0.

Overview

This extension adds new functionality to support the Vulkan VK_NV_ray_tracing 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_NV_ray_tracing"

New Execution Models

This extension introduces new execution models:

RayGenerationNV
IntersectionNV
AnyHitNV
ClosestHitNV
MissNV
CallableNV

these depend on the RayTracingNV capability.

New Capabilities

This extension introduces new capabilities:

RayTracingNV

New Storage Classes

Storage classes added under the RayTracingNV capability

RayPayloadNV
IncomingRayPayloadNV
HitAttributeNV
CallableDataNV
IncomingCallableDataNV
ShaderRecordBufferNV

New Builtins

Builtins added under the RayTracingNV capability

LaunchIdNV
LaunchSizeNV
InstanceCustomIndexNV
WorldRayOriginNV
WorldRayDirectionNV
ObjectRayOriginNV
ObjectRayDirectionNV
RayTminNV
RayTmaxNV
ObjectToWorldNV
WorldToObjectNV
HitTNV
HitKindNV
IncomingRayFlagsNV

New Instructions

Instructions added under the RayTracingNV capability

OpReportIntersectionNV
OpIgnoreIntersectionNV
OpTerminateRayNV
OpTraceNV
OpTypeAccelerationStructureNV
OpExecuteCallableNV

Modifications to the SPIR-V Specification, Version 1.1

(Modify Section 2.2.2, Types )

add OpTypeAccelerationStructureNV to list of opaque types

(Modify Section 3.3, Execution Model, adding rows to the Execution Model table)

Execution Model		Enabling Capabilities
5313	RayGenerationNV Ray generation shading stage.	RayTracingNV
5314	IntersectionNV Intersection shading stage.	RayTracingNV
5315	AnyHitNV Any hit shading stage.	RayTracingNV
5316	ClosestHitNV Closest hit shading stage.	RayTracingNV
5317	MissNV Miss shading stage.	RayTracingNV
5318	CallableNV Ray callable shading stage.	RayTracingNV

(Modify Section 3.7, Storage Class, adding rows to the Storage Class table)

Storage Class		Enabling Capabilities	Enabled by Extension
5328	CallableDataNV 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. Only allowed in RayGenerationNV, ClosestHitNV, CallableNV, and MissNV execution models.	RayTracingNV	SPV_NV_ray_tracing
5329	IncomingCallableDataNV Used for storing arbitrary data from parent sent to current callable stage invoked from an executeCallable call. Visible across all functions in current invocation. Not shared externally. Variables declared with the storage class are allowed only in CallableNV execution models. Can be both read and written to in above execution models.	RayTracingNV	SPV_NV_ray_tracing
5338	RayPayloadNV 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. Only allowed in RayGenerationNV, AnyHitNV, ClosestHitNV and MissNV execution models.	RayTracingNV	SPV_NV_ray_tracing
5339	HitAttributeNV 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 IntersectionNV, AnyHitNV and ClosestHitNV execution models. They can be written to only in IntersectionNV execution model and read from only in AnyHitNV and ClosestHitNV execution models.	RayTracingNV	SPV_NV_ray_tracing
5342	IncomingRayPayloadNV 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 AnyHitNV, ClosestHitNV and MissNV execution models. Can be both read and written to in above execution models.	RayTracingNV	SPV_NV_ray_tracing
5343	ShaderRecordBufferNV 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 RayGenerationNV, IntersectionNV, AnyHitNV, ClosestHitNV, MissNV and CallableNV execution models and can be both read and written to but cannot have initializers. Refer to the Ray Tracing chapter of Vulkan API specification for details on shader records.	RayTracingNV	SPV_NV_ray_tracing

(Modify Section 3.20, Decoration)

Modify the definition of the Location decoration to add:

Location also forms the linkage between:

• OpTraceNV and the RayPayloadKHR and IncomingRayPayloadKHR Storage Classes

• OpExecuteCallableNV and the CallableDataKHR and IncomingCallableDataKHR Storage Classes

Add RayPayloadKHR, IncomingRayPayloadKHR, CallableDataKHR, and IncomingCallableDataKHR to the list of Storage Classes that Location is valid on.

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

Decoration		Enabling Capabilities	Extra Operands
5319	LaunchIdNV Index of work item being processed in current invocation of ray tracing shader stage. Allowed in all ray tracing execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5320	LaunchSizeNV Width and height dimensions passed to vkCmdTraceRaysNV call which resulted in invocation of current ray tracing shader stage. Allowed in all ray tracing execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5321	WorldRayOriginNV World-space origin coordinates for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5322	WorldRayDirectionNV World-space direction for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5323	ObjectRayOriginNV Object-space origin coordinates for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5324	ObjectRayDirectionNV Object-space direction for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5325	RayTminNV The current Tmin parametric value for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5326	RayTmaxNV The current Tmax parametric value for the ray being traced in the IntersectionNV, AnyHitNV, ClosestHitNV, or MissNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5327	InstanceCustomIndexNV Application specified value associated with the instance that was hit by the current ray in the IntersectionNV, AnyHitNV, ClosestHitNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5330	ObjectToWorldNV The 4x3 object to world transformation matrix for the ray being traced in the IntersectionNV, AnyHitNV, or ClosestHitNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5331	WorldToObjectNV The 4x3 world to object transformation matrix for the ray being traced in the IntersectionNV, AnyHitNV, or ClosestHitNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5332	HitTNV The parametric value T for the ray resulting in a hit for the ray being traced in the AnyHitNV or ClosestHitNV execution models. This is an alias for RayTMaxNV for convenience. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5333	HitKindNV The hit kind of the hit for the ray being traced in the AnyHitNV or ClosestHitNV execution models. Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV
5351	IncomingRayFlagsNV The ray flags in current stage as passed in through trace call in parent. Available in AnyHitNV, ClosestHitNV, IntersectionNV, and MissNV stage Refer to the Ray Tracing chapter of Vulkan API specification for more details.	RayTracingNV

(Modify the definition of following BuiltIns, allowing them to be used in IntersectionNV, AnyHitNV, or ClosestHitNV 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 IntersectionNV, AnyHitNV, or ClosestHitNV Execution Model	RayTracingNV	SPV_NV_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 IntersectionNV, AnyHitNV, or ClosestHitNV Execution Model	RayTracingNV	SPV_NV_ray_tracing

(Modify Section 3.31, Capability, adding a row to the Capability table)

Capability		Depends On	Enabled by Extension
5340	RayTracingNV Uses the RayGenerationNV, IntersectionNV, AnyHitNV, ClosestHitNV, MissNV, or CallableNV Execution Models		SPV_NV_ray_tracing

(Modify Section 3.32.6, Type-Declaration Instructions, adding a new table)

OpTypeAccelerationStructureNV Declares an acceleration structure type which is an opaque reference to acceleration structure handle as defined in the Ray Tracing chapter of Vulkan API specification. Consumed by OpTraceNV This type is opaque: values of this type have no defined physical size or bit pattern.		Capability: RayTracingNV
2	5341	<id> Result

(Add a new sub section 3.32.24, Ray Tracing Instructions, adding to end of list of instructions)

OpTraceNV Trace a ray into the acceleration structure. Acceleration Structure is the descriptor for the acceleration structure to trace into. Ray Flags controls the properties for the trace. See the Ray Tracing chapter of Vulkan API specification for more details. Cull Mask is the 8-bit mask for 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 Ray Tracing chapter of Vulkan 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 number matches the declared location of the payload structure to use for this trace. Ray Flags, Cull Mask, SBT Offset, SBT Stride, and Miss Index must be a 32-bit integer type scalar. 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 RayGenerationNV, ClosestHitNV and MissNV execution models.

Capability: RayTracingNV

12

5337

<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 number

OpReportIntersectionNV Reports an intersection back to the traversal infrastructure. 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 IntersectionNV execution model.					Capability: RayTracingNV
5	5334	<id> Result Type	<id> Result	<id> Hit	<id> Hit Kind

OpIgnoreIntersectionNV Ignores the current potential intersection. This instruction is allowed only in AnyHitNV execution model.	Capability: RayTracingNV
1	5335

OpTerminateRayNV Terminates further traversal of a ray. This instruction is allowed only in AnyHitNV execution model.	Capability: RayTracingNV
1	5336

OpExecuteCallableNV Invoke a callable shader SBT Index is the index into the SBT table to select callable shader to execute Callable Data Number matches the declared location of the callable data to pass into through this call This instruction is allowed only in RayGenerationNV, ClosestHitNV, MissNV and CallableNV execution models.			Capability: RayTracingNV
3	5344	<id> SBT Index	<id> Callable Data Number

Validation Rules

An OpExtension must be added to the SPIR-V for validation layers to check legal use of this extension:

OpExtension "SPV_NV_ray_tracing"

Issues

None yet!

Revision History

Rev	Date	Author	Changes
1	2018-09-12	Eric Werness	Internal revisions
2	2018-10-19	Ashwin Lele	Rename from NVX_raytracing to NV_ray_tracing. Add IncomingRayFlagsNV, CallableDataNV, IncomingCallableDataNV, OpExecuteCallableNV
3	2018-11-20	Daniel Koch	Uses InstanceId not InstanceIndex for Intersection, Any Hit and Closest Hit shaders
4	2019-03-25	Eric Werness	Incoming ray flags shouldn’t be exposed in Callable shaders
5	2020-09-17	Daniel Koch	Add edits for the Location decoration (SPIR #583)