RTCSETGEOMETRYINTERSECTFILTERFUNCTION(3)

✨ NAME ✨

rtcSetGeometryIntersectFilterFunction — okay bestie, this one sets the intersection filter for the geometry 💅

---

🌸 SYNOPSIS 🌸

#include <embree4/rtcore.h>

struct RTCFilterFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  const struct RTCRayQueryContext* 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 the function that registers an intersection filter callback function (that's the filter argument, bestie) for whichever geometry you point at (the geometry argument 🎯).

One (1) single callback per geometry, that's the rule — if you call it again it just overwrites the old one, no stacking, no collecting, it's giving "there can only be one" 👑. And if you pass NULL as the function pointer? Boom, the registered callback is disabled, gone, bye 💀.

Here's the tea: the intersection filter function you registered gets invoked for every hit that shows up during the rtcIntersect-type ray queries, and it gets to accept or reject that hit. It's literally main character energy for your primitives. What's it for? Think defining a silhouette for a primitive and rejecting hits that land outside that silhouette 🦋. 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.

⚠️ Real talk, this next part matters: if the RTC_BUILD_QUALITY_HIGH mode is set, the filter functions may be called multiple times for the same primitive hit. And on top of that, rays hitting exactly the edge might also report two hits for the same surface. For certain use cases the application may have to work around this limitation by collecting already reported hits (the geomID/primID pairs, iykyk) and ignoring the duplicates 🙈.

---

🎀 The Callback Arguments 🎀

The filter function callback, which is of type RTCFilterFunctionN, gets handed a bunch of arguments through the RTCFilterFunctionNArguments structure. Let's break it down, no gatekeeping:

• The valid parameter points to an integer valid mask — 0 means invalid and -1 means valid ✅
• The geometryUserPtr member is a user pointer that you can optionally set per geometry through the rtcSetGeometryUserData function 🫶
• The context member points to the ray query context that got passed to the ray query function 🌈
• The ray parameter points to N rays in SOA layout ⭐
• The hit parameter points to N hits in SOA layout to test 🎯
• The N parameter is the number of rays and hits inside ray and hit 🔢
• 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 Filter Callback Actually Does 💅

The filter callback function has one job: for each valid ray, check whether it wants to accept or reject the corresponding hit.

• To reject a hit, the filter callback function just has to write 0 to the integer valid mask of the corresponding ray ✋
• To accept the hit, it just has to leave the valid mask set to -1 💚

And here's a lil bonus when you accept: the filter function is further allowed to change the hit and decrease the tfar value of the ray — but bestie, it should not modify other ray data, nor any inactive components of the ray or hit. Stay in your lane, respectfully 🙏.

---

🧚 How To Write The Implementation 🧚

The implementation of the filter function has options, and honestly? Both are valid:

• You can choose to implement a single code path that uses the ray access helper functions RTCRay_XXX and the hit access helper functions RTCHit_XXX to access the ray and hit data 🫧
• Or, alternatively, the code can branch to optimized implementations for specific sizes of N and cast the ray and hit inputs to the proper packet types 🚀

Pick your fighter, both slay 🔥

---

💀 EXIT STATUS 💀

On failure an error code is set that can be queried using rtcGetDeviceError. So like, if something goes sideways, that's where you go looking 🔍

---

👑 SEE ALSO 👑

• rtcSetGeometryOccludedFilterFunction

---

And that's the whole page, bestie! This was rtcSetGeometryIntersectFilterFunction(3) from the Embree Ray Tracing Kernels 4 manual — the footer's lil abbreviation is rtcSetGeo...erFunction(3), which is just the name getting squished to fit, no cap 😭. Go forth and filter those hits ✨💖🎀