RTCSETGEOMETRYINTERSECTFILTERFUNCTION(3embree3)

💖 rtcSetGeometryIntersectFilterFunction — Embree Ray Tracing Kernels 3, section 3 ✨

okay bestie, sit down, hydrate, because today we're learning how to tell Embree which hits are actually valid. this is rtcSetGeometryIntersectFilterFunction from the Embree Ray Tracing Kernels 3 manual, and it's giving gatekeeper-of-the-hits energy 💅

---

🌸 NAME 🌸

rtcSetGeometryIntersectFilterFunction — sets the intersection filter for the geometry 🎀

---

✨ SYNOPSIS ✨

#include <embree3/rtcore.h>

struct RTCFilterFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  const struct RTCIntersectContext* context;
  struct RTCRayN* ray;
  struct RTCHitN* hit;
  unsigned int N;
};

typedef void (*RTCFilterFunctionN)(
  const struct RTCFilterFunctionNArguments* args
);

void rtcSetGeometryIntersectFilterFunction(
  RTCGeometry geometry,
  RTCFilterFunctionN filter
);

---

🦋 DESCRIPTION 🦋

so rtcSetGeometryIntersectFilterFunction is literally the function that registers an intersection filter callback (that's the filter argument, bestie) for whichever geometry you point at (the geometry argument). one geometry, one callback, that's the rule 💖

only one callback per geometry, no cap. register another one and it just overwrites the one you had before. pass NULL as the function pointer and boom, the registered callback is disabled. gone. bye 👋

the intersection filter you registered gets invoked for every single hit that shows up during rtcIntersect-type ray queries, and it gets to accept or reject that hit. iconic. what's it for? defining a silhouette for a primitive and rejecting hits that fall outside it! like, imagine a tree leaf modeled with an alpha texture that decides whether hit points are inside or outside the leaf. that's the vibe 🌿

⚠️ okay important, listen up: if the RTC_BUILD_QUALITY_HIGH mode is set, filter functions may get called multiple times for the same primitive hit. AND rays hitting exactly the edge might also report two hits for the same surface. so for certain use cases the application may have to work around this limitation by collecting already reported hits (geomID/primID pairs) and ignoring duplicates. yes, you have to do that yourself. no, it's not a bug, it's a limitation. periodt 😭

---

🎀 the arguments struct, explained 🎀

the filter callback is of type RTCFilterFunctionN and it gets handed a bunch of arguments through the RTCFilterFunctionNArguments structure. let's break it down, one member at a time, no skipping 🔥

• valid — points to an integer valid mask. 0 means invalid, -1 means valid. that's it, that's the whole scale 🫶
• geometryUserPtr — a user pointer, optionally set per geometry through the rtcSetGeometryUserData function. your lil custom data slot 💜
• context — points to the intersection context passed to the ray query function.
• ray — points to N rays in SOA layout.
• hit — points to N hits in SOA layout, ready to be tested.
• N — the number of rays and hits in ray and hit. same N for both, they match 🌈

a few more things you gotta know:

• the hit distance is provided as the tfar value of the ray.
• if the hit geometry is instanced, the instID member of the ray is valid, and the ray and the potential hit are in object space.

---

💅 what your callback actually has to do 💅

your filter callback's whole job is: for each valid ray, decide if it wants to accept or reject the corresponding hit.

• to reject a hit → just write 0 to the integer valid mask of the corresponding ray.
• to accept the hit → just leave the valid mask set to -1. don't touch it, it's already correct ✨

the filter function is also allowed to change the hit and decrease the tfar value of the ray. but bestie — it should not modify other ray data, and it should not touch any inactive components of the ray or hit. stay in your lane 🚧

---

🧚 implementation options (both slay) 🧚

you've got choices, and honestly both eat:

1. implement a single code path that uses the ray access helper functions RTCRay_XXX and hit access helper functions RTCHit_XXX to access ray and hit data. one path, clean, simple, we love her 💖
2. branch to optimized implementations for specific sizes of N and cast the ray and hit inputs to the proper packet types. spicy, fast, main character energy 👑

---

💀 EXIT STATUS 💀

on failure an error code is set, and you can query it using rtcGetDeviceError. so like, if something goes wrong, that's where you go lookin 🔍

---

👑 SEE ALSO 👑

• [rtcSetGeometryOccludedFilterFunction]

---

and that's the whole page, bestie!! 🌈✨

this was rtcSetGeometryIntersectFilterFunction(3) from the Embree Ray Tracing Kernels 3 manual, section 3, and no date was on the tin so we're just vibing with that. go forth and filter those hits responsibly 🫶💖🎀🦋🌸