rtcSetGeo...tFunction(3)

💖 rtcSetGeometryDisplacementFunction 💖

okay bestie, welcome to the Embree Ray Tracing Kernels 3 manual page for rtcSetGeometryDisplacementFunction — yes the header truncates it to rtcSetGeo...tFunction(3) because apparently even manpages have to fit in the group chat preview. anyway. this one is about making your subdivision geometry move, and it's lowkey iconic.

---

✨ NAME ✨

rtcSetGeometryDisplacementFunction — sets the displacement function for a subdivision geometry

---

🌸 SYNOPSIS 🌸

#include <embree3/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
);

---

🦋 DESCRIPTION 🦋

so the rtcSetGeometryDisplacementFunction function registers a displacement callback function (that's the displacement argument, bestie) for the subdivision geometry you point at with the geometry argument. it's giving "hey geometry, here's the glow-up routine."

you can only have ONE callback function registered per geometry, periodt. every further invocation just overwrites whatever callback was there before, no drama, no queue. and if you pass NULL as the function pointer? that disables the registered callback function entirely. poof. gone. 💅

the registered displacement callback gets invoked to displace points on the subdivision geometry during spatial acceleration structure construction — specifically during the rtcCommitScene call. so it's not vibing at render time, it's doing its thing while the acceleration structure is being built. important distinction, iykyk.

the callback function is of type RTCDisplacementFunctionN and it gets invoked with a bunch of arguments stored inside the RTCDisplacementFunctionNArguments structure. let's go through them because this is the part where people get lost:

• the provided user data pointer of the geometry (the geometryUserPtr member) can point to your application's representation of the subdivision mesh — that's your little pocket dimension for whatever data you need.
• a number N of points to displace is specified in a structure of array layout. so like, arrays. obviously.
• for each point to displace, 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? use all of that info and change the position data. that's the whole job. slay.

the geometry handle (the geometry member) and the primitive ID (the primID member) of the patch to displace are additionally provided as well — and so is the time step timeStep, which can be important if the displacement is time-dependent and motion blur is used. ⏱️

⚠️ real talk, bestie: all passed arrays must be aligned to 64 bytes and properly padded, so that wide vector processing inside the displacement function is easily possible. don't skip this. the vector unit will simply not be okay. 😭

also see the tutorial [Displacement Geometry] for an example of how to use the displacement mapping functions. 🎀

---

💀 EXIT STATUS 💀

on failure an error code is set that you can query using rtcGetDeviceError. so like, check it. don't just assume it ate. 🙈

---

🌈 SEE ALSO 🌈

[RTC_GEOMETRY_TYPE_SUBDIVISION]

---

and that's the whole page, bestie! this was rtcSetGeometryDisplacementFunction(3) from the Embree Ray Tracing Kernels 3 manual set — go forth and displace, you've got this. mwah. 💖✨🫶