rtcPointQuery(3)

💫 rtcPointQuery(3) 💫

okay bestie, welcome to the Embree Ray Tracing Kernels 3 manual page for rtcPointQuery — yes she's a 3, she's a library function, she's iconic, let's go 🎀

---

✨ NAME ✨

rtcPointQuery — traverses the BVH with a point query object 🦋

---

🌸 SYNOPSIS 🌸

#include <embree3/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. The rtcPointQuery function traverses the BVH using an RTCPointQuery object (that's the query argument, bestie) and it calls a user defined callback function (e.g. the queryFunc argument) for each primitive of the scene (that's the scene argument) that intersects the query domain. Periodt. 💖

The user has to initialize the query location (the x, y and z members) and the query radius, which lives in the range [0, ∞]. And if the scene contains motion blur geometries, you also gotta initialize the query time (the time member) to a value in the range [0, 1]. No skipping steps, girl. 😤

Also, a RTCPointQueryContext (the context argument) must be created and initialized. She's holding ID and transformation information of the instancing hierarchy if (multilevel-)instancing is used. Go read [rtcInitPointQueryContext] for the details, iykyk. 📚

For every primitive that intersects the query domain, the callback function (the queryFunc argument) gets called, and that's where you can implement distance computations to the primitive. You will be provided with the primID and geomID of the according primitive — however, the geometry information (e.g. triangle index and vertex data) has to be determined manually by you. The userPtr argument can be used to input geometry data of the scene or output results of the point query (e.g. the closest point currently found on surface geometry — see the tutorial [ClosestPoint]). Obsessed with a good userPtr, honestly. 🫶

The parameter queryFunc is optional and can be NULL, in which case the callback function is not invoked. However, a callback function can still get attached to a specific RTCGeometry object using [rtcSetGeometryPointQueryFunction]. And if a callback function is attached to a geometry and (a potentially different) callback function is passed as an argument to rtcPointQuery, then both functions are called for the primitives of the according geometries. Double the callback, double the slay. ✨

The query radius can be decreased inside the callback function, which lets you efficiently cull parts of the scene during BVH traversal. That's the good stuff. 💚

⚠️ but increasing the query radius, or modifying time or location of the query, will result in undefined behaviour. Do NOT. Not me watching you try it. 💀

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, since Embree does not gather geometry information of primitives internally. Like, she's not being extra, she just doesn't keep that info. 🙈

Point queries can be used with (multilevel)-instancing. However, care has to be taken when the instance transformation contains anisotropic scaling or sheering. In these 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. Therefore, the callback function might be invoked even for primitives in inner BVH nodes that do not intersect the query domain. See [rtcSetGeometryPointQueryFunction] for details. 🦋

💖 reminder: the point query structure must be aligned to 16 bytes.

---

👑 SUPPORTED PRIMITIVES 👑

Currently, all primitive types are supported by the point query API — except of points (see [RTC_GEOMETRY_TYPE_POINT]), curves (see [RTC_GEOMETRY_TYPE_CURVE]) and subdivision surfaces (see [RTC_GEOMETRY_SUBDIVISION]). Sorry to those three specifically, it's not personal. 😭

---

⭐ EXIT STATUS ⭐

For performance reasons this function does not do any error checks, thus it will not set any error flags on failure. She's fast, she's not checking your work. 💅

---

🌈 SEE ALSO 🌈

• [rtcSetGeometryPointQueryFunction]
• [rtcInitPointQueryContext]

---

and that's the whole page, bestie!! this one came from Embree Ray Tracing Kernels 3, it's the rtcPointQuery(3) page, and honestly? she ate. 🎀✨💜