rtcSetGeo...yFunction(3)

✨ NAME ✨

okay so bestie, welcome to rtcSetGeo...yFunction(3), section 3 of the Embree Ray Tracing Kernels 4 manual 🎀 and the star of the show is:

rtcSetGeometryPointQueryFunction — sets the point query callback function for a geometry 💅

that's the whole assignment. short title, big power. periodt.

---

🦋 SYNOPSIS 🦋

like, here's the whole cast, no cuts:

#include <embree4/rtcore.h>

struct RTCPointQueryFunctionArguments
{
  // the (world space) query object that was passed as an argument of rtcPointQuery.
  struct RTCPointQuery* query;

  // used for user input/output data. Will not be read or modified internally.
  void* userPtr;

  // primitive and geometry ID of primitive
  unsigned int  primID;
  unsigned int  geomID;

  // the context with transformation and instance ID stack
  struct RTCPointQueryContext* context;

  // scaling factor indicating whether the current instance transformation
  // is a similarity transformation.
  float similarityScale;
};

typedef bool (*RTCPointQueryFunction)(
  struct RTCPointQueryFunctionArguments* args
);

void rtcSetGeometryPointQueryFunction(
  RTCGeometry geometry,
  RTCPointQueryFunction queryFunc
);

not me putting the whole struct in here, but you NEED it, iykyk 🫶

---

💅 DESCRIPTION 💅

so rtcSetGeometryPointQueryFunction does one job and does it gorgeously: it registers a point query callback function (the queryFunc argument) for the specified geometry (the geometry argument). ✨

only one callback function per geometry, bestie. one. further invocations overwrite the previously set callback function — so don't come crying when your old one ghosts you 💀. and if you pass NULL as the function pointer? that disables the registered callback function. bye bye 👋

the registered callback function gets invoked by [rtcPointQuery] for every primitive of the geometry that intersects the corresponding point query domain 🌸. the callback, of type RTCPointQueryFunction, receives a whole lil care package of arguments through the RTCPointQueryFunctionArguments structure:

• the query object is the original point query object passed into [rtcPointQuery]
• usrPtr is an arbitrary pointer — for passing input into and storing results of the callback function
• primID, geomID and context (see [rtcInitPointQueryContext] for the deets) can be used to identify the geometry data of the primitive

you can also pass an RTCPointQueryFunction directly as an argument to [rtcPointQuery] 🎀 in that case the callback is invoked for all primitives in the scene that intersect the query domain. and if you do both — pass one to [rtcPointQuery] and set one on a geometry with [rtcSetGeometryPointQueryFunction] — then both callback functions are invoked, and the one passed to [rtcPointQuery] gets called before the geometry specific callback function. it's giving queue energy, honestly.

🌈 instancing & that simliarityScale moment 🌈

if instancing is used, the parameter simliarityScale tells you whether the current instance transform (the top element of the stack in context) is a similarity transformation or not 🦋 similarity transformations are composed of translation, rotation and uniform scaling, and if a matrix M defines a similarity transformation, there's a scaling factor D such that for all x,y: dist(Mx, My) = D * dist(x, y). in this case the parameter scalingFactor is this scaling factor D — and otherwise it is 0.

a valid similarity scale (similarityScale > 0) lets you compute distance information in instance space and scale the distances into world space (for example, to update the query radius, see below) by dividing the instance space distance with the similarity scale ✨

if the current instance transform is not a similarity transform (similarityScale is 0), the distance computation has to be performed in world space to ensure correctness. in that case the instance to world transformations given with the context should be used to transform the primitive data into world space. otherwise, the query location can be transformed into instance space, which can be more efficient 💖

and if there's no instance transform? the similarity scale is 1. cute. simple. iconic.

🙈 why you're getting called for stuff outside the domain

the callback function will potentially be called for primitives outside the query domain, for two reasons:

1. the callback is invoked for all primitives inside a BVH leaf node, since no geometry data of primitives is determined internally and therefore individual primitives are not culled (only their (aggregated) bounding boxes are).
2. in case non similarity transformations are used, the resulting ellipsoidal query domain (in instance space) is approximated by its axis aligned bounding box internally, and therefore inner nodes that do not intersect the original domain might intersect the approximative bounding box, which results in unnecessary callbacks 😭

in any case, the callbacks are conservative, i.e. if a primitive is inside the query domain a callback will be invoked — but the reverse is not necessarily true. so like, extra calls are normal, don't panic 🍓

🔥 radius things (read this part, fr fr)

for efficiency, the radius of the query object can be decreased (in world space) inside the callback function, to improve culling of geometry during BVH traversal 💅

if the query radius was updated, the callback function should return true to issue an update of internal traversal information.

⚠️ increasing the radius, or modifying the time or position of the query, results in undefined behaviour. do not do it. i'm so serious. that's the cursed part of this page 💀

🧚 nesting your own rtcPointQuery calls

within the callback function, it is safe to call [rtcPointQuery] again — for example when implementing instancing manually 👑 in this case the instance transformation should be pushed onto the stack in context. Embree will internally compute the point query information in instance space using the top element of the stack in context when [rtcPointQuery] is called. main character recursion energy, honestly.

for a reference implementation of a closest point traversal of triangle meshes using instancing and user defined instancing, see the tutorial [ClosestPoint] ⭐ go look, it ate.

---

🌸 SEE ALSO 🌸

• [rtcPointQuery]
• [rtcInitPointQueryContext]

---

and that's the page bestie 💖 that was rtcSetGeo...yFunction(3) out of the Embree Ray Tracing Kernels 4 manual, section 3 — that's the source/version tea, and the date? not on this page, so i'm not gonna make one up 😌 go forth and set those geometry point query functions, you've got this 🫶✨