rtcSetGeo...dFunction(3)

💖 rtcSetGeo...dFunction — bestie edition ✨

okay so this is from the Embree Ray Tracing Kernels 4 manual (rtcSetGeo...dFunction(3)), and it's all about teaching your custom geometry how to get occluded. no cap, this one's a vibe. 🦋

---

✨ NAME ✨

rtcSetGeometryOccludedFunction — sets the callback function to test a user geometry for occlusion 💅

---

🎀 SYNOPSIS 🎀

#include <embree4/rtcore.h>

struct RTCOccludedFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  unsigned int primID;
  struct RTCRayQueryContext* context;
  struct RTCRayN* ray;
  unsigned int N;
  unsigned int geomID;
};

typedef void (*RTCOccludedFunctionN)(
  const struct RTCOccludedFunctionNArguments* args
);

void rtcSetGeometryOccludedFunction(
  RTCGeometry geometry,
  RTCOccludedFunctionN filter
);

---

🌸 DESCRIPTION 🌸

so basically, rtcSetGeometryOccludedFunction registers a ray/primitive occlusion callback function (that's the filter argument, bestie) for the user geometry you picked (that's the geometry argument 🫶).

one (1) callback per geometry, periodt. only a single callback function can be registered per geometry, and if you call this again it just overwrites whatever you set before — no stacking, no drama. and if you pass NULL as the function pointer? that disables the registered callback function entirely. bye bestie 👋

the callback you registered gets invoked by rtcOccluded-type ray queries, and its whole job is testing whether the rays of a packet of variable size are occluded by a user-defined primitive. the callback is of type RTCOccludedFunctionN and it gets a bunch of arguments handed to it through the RTCOccludedFunctionNArguments structure. let's break down the cast, iykyk:

• N — the ray packet size
• valid — points to an array of integers saying whether each corresponding ray is valid (-1) or invalid (0)
• geometryUserPtr — points to the geometry user data you set earlier through rtcSetGeometryUserData
• context — points to the ray query context that got passed to the ray query
• ray — points to a ray packet of variable size N
• geomID and primID — identify the geometry ID and primitive ID of the primitive to intersect

---

so what's the actual task here? the callback function has to intersect each active ray from the ray packet with the specified user primitive. and listen:

• if the user-defined primitive is missed by a ray of the ray packet, the function should just return without modifying the ray. leave it alone, it's fine 🧚
• if an intersection of the user-defined primitive with the ray was found in the valid range (from tnear to tfar), it should set the tfar member of the ray to -inf. slay.

⭐ heads up! a primitive might have multiple intersections with a ray, so if you actually want filtering of intersections, the occlusion filter function needs to be invoked by the user geometry occlusion callback for each encountered intersection. you can do that with the rtcInvokeOccludedFilterFromGeometry call.

and the best part: within the user geometry occlusion function, it is safe to trace new rays and create new scenes and geometries. go off, main character energy 👑

---

💀 EXIT STATUS 💀

on failure an error code gets set, and you can go query it with rtcGetDeviceError. not me checking the error code every time 🙈

---

🌈 SEE ALSO 🌈

• [rtcSetGeometryIntersectFunction]
• [rtcSetGeometryUserData]
• [rtcInvokeOccludedFilterFromGeometry]

---

that's the whole page bestie, you ate it 💅✨ this was rtcSetGeo...dFunction(3) from the Embree Ray Tracing Kernels 4 manual — go forth and occlude responsibly 🫶💖🎀