rtcForwar...4/8/16/Ex(3)

💖 NAME 💖

rtcForwardIntersect4/8/16/Ex — bestie, this one forwards a ray packet to a whole new scene, and you can only do it from inside a user geometry callback ✨

🌸 SYNOPSIS 🌸

#include <embree4/rtcore.h>

void rtcForwardIntersect4(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay4* ray,
  unsigned int instID
);

void rtcForwardIntersect8(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay8* ray,
  unsigned int instID
);

void rtcForwardIntersect16(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay16* ray,
  unsigned int instID,
  unsigned int instPrimID
);

void rtcForwardIntersect4Ex(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay4* ray,
  unsigned int instID,
  unsigned int instPrimID
);

void rtcForwardIntersect8Ex(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay8* ray,
  unsigned int instID,
  unsigned int instPrimID
);

void rtcForwardIntersect16Ex(
  void int* valid,
  const struct RTCIntersectFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay16* ray,
  unsigned int instID,
  unsigned int instPrimID
);

✨ DESCRIPTION ✨

Okay so picture this: you're chilling inside a user geometry callback, and you're like "hmm, this transformed ray packet needs to go check out another scene." That's literally what rtcForwardIntersect4/8/16 and rtcForwardIntersect4/8/16Ex are for, bestie 💅 They forward the traversal of a transformed ray packet (that's your ray argument) into a scene (that's your scene argument), straight from a user geometry callback.

🚨 Real talk: this function can only get invoked from a user geometry callback for a ray traversal that was initiated with rtcIntersect4/8/16. No other vibes allowed.

The callback arguments structure of the callback invocation has to get passed to the ray forwarding (the args argument). And the user geometry callback should instantly terminate after invoking the rtcForwardIntersect4/8/16/Ex function — like, no lingering, no small talk, just go 🙈

Now, the deets: only the ray origin and ray direction members of the ray argument are used for forwarding. Every other ray property is inherited from the initial ray traversal invocation of rtcIntersect4/8/16. So don't stress about packing extras in there, it's giving "inherit from mom" energy 🧚

The implementation of the rtcForwardIntersect4/8/16 function recursively continues the ray traversal into the specified scene and pushes the provided instance ID (the instID argument) onto the instance ID stack. Hit information gets updated into the ray hit structure that was passed to the original rtcIntersect4/8/16 invocation. Iconic.

This function can get used to implement user defined instancing using user geometries — e.g. by transforming the ray in a special way, and/or selecting between different scenes to instantiate. Main character customization energy, honestly 👑

For user defined instance arrays, the rtcForwardIntersect4/8/16Ex variant has an additional instPrimID argument, which gets pushed to the instance primitive ID stack. Instance primitive IDs identify which instance of an instance array was hit. Slay 🌈

When using Embree on the CPU, it is possible to recursively invoke rtcIntersect4/8/16 directly from a user geometry callback. However — and this is the plot twist — when SYCL is used, recursively tracing rays is not directly supported, and the rtcForwardIntersect4/8/16 function must be used. No cap.

And now for the alignment tea, because alignment is that girl:

• For rtcForwardIntersect4 the ray packet must be aligned to 16 bytes.
• For rtcForwardIntersect8 the alignment must be 32 bytes.
• For rtcForwardIntersect16 the alignment must be 64 bytes.

💀 EXIT STATUS 💀

For performance reasons this function does not do any error checks, thus will not set any error flags on failure. So if something goes wrong... it's just gonna be quiet about it 🫶

🦋 SEE ALSO 🦋

• [rtcIntersect4/8/16]

Okay bestie that's the whole page, you're officially fluent in ray packet forwarding. This was rtcForwar...4/8/16/Ex(3) from the Embree Ray Tracing Kernels 4 era — mwah, go forth and forward those rays 💖✨🎀