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

14

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

2

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

2

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

4

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

9

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

2

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

3

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

2

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

4

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

5

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

4

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

4

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

5

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

5

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

5

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

5

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

5

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

5

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

5

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

5

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

4

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

5

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

5

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

4

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

4

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

5

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

5

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.