<table border="1" cellspacing="0" cellpadding="8">
<tr>
<th>Issue</th>
<td>
<a href=https://github.com/llvm/llvm-project/issues/99178>99178</a>
</td>
</tr>
<tr>
<th>Summary</th>
<td>
Implement the `TraceRay` HLSL Function
</td>
</tr>
<tr>
<th>Labels</th>
<td>
metabug,
backend:DirectX,
HLSL,
backend:SPIR-V,
bot:HLSL
</td>
</tr>
<tr>
<th>Assignees</th>
<td>
</td>
</tr>
<tr>
<th>Reporter</th>
<td>
farzonl
</td>
</tr>
</table>
<pre>
- [ ] 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](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#OpTraceRayKHR):
## Description:
Reserved.
[Capability](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#Capability):
**RayTracingKHR**
[Reserved](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#Unified).
<table style="width:100%;">
<colgroup>
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
</colgroup>
<thead>
<tr>
<th>Word Count</th>
<th>Opcode</th>
<th>Results</th>
<th>Operands</th>
<th></th>
<th></th>
<th></th>
<th></th>
<th></th>
<th></th>
<th></th>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p>12</p></td>
<td class="tableblock halign-left valign-top"><p>4445</p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Accel</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Ray Flags</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Cull Mask</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>SBT Offset</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>SBT Stride</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Miss Index</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Ray Origin</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Ray Tmin</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Ray Direction</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Ray Tmax</em></p></td>
<td
class="tableblock halign-left valign-top"><p><em><id></em><br />
<em>Payload</em></p></td>
</tr>
</tbody>
</table>
## Test Case(s)
### Example 1
```hlsl
//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](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/ray_flag.md) values. Only defined ray flags are propagated by the system, i.e. are visible to the [RayFlags](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/rayflags.md) 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**](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/raydesc.md) 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**](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/traceray-function.md) 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**](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/closest-hit-shader.md)
* [**Miss Shader**](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/miss-shader.md)
* [**Ray Generation Shader**](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/ray-generation-shader.md)
## See also
<dl> <dt>
[Direct3D 12 Raytracing HLSL Reference](https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src//direct3dhlsl/direct3d-12-raytracing-hlsl-reference.md)
</dt> </dl>
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJzsWl9T4zgS_zTipSspRyYJPPAQwmSGupllC9i5faNku-NokSWfJAO5T3_Vkv8kEJjdrdtZpmqpVIhaUqv7161Wt2zhnCw14hmbnrPpxZFo_MbYs7Ww_zVaHWWm2J6NgE3PgU0v4LKqFVaoPbBZcmtFjtdiy2YJ5EroErJGKi8140uWLIZZn6W-f3MCPEq_oREb5dSd1N5K7WTuxhs2S_ZYLYoCHFYC8g3m9w7Wxj7n7A1RltT_6fPN5_O4xKrRuZdGL4VSNEpqGnWDlQgjpS7HeV0fWi43BZaoX1_qQyX9zkofnmo7rLD82JK_xd6j867lGMBhfEU0xldLU-BH1LQG46sWM8f4qpNlTLi9CtUbnEn_lm0Q83KP7QitNdYd5L60KDyC3yCxldrfFU93u9j0VmyBuOyteiEt5v7XsS_eZnrx6-Xnq_qLqGupS2Jp1q-s5Q1Qz2Q6H4Cn2d9cogcwOoXQxS71rtU_dkYYI3OlHqoX9mF81arG-OrbeLn64XcCdvPz5fXXA7pcaghdl9p52wT3vkGFuTeWvA3yg7rSWso8opW6DBpXogaQvvWQw6KFzfLKWixdsHThQqsXms2S8SEAiMnoK2Qiv0ddBFAhFw6_AWxYm_EVueJoCBC7e0C1PkofnjKeQmeNSJsvgXwCrmracrDT_klUsX2zEQVa-GIKVLuEGy9KdERpGY2GP_hG-yVhtMNoMp2H_k6L0JiN0_Cf8RPG50pmVtgt43PGiTa3YluiRivICAM5V8ah8xvpB1olnQut027NHpxoiJ5EdrqqOzH-9emaTS8YP9l4XzsyMF8xvrJYSuftdny_sUYbNza2bI0zIuu4GoNNGi3XEotJZ7jxxleK8XR_AX5KjPcMhi63sg56hS5gyeIaHdoHLMbt0On5UtQik0r67V8h5A73ICEE-ehzLbYkv9RlEJ9IAK2UbHreCfpXCPVLpDN-2sGQLr3IFILzW4UsvWCcP8rCb1i6mCQJ41OWnjPOWfohjs6NKq1p6l3Cockwp7mcAwn-z9h_xh4ay_jqhT_5DYpiaNmdDpZ--LexBSxNo32cHog7_TEqH-67Rtco716biFbo4pXeH55KLbvX2oeZEvSDoBeUYjsXjRlCRaZMfg8boWSpRwrXHh7ib2_qNlKkS7LnhMel6kGg4v_C-Pj4ePoma5Ys_jRzli6xov98pjxLz2XB-KykX3Gh2JkuM7vnyoG8yHNU-8Pen5CUHqyUKN17F3TZKAVfhLt_74LenN_C1Xrt0P8Ikt54K7sQ-X4l_SKdg0td4NN7l5T205WVpdQ_gqS31Y8hZyy6Qgb__oW9rcS7d9OfxVYZOvJ_j5gv04W9BIEIJHhLSPbLr1sqxpfCIeMnjoqfpKvBII6gQR-eRFUrhAn1zpL4CTdESVvrFE95X8_eUSUfLpBgdAtKZnezuxMYoSYpRpNZJv3Ib2t0MLpqi_d4v0D1qBXbulV-egHXYttBQbXzeRh9ulZG-GPIjTIWKF19tNKTArlQCm2ofNMFWEqa-MlujXxK6A88oJDOC53jn-Myv-jYUSnowr1BqN_5s3Kd05zpBUsWD0YWsNZhFNXnrTTXYutjlRmyknbiTUClsQj1pBe8kdpDzZ-102ft42ft6bP2rG9fiy2V4FDPd0kt6lCf9NT-coif1BPGlyQEfafh-zh8T8P3LHyH-4j6ZA-uHfcZXDBcRna3AjeoCwcCrNiC1N6AAIfC5ptwF7uR8TpOaBA7QIHrkBrv33dstRdPLFncbqTbuWxbtxfDUOBaahl-Sgf4n0Y-CIU63Iv5DcLaKGUepS6HKR6rWgmPwz3Gjka3feey9eI7H_ddMPwOhN-y-EFqvGSHYMJrsY2JYaTt_YUBlzr69qXOVeOk0SE72-ewNIRJ1tAqt-aT9B-pvIsn-Wt8vzTKy1pJtCtjP6Kp0Ns_x0g6Fy_bXh3XOWfA7GW31Kbx0CMNXawY9vm-vz2LfT8LKyr0aF0_9jDs3ezbDYI39UjhA6pXPJBcp3E4hpsac7nehhtX-OmXz59fm7A2Nkfy-Uo6N-5F6Q3crf5VKFlAbqpM6sjDrNuQebdWojx0B1VKv2mycW4qxldfZG6NM2t_YcLF06PUKWd8lSmTUQyP1ALdPSnpbN7G9nC6p0UI-HzVLTeuCGg6_Rp0Y7jSahv3ExZh99IYB4KilzW1KIXHArJt2Fdu6zxWFCDkGMdh0IN0MlPY7Tw2Pe8B-G56BZFbvWI4H4LGYJjDG6uz0kJDo8PztYImY0lnwjLolBnvTQUnkFEYM2t43Mh8E7RvHBakuiSeBYKxYPE3zD2U7Q4D2S7rIBM0mmLRBvttTkJQaESRb_qxY1gZCxiP7zZi7WwIuQ4H0SR8nxzUCxif7a0Rzi0-g-RpvaaNFo8xiJDKUhuLQW_rYkoIB-J-599vRY038AQ3bC2CwIRyjuATRdGeGkVh0TkakQuVNypsGBceOkrdGTfkRa47WSDcbYGk5aUuxxB9esdyx73lPB0owfV78w0O8ocj5B_Q1YWCkHSt4ipb2lOML35XJF6QK0avkw5-a5wPTJPWpYLqgdJ73aNw4JqatOl3r6jriDKBEaF5MySOXwA5me0jWfWIvQ7qs9PiD2AW1QprYQiynf1bbxB7_rAXgYdlKCL1jwToUIqN7xecCnR5G5ss1hYdat9pSPHWG8gQKKnYha07Egc9God2L1C352cwniM3yIyP6Vb4IXXd-PDQ0DSefmbbFi9KqR7MPRZQNOHJou2TmjEs1h7tANqQ-nxH1AIYVmxHXfbW4pcbioceXReZY8oPeZtXOheoPTAOHlGp_dzyGn1jNXwld-066EOJXqvk_vBK2HvX5RHSDRklrZq1MhSwtqZ6lnsOsPaOSuXTzpO0He9cxkIFPknfPsr8rpC3ddJoI_0oChsxfy5muDL6G-Sj7f-mYNdiCx_72u3vEJEcdqgeXwj7LIm9QQShnGHdI8JCsfQD0A8_lPzT83hHk17AhMNQfITiC65xjRZ1jt9Jw645mvDR4Nyj8KDfdrIMGoc7jKANtL9JxaPiLC1O01NxhGeTOZ9MZsnx8exoc5bPsmTGi6yYnE6m2WzC15PTWVbMktOTSZrP8yN5xhN-nMwnM54kcz4bpwlOEXF-fLKeTNN8wo4TrIRUY6UeqrGx5ZF0rsGz09PJ_ORIiQyVCy9PcV6hF1lThhp_yThvX3Jg6aJ_L6Ttie_cvBjWPQ7uOoxn6aIbO704smckxChrSseOEyWdd4NYXnqFZ8MbWgde-wgG7t6EOmqsOnvDvO2rGGHF2hpKQCmrI-XJrlH_hzP-vwAAAP__PMKbNA">