rtcPointQuery(3)

✨ rtcPointQuery(3) ✨

okay bestie, welcome to rtcPointQuery, a page straight out of the Embree Ray Tracing Kernels 4 manual 💖 this one's a whole function that goes poking around your BVH asking "hey, what's near this point?" and it is lowkey iconic.

---

🎀 NAME 🎀

rtcPointQuery — traverses the BVH with a point query object

---

🌸 SYNOPSIS 🌸

#include <embree4/rtcore.h>

struct RTC_ALIGN(16) RTCPointQuery
{
  // location of the query
  float x;
  float y;
  float z;

  // radius and time of the query
  float radius;
  float time;
};

void rtcPointQuery(
  RTCScene scene,
  struct RTCPointQuery* query,
  struct RTCPointQueryContext* context,
  struct RTCPointQueryFunction* queryFunc,
  void* userPtr
);

---

🦋 DESCRIPTION 🦋

so rtcPointQuery walks the BVH using an RTCPointQuery object (that's the query argument, bestie) and it calls a user-defined callback function (the queryFunc argument, e.g.) for every single primitive in the scene (the scene argument) that intersects the query domain. no cap.

You — yes YOU — have to initialize the query location (the x, y, and z members) and the query radius, in the range [0, ∞]. and if the scene has motion blur geometries, you also gotta set the query time (the time member) to a value in the range [0, 1]. don't skip that part fr fr 🙈

Also, an RTCPointQueryContext (the context argument) has to be created and initialized. it holds the ID and transformation info of the instancing hierarchy when (multilevel-)instancing is in play. go read [rtcInitPointQueryContext] for the deets 💅

For every primitive that intersects the query domain, the callback function (queryFunc) gets called, and that's where you can implement distance computations to the primitive. You'll be handed the primID and geomID of the primitive in question — but the geometry information (like the triangle index and vertex data) has to be determined manually. yes, by hand. the userPtr argument is your little messenger bag: use it to pass in geometry data of the scene, or to hand back the results of the point query (like the closest point currently found on surface geometry — see the tutorial [ClosestPoint]). 🫶

The queryFunc parameter is optional and can be NULL, in which case the callback function just doesn't get invoked. BUT ✋ a callback function can still get attached to a specific RTCGeometry object using [rtcSetGeometryPointQueryFunction]. And if a callback is attached to a geometry and a (potentially different) callback is passed as an argument to rtcPointQuery, then both functions get called for the primitives of those geometries. double trouble, but make it efficient.

the query radius can be decreased inside the callback function, which is the slay way to efficiently cull parts of the scene during BVH traversal 🔥 BUT — and this is the important bit — increasing the query radius and modifying time or location of the query will result in undefined behaviour. do not do it. that's not a vibe. 💀

The callback function will be called for all primitives in a leaf node of the BVH even if the primitive is outside the query domain, because Embree does not gather geometry information of primitives internally. it's giving "we didn't check, you check" 🙈

Point queries can be used with (multilevel)-instancing. However, care has to be taken when the instance transformation contains anisotropic scaling or sheering. In those cases, distance computations have to be performed in world space to ensure correctness, and the ellipsoidal query domain (in instance space) will be approximated with its axis aligned bounding box internally. So the callback function might get invoked even for primitives in inner BVH nodes that don't intersect the query domain. See [rtcSetGeometryPointQueryFunction] for details. 👑

And the point query structure must be aligned to 16 bytes. that's not optional, that's a rule. ⭐

---

🌈 SUPPORTED PRIMITIVES 🌈

Right now, all primitive types are supported by the point query API except:

• points (see [RTC_GEOMETRY_TYPE_POINT]) 😭
• curves (see [RTC_GEOMETRY_TYPE_CURVE]) 😭
• subdivision surfaces (see [RTC_GEOMETRY_SUBDIVISION]) 😭

so close to a full sweep. not quite. 💔

---

💅 EXIT STATUS 💅

for performance reasons, this function does not do any error checks, so it will not set any error flags on failure. she simply does not have the time, bestie. 👑

---

👀 SEE ALSO 👀

• [rtcSetGeometryPointQueryFunction]
• [rtcInitPointQueryContext]

---

and that's the whole page, babe 🎀 this was rtcPointQuery(3) from the Embree Ray Tracing Kernels 4 docs — the manual name is right there in the page title and it's giving main character energy ⭐ go forth and query points, you absolute legend 💖✨🌸🦋