RTCFORWARDOCCLUDED1(3embree4)

💅 rtcForwardOccluded1/Ex — forwards a single ray to new scene from user geometry callback

ok so bestie, we're in the Embree Ray Tracing Kernels 4 manual and this one is chef's kiss niche but so important. It's rtcForwardOccluded1/Ex, and it does exactly one gorgeous thing: it takes a ray and forwards it into a whole new scene from inside a user geometry callback. Main character energy fr fr. 🦋

✨ SYNOPSIS ✨

#include <embree4/rtcore.h>

void rtcForwardOccluded1(
  const struct RTCOccludedFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay* ray,
  unsigned int instID
);

void rtcForwardOccluded1Ex(
  const struct RTCOccludedFunctionNArguments* args,
  RTCScene scene,
  struct RTCRay* ray,
  unsigned int instID,
  unsigned int instPrimID
);

🌸 DESCRIPTION 🌸

So rtcForwardOccluded1 and rtcForwardOccluded1Ex forward the traversal of a transformed ray (that's the ray argument) into a scene (that's the scene argument) — and they do it from a user geometry callback. It's giving "hey, take this ray, I trust you with it."

Here's the tea though, and it's a hard rule: this function can only get invoked from a user geometry callback for a ray traversal that was initiated with the rtcOccluded1 function. No sneaking it in anywhere else. Also, the callback arguments structure of the callback invokation has to get passed to the ray forwarding (that's the args argument). And listen — your user geometry callback should instantly terminate after invoking the rtcForwardOccluded1/Ex function. Like, hit the road immediately. Don't stick around.

Now, about the ray: only the ray origin and ray direction members of the ray argument are used for forwarding. Everything else? All those additional ray properties are inherited from the initial ray traversal invokation of rtcOccluded1. So don't be out here thinking you can sneak extra stuff in through the ray struct. It's not the vibe. 🙈

The implementation of the rtcForwardOccluded1 function recursively continues the ray traversal into the specified scene and pushes the provided instance ID (the instID argument) to the instance ID stack. Hit information gets updated into the ray structure that was passed to the original rtcOccluded1 invokation. So it all flows back to where it started — cute, right?

What's this even for, you ask? Bestie, it's for implementing user defined instancing using user geometries. You can transform the ray in a special way, and/or pick between different scenes to instantiate. Iconic.

And for user defined instance arrays? The rtcForwardIntersect1Ex 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. Periodt. 👑

⚠️ okay important technical moment, no cap: when you're using Embree on the CPU, it is possible to recursively invoke rtcOccluded1 directly from a user geometry callback. BUT. When SYCL is used, recursively tracing rays is not directly supported, and the rtcForwardOccluded1/Ex function must be used. So SYCL girlies, this is your only lane. 💀

Also — don't forget — the ray structure must be aligned to 16 bytes. That's not a suggestion, that's a requirement. ✨

💀 EXIT STATUS 💀

For performance reasons, this function does not do any error checks. So it will not set any error flags on failure. It's fast, it's fearless, it's not gonna tell you when things go wrong. You've been warned, bestie. 😭

🔥 SEE ALSO 🔥

• [rtcOccluded1]
• [RTCRay]

and that's the whole page, my love 🫶 go forth and forward those rays responsibly. this was rtcForwardOccluded1/Ex(3) from the Embree Ray Tracing Kernels 4 manual — mwah, catch you in the next one 💖🎀