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 RTCPointQueryInstanceStack* instStack,
27                struct RTCPointQueryFunction* queryFunc,
28                void* userPtr
29              );
30
31   DESCRIPTION
32       The  rtcPointQuery  function  traverses  the  BVH using a RTCPointQuery
33       object (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 RTCPointQueryInstanceStack (instStack argument) must be cre‐
43       ated and initialized.  It contains ID and transformation information of
44       the  instancing  hierarchy  if  (multilevel-)instancing  is  used.  See
45       [rtcInitPointQueryInstanceStack] 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
61       argument 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
71       Embree 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   EXIT STATUS
85       For  performance  reasons  this  function does not do any error checks,
86       thus will not set any error flags on failure.
87
88   SEE ALSO
89       [rtcSetGeometryPointQueryFunction], [rtcInitPointQueryInstanceStack]
90
91
92
93                                                              rtcPointQuery(3)
Impressum