rtcPointQuery(3)         Embree Ray Tracing Kernels 4         rtcPointQuery(3)

   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
       The rtcPointQuery function traverses the BVH using a RTCPointQuery
       object (query argument) and calls a user defined callback function (e.g
       queryFunc argument) for each primitive of the scene (scene argument)
       that intersects the query domain.

       The user has to initialize the query location (x, y and z member) and
       query radius in the range [0,<?><infinity>].  If the scene contains
       motion blur geometries, also the query time (time member) must be
       initialized to a value in the range [0,<?>1].

       Further, a RTCPointQueryContext (context 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.

       For every primitive that intersects the query domain, the callback
       function (queryFunc 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 userPtr 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])).

       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].  If a callback function is attached
       to a geometry and (a potentially different) callback function is passed
       as an argument to rtcPointQuery, both functions are called for the
       primitives of the according geometries.

       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.

       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.

       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.

       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 sudivision surfaces (see
       [RTC_GEOMETRY_SUBDIVISION]).

   EXIT STATUS
       For performance reasons this function does not do any error checks,
       thus will not set any error flags on failure.

   SEE ALSO
       [rtcSetGeometryPointQueryFunction], [rtcInitPointQueryContext]

                                                              rtcPointQuery(3)