rtcSetGeo...tFunction(3)

✨ rtcSetGeometryDisplacementFunction ✨

okay bestie, welcome to the Embree Ray Tracing Kernels 4 manual (section 3, the library-call girlies) 💅 this one's all about rtcSetGeometryDisplacementFunction and it's giving subdivision-geometry glow-up energy. no cap.

---

🌸 NAME 🌸

rtcSetGeometryDisplacementFunction — sets the displacement function for a subdivision geometry 🦋

---

🎀 SYNOPSIS 🎀

#include <embree4/rtcore.h>

struct RTCDisplacementFunctionNArguments
{
  void* geometryUserPtr;
  RTCGeometry geometry;
  unsigned int primID;
  unsigned int timeStep;
  const float* u;
  const float* v;
  const float* Ng_x;
  const float* Ng_y;
  const float* Ng_z;
  float* P_x;
  float* P_y;
  float* P_z;
  unsigned int N;
};

typedef void (*RTCDisplacementFunctionN)(
   const struct RTCDisplacementFunctionNArguments* args
);

void rtcSetGeometryDisplacementFunction(
  RTCGeometry geometry,
  RTCDisplacementFunctionN displacement
);

copy that exactly, bestie, every field matters 😭

---

💖 DESCRIPTION 💖

so like, rtcSetGeometryDisplacementFunction registers a displacement callback function (that's the displacement argument) onto the subdivision geometry you picked (that's the geometry argument). iconic behavior honestly.

one callback per geometry, periodt. only a single callback function can be registered per geometry, and if you call this again it just overwrites whatever callback you set before — no stacking, no vibes-multiplying. and if you pass NULL as the function pointer? that disables the registered callback function. bye girl 👋

when does your callback actually get called? the registered displacement callback function is invoked to displace points on the subdivision geometry during spatial acceleration structure construction, which is to say, during the rtcCommitScene call. so it's not a render-time thing, it's a build-time thing. iykyk 🔥

now the callback itself, the one of type RTCDisplacementFunctionN, gets invoked with a bunch of arguments all bundled up inside the RTCDisplacementFunctionNArguments structure. let's go through them like a group chat roll call 📱:

• the provided user data pointer of the geometry — that's the geometryUserPtr member — you can use it to point at your application's representation of the subdivision mesh. it's yours, decorate it however 🎀
• a number N of points to displace is specified, and it's in a structure-of-arrays layout, not array-of-structs. important!! ✨
• for each point you're displacing you get:
  • the local patch UV coordinates — the u and v arrays
  • the normalized geometry normal — the Ng_x, Ng_y, and Ng_z arrays
  • the position — the P_x, P_y, and P_z arrays
• and the task of the displacement function is literally just: use all that info and change the position data. that's the whole job. slay.

you also get the geometry handle (the geometry member) and the primitive ID of the patch to displace (the primID member), plus the time step timeStep — and that one's important if your displacement is time-dependent and motion blur is in the mix. don't sleep on timeStep, bestie 🫶

⚠️ okay serious moment: all passed arrays must be aligned to 64 bytes and properly padded, so that wide vector processing inside the displacement function is easily possible. do not skip this. the SIMD girlies are counting on you. 💀

also!! there's a tutorial, [Displacement Geometry], that shows an example of how to use the displacement mapping functions. go read it, it ate 👑

---

🌈 EXIT STATUS 🌈

if something goes wrong — on failure — an error code gets set, and you can go query it with rtcGetDeviceError. so like, always check on your girl. 🥺

---

⭐ SEE ALSO ⭐

• [RTC_GEOMETRY_TYPE_SUBDIVISION]

---

and that's the whole page, no notes 💜 this was rtcSetGeo...tFunction(3) from the Embree Ray Tracing Kernels 4 manual, section 3, bestie — go displace something gorgeous ✨🎀🦋