SPV_KHR_ray

Name Strings

SPV_KHR_ray_query

Contact

See Issues list in the Khronos SPIRV-Registry repository: https://github.com/KhronosGroup/SPIRV-Registry

Contributors

Contributors to SPV_KHR_ray_tracing
Tobias Hector, AMD
Nicolai Haehnle, AMD
Eric Werness, NVIDIA
Joshua Barczak, Intel
Ashwin Lele, NVIDIA
Daniel Koch, NVIDIA
Hans-Kristian Arntzen, Valve
David McAllister, Qualcomm
Dae Kim, Imagination
Alan Baker, Google
Aleksandra Krstic, Qualcomm

Status

Complete
Ratified by the Khronos Board 2020-11-20

Version

Last Modified Date

2023-01-13

Revision

Dependencies

This extension is written against the Unified SPIR-V Specification, Version 1.5, Revision 1.

This extension requires SPIR-V 1.0.

This extension interacts with SPV_KHR_ray_tracing.

Overview

This extension adds ray query objects to enable ray traversal in any shader stage.

Extension Name

To use this extension within a SPIR-V module, the following OpExtension must be present in the module:

OpExtension "SPV_KHR_ray_query"

New Capabilities

This extension introduces new capabilities:

RayQueryKHR
RayTraversalPrimitiveCullingKHR

New Instructions

Instructions added under the RayQueryKHR capability

OpTypeAccelerationStructureKHR
OpTypeRayQueryKHR
OpRayQueryInitializeKHR
OpRayQueryTerminateKHR
OpRayQueryGenerateIntersectionKHR
OpRayQueryConfirmIntersectionKHR
OpRayQueryProceedKHR
OpRayQueryGetIntersectionTypeKHR
OpRayQueryGetRayTMinKHR
OpRayQueryGetRayFlagsKHR
OpRayQueryGetWorldRayDirectionKHR
OpRayQueryGetWorldRayOriginKHR
OpRayQueryGetIntersectionTKHR
OpRayQueryGetIntersectionInstanceCustomIndexKHR
OpRayQueryGetIntersectionInstanceIdKHR
OpRayQueryGetIntersectionInstanceShaderBindingTableRecordOffsetKHR
OpRayQueryGetIntersectionGeometryIndexKHR
OpRayQueryGetIntersectionPrimitiveIndexKHR
OpRayQueryGetIntersectionBarycentricsKHR
OpRayQueryGetIntersectionFrontFaceKHR
OpRayQueryGetIntersectionCandidateAABBOpaqueKHR
OpRayQueryGetIntersectionObjectRayDirectionKHR
OpRayQueryGetIntersectionObjectRayOriginKHR
OpRayQueryGetIntersectionObjectToWorldKHR
OpRayQueryGetIntersectionWorldToObjectKHR
OpConvertUToAccelerationStructureKHR

Modifications to the SPIR-V Specification

(Add the following terminology to section 2.2.2, Types)

Ray query type: The type returned by OpTypeRayQueryKHR.

(Add to the list of opaque types in section 2.2.2, Types)

OpTypeAccelerationStructureKHR
OpTypeRayQueryKHR

(Modify Section 2.16.1, Universal Validation Rules)

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.

(Add a new sub-section 3.RF, Ray Flags, adding a new table)

3.RF, Ray Flags

Flags controlling the properties of an OpRayQueryInitializeKHR 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.	RayQueryKHR
1	OpaqueKHR Force all intersections with the trace to be opaque. See the Ray Opacity Culling section in the Vulkan API specification.	RayQueryKHR
2	NoOpaqueKHR Force all intersections with the trace to be non-opaque. See the Ray Opacity Culling section in the Vulkan API specification.	RayQueryKHR
4	TerminateOnFirstHitKHR Accept the first hit discovered. See the Ray Closest Hit Determination section in the Vulkan API specification.	RayQueryKHR
8	SkipClosestHitShaderKHR Do not execute a closest hit shader. See the Ray Result Determination section in the Vulkan API specification.	RayQueryKHR
16	CullBackFacingTrianglesKHR Do not intersect with the back face of triangles. See the Ray Face Culling section in the Vulkan API specification.	RayQueryKHR
32	CullFrontFacingTrianglesKHR Do not intersect with the front face of triangles. See the Ray Face Culling section in the Vulkan API specification.	RayQueryKHR
64	CullOpaqueKHR Do not intersect with opaque geometry. See the Ray Opacity Culling section in the Vulkan API specification.	RayQueryKHR
128	CullNoOpaqueKHR Do not intersect with non-opaque geometry. See the Ray Opacity Culling section in the Vulkan API specification.	RayQueryKHR
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

Ray Flags

Enabling Capabilities

NoneKHR
No flags specified.

RayQueryKHR

OpaqueKHR
Force all intersections with the trace to be opaque.
See the Ray Opacity Culling section in the Vulkan API specification.

RayQueryKHR

NoOpaqueKHR
Force all intersections with the trace to be non-opaque.
See the Ray Opacity Culling section in the Vulkan API specification.

RayQueryKHR

TerminateOnFirstHitKHR
Accept the first hit discovered.
See the Ray Closest Hit Determination section in the Vulkan API specification.

RayQueryKHR

SkipClosestHitShaderKHR
Do not execute a closest hit shader.
See the Ray Result Determination section in the Vulkan API specification.

RayQueryKHR

CullBackFacingTrianglesKHR
Do not intersect with the back face of triangles.
See the Ray Face Culling section in the Vulkan API specification.

RayQueryKHR

CullFrontFacingTrianglesKHR
Do not intersect with the front face of triangles.
See the Ray Face Culling section in the Vulkan API specification.

RayQueryKHR

CullOpaqueKHR
Do not intersect with opaque geometry.
See the Ray Opacity Culling section in the Vulkan API specification.

RayQueryKHR

128

CullNoOpaqueKHR
Do not intersect with non-opaque geometry.
See the Ray Opacity Culling section in the Vulkan API specification.

RayQueryKHR

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.RQIntersection, Ray Query Intersection, adding a new table)

Identifies which intersection should be returned from a ray query.

Ray Query Intersection	Enabling Capabilities
0	RayQueryCandidateIntersectionKHR Identifies the current candidate intersection being considered, valid when OpRayQueryProceedKHR returns true.	RayQueryKHR
1	RayQueryCommittedIntersectionKHR Identifies the last intersection committed that is being considered, valid when OpRayQueryGetCommittedIntersectionTypeKHR does not return RayQueryCommittedIntersectionNoneKHR.	RayQueryKHR

Ray Query Intersection

Enabling Capabilities

RayQueryCandidateIntersectionKHR
Identifies the current candidate intersection being considered, valid when OpRayQueryProceedKHR returns true.

RayQueryKHR

RayQueryCommittedIntersectionKHR
Identifies the last intersection committed that is being considered, valid when OpRayQueryGetCommittedIntersectionTypeKHR does not return RayQueryCommittedIntersectionNoneKHR.

RayQueryKHR

(Add a new sub-section 3.RQCommitted, Ray Query Committed Intersection Type, adding a new table)

Describes the type of the intersection currently committed in a ray query.

Ray Query Committed Intersection Type	Enabling Capabilities
0	RayQueryCommittedIntersectionNoneKHR No intersection is committed.	RayQueryKHR
1	RayQueryCommittedIntersectionTriangleKHR An intersection with a triangle has been committed.	RayQueryKHR
2	RayQueryCommittedIntersectionGeneratedKHR A user-generated intersection has been committed.	RayQueryKHR

Ray Query Committed Intersection Type

Enabling Capabilities

RayQueryCommittedIntersectionNoneKHR
No intersection is committed.

RayQueryKHR

RayQueryCommittedIntersectionTriangleKHR
An intersection with a triangle has been committed.

RayQueryKHR

RayQueryCommittedIntersectionGeneratedKHR
A user-generated intersection has been committed.

RayQueryKHR

(Add a new sub-section 3.RQCandidate, Ray Query Candidate Intersection Type, adding a new table)

Describes the type of the intersection which is currently the candidate in a ray query.

Ray Query Candidate Intersection Type	Enabling Capabilities
0	RayQueryCandidateIntersectionTriangleKHR A potential intersection with a triangle is being considered.	RayQueryKHR
1	RayQueryCandidateIntersectionAABBKHR A potential intersection with an axis-aligned bounding box is being considered.	RayQueryKHR

Ray Query Candidate Intersection Type

Enabling Capabilities

RayQueryCandidateIntersectionTriangleKHR
A potential intersection with a triangle is being considered.

RayQueryKHR

RayQueryCandidateIntersectionAABBKHR
A potential intersection with an axis-aligned bounding box is being considered.

RayQueryKHR

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

Capability	Implicitly Declares
4472	RayQueryKHR Uses Ray Query	Shader
4478	RayTraversalPrimitiveCullingKHR Uses SkipAABBsKHR or SkipTrianglesKHR	RayQueryKHR

Capability

Implicitly Declares

4472

RayQueryKHR
Uses Ray Query

Shader

4478

RayTraversalPrimitiveCullingKHR
Uses SkipAABBsKHR or SkipTrianglesKHR

RayQueryKHR

(Modify Section 3.36.6, Type-Declaration Instructions, adding two new tables)

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:
RayQueryKHR

5341

<id> Result

OpTypeRayQueryKHR

Declares a ray query type which is an opaque object representing a ray traversal.

This type is opaque: values of this type have no defined physical size or bit pattern.

Capability:
RayQueryKHR

4472

<id> Result

(Add the following line to the description of OpTypePointer, in Section 3.32.6, Type-Declaration Instructions)

If Type is OpTypeRayQueryKHR, Storage Class must be Private or Function.

(Add the following line to the description of OpStore and OpLoad, in Section 3.32.8, Memory Instructions)

The Type operand to the OpTypePointer used for Pointer must not be OpTypeRayQueryKHR.

(Add the following line to the description of OpCopyMemory and OpCopyMemorySized, in Section 3.32.8, Memory Instructions)

The Type operand to the OpTypePointer used for Target or Source must not be OpTypeRayQueryKHR.

(Modify Section 3.36.11, Conversion Instructions, adding a new table)

OpConvertUToAccelerationStructureKHR

Converts a 64-bit integer into an OpTypeAccelerationStructureKHR.

Acceleration Structure must either be a 64-bit scalar of integer type, whose Signedness operand is 0, or a 2-component vector of 32-bit integer type, whose Signedness operand is 0.
A vector value input behaves as-if OpBitcast converts the value to a 64-bit scalar integer first.
Acceleration Structure represents the address of a valid acceleration structure.
Refer to the client API specification for details.

Result Type must be an OpTypeAccelerationStructureKHR.

Capability:
RayQueryKHR

4447

<id> Result Type

<id> Result

<id> Acceleration Structure

(Add a new sub section 3.36.RQInstructions, Ray Query Instructions)

OpRayQueryInitializeKHR

Initialize a ray query object, defining parameters of traversal. After this call, a new ray trace can be performed with OpRayQueryProceedKHR. Any previous traversal state stored in the object is lost.

Ray Query is a pointer to the ray query to initialize.

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.

Ray Origin, Ray Tmin, Ray Direction, and Ray Tmax control the basic parameters of the ray to be traced.

Ray Flags and Cull Mask 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.
Ray Origin and Ray Direction must be a 32-bit floating-point type 3-component vector.

Ray Tmin and Ray Tmax must be a 32-bit floating-point type scalar.

Capability:
RayQueryKHR

4473

<id> Ray Query

<id> Acceleration Structure

<id> Ray Flags

<id> Cull Mask

<id> Ray Origin

<id> Ray Tmin

<id> Ray Direction

<id> Ray Tmax

OpRayQueryTerminateKHR

Terminates further execution of a ray query; further calls to OpRayQueryProceed will return false. Refer to the client API specification for more details.

Ray Query is a pointer to the ray query to terminate.

Behavior is undefined if the value returned by any prior execution of OpRayQueryProceedKHR with the same ray query object was not true.

Capability:
RayQueryKHR

4474

<id> Ray Query

OpRayQueryGenerateIntersectionKHR

Adds a candidate generated intersection to the ray query to be included in the determination of the closest hit for a ray query.

Ray Query is a pointer to the ray query to generate an intersection candidate for.

Hit T is the floating point parametric value along ray for the intersection.

Hit T must be a 32-bit floating-point type scalar.

Behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true.
Behavior is undefined if the Ray Query Candidate Intersection Type is not RayQueryCandidateIntersectionAABBKHR.

Capability:
RayQueryKHR

4475

<id> Ray Query

<id> Hit T

OpRayQueryConfirmIntersectionKHR

Confirms a triangle intersection to be included in the determination of the closest hit for a ray query.

Ray Query is a pointer to the ray query to confirm the hit to.

Behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true.
Ray Query Candidate Intersection Type must be RayQueryCandidateIntersectionTriangleKHR.

Capability:
RayQueryKHR

4476

<id> Ray Query

OpRayQueryProceedKHR

Allow traversal to proceed. Returns true if traversal is incomplete, and false when it has completed.

Ray Query is a pointer to the ray query to continue traversal on.

Behavior is undefined if a previous call to OpRayQueryProceedKHR with the same ray query object returned false.
Result Type must be a Boolean type.

Capability:
RayQueryKHR

4477

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetIntersectionTypeKHR

Returns the type of the current candidate or committed intersection.

Result describes the type of the intersection in the ray query object.
If Intersection is RayQueryCandidateIntersectionKHR, it returns one of the Ray Query Candidate Intersection Types.
If Intersection is RayQueryCommittedIntersectionKHR, it returns one of the Ray Query Committed Intersection Types.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true.

Capability:
RayQueryKHR

4479

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetRayTMinKHR

Returns the Ray Tmin value used by the ray query.

Result returns the Ray Tmin value used by the ray query.

Result Type must be a 32-bit floating-point type scalar.

Ray Query is a pointer to the ray query object.

Capability:
RayQueryKHR

6016

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetRayFlagsKHR

Returns the Ray Flags used by the ray query.

Result returns the Ray Flag values used by the ray query.

Result Type must be a 32-bit integer type scalar.

Ray Query is a pointer to the ray query object.

Capability:
RayQueryKHR

6017

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetIntersectionTKHR

Gets the T value for the current or previous intersection considered in a ray query.

Result is the returned T value.

Result Type must be a 32-bit floating-point type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, if the last value returned by such an execution of OpRayQueryProceedKHR was not true, or the current intersection candidate does not have a Ray Query Candidate Intersection Type of RayQueryCandidateIntersectionTriangleKHR. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6018

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionInstanceCustomIndexKHR

Gets the custom index of the instance for the current intersection considered in a ray query.

Result is the returned custom instance index.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6019

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionInstanceIdKHR

Gets the id of the instance for the current intersection considered in a ray query.

Result is the returned instance id.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6020

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionInstanceShaderBindingTableRecordOffsetKHR

Gets the shader binding table record offset for the current intersection considered in a ray query.

Result is the returned instance id.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6021

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionGeometryIndexKHR

Gets the geometry index for the current intersection considered in a ray query.

Result is the returned geometry index.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6022

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionPrimitiveIndexKHR

Gets the primitive index for the current intersection considered in a ray query.

Result is the returned primitive index.

Result Type must be a 32-bit integer type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6023

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionBarycentricsKHR

Gets the second and third barycentric coordinates of the current intersection considered in a ray query against the primitive it hit.

Result is the returned barycentric coordinates.

Result Type must be a 32-bit floating-point type 2-component vector.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, if the last value returned by such an execution of OpRayQueryProceedKHR was not true, or the current intersection candidate does not have a Ray Query Candidate Intersection Type of RayQueryCandidateIntersectionTriangleKHR. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR), or if the Ray Query Committed Intersection Type is not RayQueryCommittedIntersectionTriangleKHR.

Capability:
RayQueryKHR

6024

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionFrontFaceKHR

Gets a boolean indicating whether the current intersection considered in a ray query was with the front face or back face of a primitive.

Result is true if the intersection was with the front face of a primitive, or false otherwise.

Result Type must be a boolean type scalar.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, if the last value returned by such an execution of OpRayQueryProceedKHR was not true, or the current intersection candidate does not have a Ray Query Candidate Intersection Type of RayQueryCandidateIntersectionTriangleKHR. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR), or if the Ray Query Committed Intersection Type is not RayQueryCommittedIntersectionTriangleKHR.

Capability:
RayQueryKHR

6025

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionCandidateAABBOpaqueKHR

Gets a boolean indicating whether a candidate intersection considered in a ray query was with an opaque AABB or not.

Result is true if the intersection was with an opaque AABB, or false otherwise.

Result Type must be a boolean type scalar.

Ray Query is a pointer to the ray query object.

Capability:
RayQueryKHR

6026

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetIntersectionObjectRayDirectionKHR

Gets the object-space ray direction for the current intersection considered in a ray query.

Result is the returned ray direction.

Result Type must be a 32-bit floating-point type 3-component vector.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6027

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionObjectRayOriginKHR

Gets the object-space ray origin for the current intersection considered in a ray query.

Result is the returned ray origin.

Result Type must be a 32-bit floating-point type 3-component vector.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6028

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetWorldRayDirectionKHR

Gets the world-space direction for the ray traced in a ray query.

Result is the returned ray direction.

Result Type must be a 32-bit floating-point type 3-component vector.

Ray Query is a pointer to the ray query object.

Capability:
RayQueryKHR

6029

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetWorldRayOriginKHR

Gets the world-space origin for the ray traced in a ray query.

Result is the returned ray origin.

Result Type must be a 32-bit floating-point type 3-component vector.

Ray Query is a pointer to the ray query object.

Capability:
RayQueryKHR

6030

<id> Result Type

Result <id>

<id> Ray Query

OpRayQueryGetIntersectionObjectToWorldKHR

Gets a matrix that transforms values to world-space from the object-space of the current intersection considered in a ray query.

Result is the returned matrix.

Result Type must be a matrix with a Column Count of 4, and a Column Type that is a vector type with a Component Type that is a 32-bit floating-point type and a Component Count of 3.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6031

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

OpRayQueryGetIntersectionWorldToObjectKHR

Gets a matrix that transforms values from world-space to the object-space of the current intersection considered in a ray query.

Result is the returned matrix.

Result Type must be a matrix with a Column Count of 4, and a Column Type that is a vector type with a Component Type that is a 32-bit floating-point type and a Component Count of 3.

Intersection must be the <id> of a constant instruction with a 32-bit scalar integer type.

Intersection identifies which intersection values should be returned for, either the current candidate or the closest recorded hit so far; see Ray Query Intersection.

Ray Query is a pointer to the ray query object.

If Intersection is RayQueryCandidateIntersectionKHR, behavior is undefined if OpRayQueryProceedKHR was not executed on the same ray query object, or if the last value returned by such an execution of OpRayQueryProceedKHR was not true. If Intersection is RayQueryCommittedIntersectionKHR, behavior is undefined if there is no current committed intersection (see OpRayQueryGetIntersectionTypeKHR).

Capability:
RayQueryKHR

6032

<id> Result Type

Result <id>

<id> Ray Query

<id> Intersection

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_query"

Interactions with SPV_KHR_ray_tracing

OpTypeAccelerationStructureKHR, RayTraversalPrimitiveCullingKHR, OpConvertUToAccelerationStructureKHR and the Ray Flags are added by both this extension and SPV_KHR_ray_tracing; 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_tracing is not supported, ignore any references to OpTraceRayKHR.

Issues

1) What are the differences between provisional and final?

Discussion:

rename OpTypeRayQueryProvisionalKHR to OpTypeRayQueryKHR as was originally intended. Seems like it fell victim to an overreaching seach and replace when this was made provisional.
change RayQueryProvisionalKHR to RayQueryKHR and assign new token (4472)
add OpConvertUToAccelerationStructureKHR (4447) instruction to convert 64-bit integer to OpTypeAccelerationStructureKHR to enable query by handle

Revision History

Rev	Date	Author	Changes
1	2019-12-05	Tobias Hector	First draft
2	2019-12-11	Daniel Koch	add Provisional string to capabilities.
3	2020-03-06	Ashwin Lele	Reorder operands and rename builtins (!170)
4	2020-04-14	Jeff Bolz	Fix return type of OpRayQueryGetIntersectionTKHR
5	2020-06-03	Daniel Koch	Update capabilities tables to match SPIR-V 1.5.
6	2020-06-05	Hans-Kristian Arntzen	Add conversion from 64-bit acceleration structure pointer to OpTypeAccelerationStructureKHR
7	2020-06-12	Daniel Koch	rename OpTypeRayQueryProvisionalKHR → OpTypeRayQueryKHR refactored common code to include files
8	2020-07-03	Daniel Koch	Remove provisional notices and update capabilities
9	2020-07-10	Tobias Hector	Clarify that subset of bits are used for cull mask
10	2020-07-22	David McAllister	Disallow querying candidate T value for AABB primitives (!191)
11	2021-02-19	Dae Kim	Fix barycentric coordinates retrieved for OpRayQueryGetIntersectionBarycentricsKHR (!203)
12	2021-09-08	Daniel Koch	replace references to nonexistent OpRayQueryCommittedTypeKHR (GH#128)
13	2022-05-27	Daniel Koch	disallow more combinations of ray flags (vk-gl-cts#3647)
14	2023-01-13	Daniel Koch	Follow SPIR-V conventions for undefined behavior.