Unified ray tracing shader code reference

This section presents the different functions and structs provided by the API for tracing rays in a shader.

All types are defined inside the UnifiedRT namespace. In your code, you need to prefix them with UnifiedRT::. Alternatively, you can add using namespace UnifiedRT; after your TraceRayAndQueryHit.hlsl include statement.

function TraceRayClosestHit

Hit TraceRayClosestHit(DispatchInfo dispatchInfo, RayTracingAccelStruct accelStruct, uint instanceMask, Ray ray, uint rayFlags)

Searches for intersections between a ray and an acceleration structure. It returns hit information about the closest triangle encountered along the ray.

Parameters

Type	Name	Description
`DispatchInfo`	dispatchInfo	The dispatch info. Must be the value that is passed by `RayGenExecute`.
`RayTracingAccelStruct`	accelStruct	The acceleration structure to test the ray against.
`uint`	instanceMask	The lower 8 bits of this mask are used to include geometry instances based on the instance mask that was set in `MeshInstanceDesc` for each instance.
`Ray`	ray	Describes the ray segment that is intersected against the acceleration structure.
`uint`	rayFlags	Flags that filter out the triangles that participate in the intersection test. Can be one of the following: kRayFlagNone kRayFlagCullBackFacingTriangles kRayFlagCullFrontFacingTriangles

Returns

Hit containing geometry information about the hit triangle. When no primitive has intersected with the ray, hit.IsValid() returns false.

function TraceRayAnyHit

bool TraceRayAnyHit(DispatchInfo dispatchInfo, RayTracingAccelStruct accelStruct, uint instanceMask, Ray ray, uint rayFlags)

Searches for any intersection between a ray and an acceleration structure. The search ends as soon as a valid triangle hit is found. This function can typically be used to trace shadow rays or perform occlusion queries.

Parameters

Type	Name	Description
`DispatchInfo`	dispatchInfo	The dispatch info. Must be the value that is passed by `RayGenExecute`.
`RayTracingAccelStruct`	accelStruct	The acceleration structure to test the ray against.
`uint`	instanceMask	The lower 8 bits of this mask are used to include geometry instances based on the instance mask that was set in `MeshInstanceDesc` for each instance.
`Ray`	ray	Describes the ray segment that is intersected against the acceleration structure.
`uint`	rayFlags	Flags that filter out the triangles that participate in the intersection test. Can be one of the following: kRayFlagNone kRayFlagCullBackFacingTriangles kRayFlagCullFrontFacingTriangles

Returns

A boolean that is true if any primitive was hit by the ray.

struct Ray

Describes a ray. The tMin and tMax fields define the segment of the ray to be tested against the acceleration structures's primitives. Mathematically, the ray consists of all the points defined as P = ray.origin + t * ray.direction, where ray.tMin ≤ t ≤ ray.tMax.

Fields

Type	Name	Description
`float3`	origin	The ray's origin.
`float3`	direction	The ray's direction.
`float`	tMin	The ray's starting point.
`float`	tMax	The ray's endpoint.

struct DispatchInfo

Provides information about the current thread that is invoked.

Fields

Type	Name	Description
`uint3`	dispatchThreadID	Same semantic as `SV_DispatchThreadID`.
`uint`	localThreadIndex	Same semantic as `SV_GroupIndex`.
`uint3`	dispatchDimensionsInThreads	Total numbers of threads dispatched in the X, Y, and Z workgrid directions.
`uint`	globalThreadIndex	Global thread index that is unique within the workgrid.

struct Hit

Describes a Hit.

Fields

Type	Name	Description
`uint`	instanceID	Matches the `instanceID` supplied from C# in `MeshInstanceDesc.instanceID`.
`uint`	primitiveIndex	Index of the hit triangle in its source Mesh.
`float2`	uvBarycentrics	Barycentric coordinates of the hit triangle.
`float`	hitDistance	Defines the hit position: `hitPos = ray.origin + ray.direction * hit.hitDistance`.
`bool`	isFrontFace	Indicates whether the hit triangle is front-facing or back-facing.

Methods

bool IsValid();

Returns true when a hit has been found. When a hit is invalid hit.instanceID is equal to ~0 and the other fields are undefined.