RTCSETGEOMETRYINTERSECTFUNCTION(3embree3)

💖 rtcSetGeometryIntersectFunction — bestie edition 💖

okay so you're in the Embree Ray Tracing Kernels 3 manual (yes, the 3embree3 one, she's iconic) and you wanna teach your own geometry how to get hit by a ray?? say less, this page is literally for you 🫶

---

✨ NAME ✨

rtcSetGeometryIntersectFunction — sets the callback function to intersect a user geometry 💅

---

✨ SYNOPSIS ✨

#include <embree3/rtcore.h>

struct RTCIntersectFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  unsigned int primID;
  struct RTCIntersectContext* context;
  struct RTCRayHitN* rayhit;
  unsigned int N;
  unsigned int geomID;
};

typedef void (*RTCIntersectFunctionN)(
  const struct RTCIntersectFunctionNArguments* args
);

void rtcSetGeometryIntersectFunction(
  RTCGeometry geometry,
  RTCIntersectFunctionN intersect
);

---

✨ DESCRIPTION ✨

so basically rtcSetGeometryIntersectFunction registers a ray/primitive intersection callback function (that's the intersect argument, bestie) for the user geometry you point at with the geometry argument. it's giving "here's how you hit me" energy 🎀

only one callback function can be registered per geometry, no cap — if you invoke this again it just overwrites whatever callback was set before. and if you pass NULL as the function pointer? that disables the registered callback function entirely. bye bye callback 👋

the registered callback function gets invoked by rtcIntersect-type ray queries to calculate the intersection of a ray packet of variable size with one user-defined primitive. the callback function of type RTCIntersectFunctionN gets handed a bunch of arguments through the RTCIntersectFunctionNArguments structure, so let's break down the group chat:

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

so the ray component of the rayhit structure contains valid data — specifically the tfar value is the current closest hit distance found. but all the data inside the hit component of the rayhit structure are undefined and should not be read by the function. do not read them. i'm so serious 😭

now the actual job of the callback function: intersect each active ray from the ray packet with the specified user primitive. that's it, that's the task, main character energy ✨

• if the user-defined primitive is missed by a ray of the ray packet, the function should return without modifying the ray or hit. nothing happened, no notes 💀
• if an intersection of the user-defined primitive with the ray was found in the valid range (from tnear to tfar), it should update the hit distance of the ray (the tfar member) and the hit (u, v, Ng, instID, geomID, primID members).

and here's the sneaky part — the currently intersected instance is stored in the instID field of the intersection context, and you must deep copy that into the instID member of the hit. must. deep copy. do it 🫡

also, because a primitive might have multiple intersections with a ray, the intersection filter function needs to be invoked by the user geometry intersection callback for each encountered intersection — that's only if filtering of intersections is desired, iykyk. you can achieve that through the rtcFilterIntersection call 🌸

and the good news bestie: within the user geometry intersect function, it is safe to trace new rays and create new scenes and geometries. go off, live your truth 🔥

---

✨ EXIT STATUS ✨

if something goes wrong, on failure an error code is set that can be queried using rtcGetDeviceError. so like, check that if things feel off 🙈

---

✨ SEE ALSO ✨

• [rtcSetGeometryOccludedFunction]
• [rtcSetGeometryUserData]
• [rtcFilterIntersection]

---

ok that's the whole page, you ate that fr fr 💖

this was rtcSetGeometryIntersectFunction from the Embree Ray Tracing Kernels 3 manual — and yeah, the footer at the bottom is just that same rtcSetGeo...ctFunction(3) title-and-section line doing its little truncated thing, she's shy but she's there 🎀 byeee, go intersect something iconic 👑