Implement the `TraceRay` HLSL Function

[farzonl]

• Implement TraceRay clang builtin,
• Link TraceRay clang builtin with hlsl_intrinsics.h
• Add sema checks for TraceRay to CheckHLSLBuiltinFunctionCall in SemaChecking.cpp
• Add codegen for TraceRay to EmitHLSLBuiltinExpr in CGBuiltin.cpp
• Add codegen tests to clang/test/CodeGenHLSL/builtins/TraceRay.hlsl
• Add sema tests to clang/test/SemaHLSL/BuiltIns/TraceRay-errors.hlsl
• Create the int_dx_TraceRay intrinsic in IntrinsicsDirectX.td
• Create the DXILOpMapping of int_dx_TraceRay to 157 in DXIL.td
• Create the TraceRay.ll and TraceRay_errors.ll tests in llvm/test/CodeGen/DirectX/
• Create the int_spv_TraceRay intrinsic in IntrinsicsSPIRV.td
• In SPIRVInstructionSelector.cpp create the TraceRay lowering and map it to int_spv_TraceRay in SPIRVInstructionSelector::selectIntrinsic.
• Create SPIR-V backend test case in llvm/test/CodeGen/SPIRV/hlsl-intrinsics/TraceRay.ll

DirectX

DXIL Opcode	DXIL OpName	Shader Model	Shader Stages
157	TraceRay	6.3	('library', 'raygeneration', 'closesthit', 'miss')

SPIR-V

OpTraceRayKHR:

Description:

Reserved.

Capability:
RayTracingKHR

Reserved.

Word Count	Opcode	Results	Operands
12	4445	<id> Accel	<id> Ray Flags	<id> Cull Mask	<id> SBT Offset	<id> SBT Stride	<id> Miss Index	<id> Ray Origin	<id> Ray Tmin	<id> Ray Direction	<id> Ray Tmax	<id> Payload

Test Case(s)

Example 1

//dxc TraceRay_test.hlsl -T lib_6_8 -enable-16bit-types -O0

struct [raypayload] RayPayload
{
	float4 color : write(caller) : read(closesthit);
	float distance : write(caller) : read(closesthit);
};

[shader("raygeneration")]
void fn() {
	RaytracingAccelerationStructure p1;
	uint p2;
	uint p3;
	uint p4;
	uint p5;
	uint p6;
	RayDesc p7;
	RayPayload p8;
	TraceRay(p1, p2, p3, p4, p5, p6, p7, p8);
}

HLSL:

Sends a ray into a search for hits in an acceleration structure.

Syntax

This intrinsic function definition is equivalent to the following function template:

Template<payload_t>
void TraceRay(RaytracingAccelerationStructure AccelerationStructure,
              uint RayFlags,
              uint InstanceInclusionMask,
              uint RayContributionToHitGroupIndex,
              uint MultiplierForGeometryContributionToHitGroupIndex,
              uint MissShaderIndex,
              RayDesc Ray,
              inout payload_t Payload);

Parameters

AccelerationStructure

The top-level acceleration structure to use. Specifying a NULL acceleration structure forces a miss.

RayFlags

Valid combination of ray_flag values. Only defined ray flags are propagated by the system, i.e. are visible to the RayFlags shader intrinsic.

InstanceInclusionMask

An unsigned integer, the bottom 8 bits of which are used to include or reject geometry instances based on the InstanceMask in each instance. For example:

if(!((InstanceInclusionMask & InstanceMask) & 0xff)) { //ignore intersection }

RayContributionToHitGroupIndex

An unsigned integer specifying the offset to add into addressing calculations within shader tables for hit group indexing. Only the bottom 4 bits of this value are used.

MultiplierForGeometryContributionToHitGroupIndex

An unsigned integer specifying the stride to multiply by GeometryContributionToHitGroupIndex, which is just the 0 based index the geometry was supplied by the app into its bottom-level acceleration structure. Only the bottom 16 bits of this multiplier value are used.

MissShaderIndex

An unsigned integer specifying the index of the miss shader within a shader table.

Ray

A RayDesc representing the ray to be traced.

Payload

A user defined ray payload accessed both for both input and output by shaders invoked during raytracing. After TraceRay completes, the caller can access the payload as well.

Return Value

void

Remarks

This function can be called from the following raytracing shader types:

• Closest Hit Shader
• Miss Shader
• Ray Generation Shader

See also

Direct3D 12 Raytracing HLSL Reference