1rtcSetGeometryPointQueryFuEnmcbtrieoen(R3a)y TracingrKtecrSneetlGseo3metryPointQueryFunction(3)
2
3
4
5   NAME
6              rtcSetGeometryPointQueryFunction - sets the point query callback function
7                for a geometry
8
9   SYNOPSIS
10              #include <embree3/rtcore.h>
11
12              struct RTCPointQueryFunctionArguments
13              {
14                // the (world space) query object that was passed as an argument of rtcPointQuery.
15                struct RTCPointQuery* query;
16
17                // used for user input/output data. Will not be read or modified internally.
18                void* userPtr;
19
20                // primitive and geometry ID of primitive
21                unsigned int  primID;
22                unsigned int  geomID;
23
24                // the context with transformation and instance ID stack
25                struct RTCPointQueryContext* context;
26
27                // scaling factor indicating whether the current instance transformation
28                // is a similarity transformation.
29                float similarityScale;
30              };
31
32              typedef bool (*RTCPointQueryFunction)(
33                struct RTCPointQueryFunctionArguments* args
34              );
35
36              void rtcSetGeometryPointQueryFunction(
37                RTCGeometry geometry,
38                RTCPointQueryFunction queryFunc
39              );
40
41   DESCRIPTION
42       The  rtcSetGeometryPointQueryFunction  function registers a point query
43       callback function (queryFunc argument) for the specified geometry  (ge‐
44       ometry argument).
45
46       Only a single callback function can be registered per geometry and fur‐
47       ther invocations overwrite the previously set callback function.  Pass‐
48       ing NULL as function pointer disables the registered callback function.
49
50       The  registered callback function is invoked by [rtcPointQuery] for ev‐
51       ery primitive of the geometry that intersects the  corresponding  point
52       query domain.  The callback function of type RTCPointQueryFunction gets
53       passed a number of arguments through the RTCPointQueryFunctionArguments
54       structure.   The query object is the original point query object passed
55       into [rtcPointQuery], usrPtr is an arbitrary pointer to pass input into
56       and  store  results  of  the callback function.  The primID, geomID and
57       context (see [rtcInitPointQueryContext] for details)  can  be  used  to
58       identify the geometry data of the primitive.
59
60       A  RTCPointQueryFunction  can also be passed directly as an argument to
61       [rtcPointQuery].  In this case the callback is invoked for  all  primi‐
62       tives  in  the  scene  that  intersect the query domain.  If a callback
63       function is passed as an argument to [rtcPointQuery] and (a potentially
64       different)  callback  function is set for a geometry with [rtcSetGeome‐
65       tryPointQueryFunction] both callback  functions  are  invoked  and  the
66       callback  function  passed to [rtcPointQuery] will be called before the
67       geometry specific callback function.
68
69       If instancing is used, the parameter simliarityScale indicates  whether
70       the current instance transform (top element of the stack in context) is
71       a similarity transformation or  not.   Similarity  transformations  are
72       composed of translation, rotation and uniform scaling and if a matrix M
73       defines a similarity transformation, there is a scaling factor  D  such
74       that  for all x,y: dist(Mx, My) = D * dist(x, y).  In this case the pa‐
75       rameter scalingFactor is this scaling factor D and otherwise it  is  0.
76       A  valid  similarity scale (similarityScale > 0) allows to compute dis‐
77       tance information in instance space and scale the distances into  world
78       space  (for example, to update the query radius, see below) by dividing
79       the instance space distance with the similarity scale.  If the  current
80       instance  transform  is  not a similarity transform (similarityScale is
81       0), the distance computation has to be performed in world space to  en‐
82       sure  correctness.   In this case the instance to world transformations
83       given with the context should be used to transform the  primitive  data
84       into world space.  Otherwise, the query location can be transformed in‐
85       to instance space which can be more efficient.  If there is no instance
86       transform, the similarity scale is 1.
87
88       The callback function will potentially be called for primitives outside
89       the query domain for two resons: First, the callback is invoked for all
90       primitives  inside a BVH leaf node since no geometry data of primitives
91       is determined internally and therefore individual  primitives  are  not
92       culled  (only  their (aggregated) bounding boxes).  Second, in case non
93       similarity transformations are used, the  resulting  ellipsoidal  query
94       domain (in instance space) is approximated by its axis aligned bounding
95       box internally and therefore inner nodes  that  do  not  intersect  the
96       original  domain  might  intersect the approximative bounding box which
97       results in unneccessary callbacks.  In any case, the callbacks are con‐
98       servative,  i.e.   if a primitive is inside the query domain a callback
99       will be invoked but the reverse is not neccessarily true.
100
101       For efficiency, the radius of the query object  can  be  decreased  (in
102       world  space) inside the callback function to improve culling of geome‐
103       try during BVH traversal.  If the query radius was updated,  the  call‐
104       back function should return true to issue an update of internal traver‐
105       sal information.  Increasing the radius or modifying the time or  posi‐
106       tion of the query results in undefined behaviour.
107
108       Within the callback function, it is safe to call [rtcPointQuery] again,
109       for example when implementing instancing manually.  In  this  case  the
110       instance  transformation  should  be  pushed onto the stack in context.
111       Embree will internally compute the point query information in  instance
112       space  using  the  top  element of the stack in context when [rtcPoint‐
113       Query] is called.
114
115       For a reference implementation of a closest point traversal of triangle
116       meshes  using  instancing  and user defined instancing see the tutorial
117       [ClosestPoint].
118
119   SEE ALSO
120       [rtcPointQuery], [rtcInitPointQueryContext]
121
122
123
124                                           rtcSetGeometryPointQueryFunction(3)
Impressum