1rtcPointQuery(3)         Embree Ray Tracing Kernels 3         rtcPointQuery(3)
2
3
4
5   NAME
6              rtcPointQuery - traverses the BVH with a point query object
7
8   SYNOPSIS
9              #include <embree3/rtcore.h>
10
11              struct RTC_ALIGN(16) RTCPointQuery
12              {
13                // location of the query
14                float x;
15                float y;
16                float z;
17
18                // radius and time of the query
19                float radius;
20                float time;
21              };
22
23              void rtcPointQuery(
24                RTCScene scene,
25                struct RTCPointQuery* query,
26                struct RTCPointQueryContext* context,
27                struct RTCPointQueryFunction* queryFunc,
28                void* userPtr
29              );
30
31   DESCRIPTION
32       The  rtcPointQuery function traverses the BVH using a RTCPointQuery ob‐
33       ject (query argument) and calls a user defined callback  function  (e.g
34       queryFunc  argument)  for  each primitive of the scene (scene argument)
35       that intersects the query domain.
36
37       The user has to initialize the query location (x, y and z  member)  and
38       query  radius  in  the range [0, ∞].  If the scene contains motion blur
39       geometries, also the query time (time member) must be initialized to  a
40       value in the range [0, 1].
41
42       Further,  a RTCPointQueryContext (context argument) must be created and
43       initialized.  It contains ID and transformation information of the  in‐
44       stancing  hierarchy  if (multilevel-)instancing is used.  See [rtcInit‐
45       PointQueryContext] for further information.
46
47       For every primitive that intersects  the  query  domain,  the  callback
48       function (queryFunc argument) is called, in which distance computations
49       to the primitive can be implemented.  The user will  be  provided  with
50       the primID and geomID of the according primitive, however, the geometry
51       information (e.g.  triangle index and vertex data) has to be determined
52       manually.   The  userPtr argument can be used to input geometry data of
53       the scene or output results of the point  query  (e.g.   closest  point
54       currently found on surface geometry (see tutorial [ClosestPoint])).
55
56       The  parameter queryFunc is optional and can be NULL, in which case the
57       callback function is not invoked.  However,  a  callback  function  can
58       still get attached to a specific RTCGeometry object using [rtcSetGeome‐
59       tryPointQueryFunction].  If a callback function is attached to a geome‐
60       try and (a potentially different) callback function is passed as an ar‐
61       gument to rtcPointQuery, both functions are called for  the  primitives
62       of the according geometries.
63
64       The  query  radius can be decreased inside the callback function, which
65       allows to efficiently cull parts of the  scene  during  BVH  traversal.
66       Increasing the query radius and modifying time or location of the query
67       will result in undefined behaviour.
68
69       The callback function will be called for all primitives in a leaf  node
70       of the BVH even if the primitive is outside the query domain, since Em‐
71       bree does not gather geometry information of primitives internally.
72
73       Point queries can be used with (multilevel)-instancing.  However,  care
74       has  to  be taken when the instance transformation contains anisotropic
75       scaling or sheering.  In these cases distance computations have  to  be
76       performed  in  world  space  to  ensure correctness and the ellipsoidal
77       query domain (in instance space) will be  approximated  with  its  axis
78       aligned bounding box interally.  Therefore, the callback function might
79       be invoked even for primitives in inner BVH nodes that do not intersect
80       the query domain.  See [rtcSetGeometryPointQueryFunction] for details.
81
82       The point query structure must be aligned to 16 bytes.
83
84   SUPPORTED PRIMITIVES
85       Currenly,  all primitive types are supported by the point query API ex‐
86       cept of points (see [RTC_GEOMETRY_TYPE_POINT]), curves (see [RTC_GEOME‐
87       TRY_TYPE_CURVE])  and  sudivision  surfaces (see [RTC_GEOMETRY_SUBDIVI‐
88       SION]).
89
90   EXIT STATUS
91       For performance reasons this function does not  do  any  error  checks,
92       thus will not set any error flags on failure.
93
94   SEE ALSO
95       [rtcSetGeometryPointQueryFunction], [rtcInitPointQueryContext]
96
97
98
99                                                              rtcPointQuery(3)