75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
|
# 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
|
||
|
|
```HLSL
|
||
|
|
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`](#struct-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`](#struct-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: <ul><li>kRayFlagNone</li><li>kRayFlagCullBackFacingTriangles</li><li>kRayFlagCullFrontFacingTriangles</li> </ul>|
|
||
|
|
### Returns
|
||
|
|
[`Hit`](#struct-hit) containing geometry information about the hit triangle. When no primitive has intersected with the ray, `hit.IsValid()` returns false.
|
||
|
|
|
||
|
|
## function TraceRayAnyHit
|
||
|
|
```HLSL
|
||
|
|
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`](#struct-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`](#struct-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: <ul><li>kRayFlagNone</li><li>kRayFlagCullBackFacingTriangles</li><li>kRayFlagCullFrontFacingTriangles</li> </ul>|
|
||
|
|
### 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
|
||
|
|
```HLSL
|
||
|
|
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.
|