1rtcSetGeometryPointQueryFuEnmcbtrieoen(R3a)y TracingrKtecrSneetlGseo3metryPointQueryFunction(3)
2 NAME
6 rtcSetGeometryPointQueryFunction - sets the point query callback function
7 for a geometry
8 SYNOPSIS
10 #include <embree3/rtcore.h>
11 struct RTCPointQueryFunctionArguments
13 {
14 // the (world space) query object that was passed as an argument of rtcPointQuery.
15 struct RTCPointQuery* query;
16 // used for user input/output data. Will not be read or modified internally.
18 void* userPtr;
19 // primitive and geometry ID of primitive
21 unsigned int primID;
22 unsigned int geomID;
23 // the context with transformation and instance ID stack
25 struct RTCPointQueryContext* context;
26 // scaling factor indicating whether the current instance transformation
28 // is a similarity transformation.
29 float similarityScale;
30 };
31 typedef bool (*RTCPointQueryFunction)(
33 struct RTCPointQueryFunctionArguments* args
34 );
35 void rtcSetGeometryPointQueryFunction(
37 RTCGeometry geometry,
38 RTCPointQueryFunction queryFunc
39 );
40 DESCRIPTION
42 The rtcSetGeometryPointQueryFunction function registers a point query
43 callback function (queryFunc argument) for the specified geometry (ge‐
44 ometry argument).
45 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 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 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 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 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 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 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 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 SEE ALSO
120 [rtcPointQuery], [rtcInitPointQueryContext]
121 rtcSetGeometryPointQueryFunction(3)