.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "rtcPointQuery" "3" "" "" "Embree Ray Tracing Kernels 4"
.hy
.SS NAME
.IP
.nf
\f[C]
rtcPointQuery - traverses the BVH with a point query object
\f[R]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#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
);
\f[R]
.fi
.SS DESCRIPTION
.PP
The \f[C]rtcPointQuery\f[R] function traverses the BVH using a
\f[C]RTCPointQuery\f[R] object (\f[C]query\f[R] argument) and calls a
user defined callback function (e.g \f[C]queryFunc\f[R] argument) for
each primitive of the scene (\f[C]scene\f[R] argument) that intersects
the query domain.
.PP
The user has to initialize the query location (\f[C]x\f[R], \f[C]y\f[R]
and \f[C]z\f[R] member) and query radius in the range [0,\[u2006]\[if]].
If the scene contains motion blur geometries, also the query time
(\f[C]time\f[R] member) must be initialized to a value in the range
[0,\[u2006]1].
.PP
Further, a \f[C]RTCPointQueryContext\f[R] (\f[C]context\f[R] argument)
must be created and initialized.
It contains ID and transformation information of the instancing
hierarchy if (multilevel-)instancing is used.
See [rtcInitPointQueryContext] for further information.
.PP
For every primitive that intersects the query domain, the callback
function (\f[C]queryFunc\f[R] argument) is called, in which distance
computations to the primitive can be implemented.
The user 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.
The \f[C]userPtr\f[R] argument can be used to input geometry data of the
scene or output results of the point query (e.g.\ closest point
currently found on surface geometry (see tutorial [ClosestPoint])).
.PP
The parameter \f[C]queryFunc\f[R] 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
\f[C]RTCGeometry\f[R] object using [rtcSetGeometryPointQueryFunction].
If a callback function is attached to a geometry and (a potentially
different) callback function is passed as an argument to
\f[C]rtcPointQuery\f[R], both functions are called for the primitives of
the according geometries.
.PP
The query radius can be decreased inside the callback function, which
allows to efficiently cull parts of the scene during BVH traversal.
Increasing the query radius and modifying time or location of the query
will result in undefined behaviour.
.PP
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.
.PP
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.
.PP
The point query structure must be aligned to 16 bytes.
.SS SUPPORTED PRIMITIVES
.PP
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 sudivision surfaces (see
[RTC_GEOMETRY_SUBDIVISION]).
.SS EXIT STATUS
.PP
For performance reasons this function does not do any error checks, thus
will not set any error flags on failure.
.SS SEE ALSO
.PP
[rtcSetGeometryPointQueryFunction], [rtcInitPointQueryContext]