SPV_KHR_ray_query
SPV_KHR_ray_query
Table of Contents
Name Strings
Contact
Contributors
Status
Version
Dependencies
Overview
Extension Name
New Capabilities
New Instructions
Modifications to the SPIR-V Specification
Validation Rules
Interactions with SPV_KHR_ray_tracing
Issues
Revision History
Name Strings
SPV_KHR_ray_query
Contact
See
Issues
list in the Khronos SPIRV-Registry repository:
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
2025-08-20
Revision
15
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)
Modify the list following the statement:
It is invalid for a pointer to be an operand to any instruction other than:
to include:
OpRayQueryConfirmIntersectionKHR
OpRayQueryInitializeKHR
OpRayQueryTerminateKHR
OpRayQueryGenerateIntersectionKHR
OpRayQueryProceedKHR
OpRayQueryGetIntersectionTypeKHR
OpRayQueryGetRayTMinKHR
OpRayQueryGetRayFlagsKHR
OpRayQueryGetIntersectionTKHR
OpRayQueryGetIntersectionInstanceCustomIndexKHR
OpRayQueryGetIntersectionInstanceIdKHR
OpRayQueryGetIntersectionInstanceShaderBindingTableRecordOffsetKHR
OpRayQueryGetIntersectionGeometryIndexKHR
OpRayQueryGetIntersectionPrimitiveIndexKHR
OpRayQueryGetIntersectionBarycentricsKHR
OpRayQueryGetIntersectionFrontFaceKHR
OpRayQueryGetIntersectionCandidateAABBOpaqueKHR
OpRayQueryGetIntersectionObjectRayDirectionKHR
OpRayQueryGetIntersectionObjectRayOriginKHR
OpRayQueryGetWorldRayDirectionKHR
OpRayQueryGetWorldRayOriginKHR
OpRayQueryGetIntersectionObjectToWorldKHR
OpRayQueryGetIntersectionWorldToObjectKHR
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
are consumed. Such
Result
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
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
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
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
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
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
(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
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
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
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
Cull Mask
Ray Origin
Ray Tmin
Ray Direction
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
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
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
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
Result
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
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
Result Type
Result
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
Result Type
Result
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
Result Type
Result
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
Result Type
Result
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
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
Result Type
Result
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
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
Result Type
Result
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
2019-12-05
Tobias Hector
First draft
2019-12-11
Daniel Koch
add Provisional string to capabilities.
2020-03-06
Ashwin Lele
Reorder operands and rename builtins (!170)
2020-04-14
Jeff Bolz
Fix return type of OpRayQueryGetIntersectionTKHR
2020-06-03
Daniel Koch
Update capabilities tables to match SPIR-V 1.5.
2020-06-05
Hans-Kristian Arntzen
Add conversion from 64-bit acceleration structure pointer
to OpTypeAccelerationStructureKHR
2020-06-12
Daniel Koch
rename OpTypeRayQueryProvisionalKHR → OpTypeRayQueryKHR
refactored common code to include files
2020-07-03
Daniel Koch
Remove provisional notices and update capabilities
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.
15
2025-08-20
Alan Baker
Modify logical pointer validation rules (spir-v#878)
US