1rtcBuildBVH(3)           Embree Ray Tracing Kernels 3           rtcBuildBVH(3)
2
3
4
5   NAME
6              rtcBuildBVH - builds a BVH
7
8   SYNOPSIS
9              #include <embree3/rtcore.h>
10
11              struct RTC_ALIGN(32) RTCBuildPrimitive
12              {
13                float lower_x, lower_y, lower_z;
14                unsigned int geomID;
15                float upper_x, upper_y, upper_z;
16                unsigned int primID;
17              };
18
19              typedef void* (*RTCCreateNodeFunction) (
20                RTCThreadLocalAllocator allocator,
21                unsigned int childCount,
22                void* userPtr
23              );
24
25              typedef void (*RTCSetNodeChildrenFunction) (
26                void* nodePtr,
27                void** children,
28                unsigned int childCount,
29                void* userPtr
30              );
31
32              typedef void (*RTCSetNodeBoundsFunction) (
33                void* nodePtr,
34                const struct RTCBounds** bounds,
35                unsigned int childCount,
36                void* userPtr
37              );
38
39              typedef void* (*RTCCreateLeafFunction) (
40                RTCThreadLocalAllocator allocator,
41                const struct RTCBuildPrimitive* primitives,
42                size_t primitiveCount,
43                void* userPtr
44              );
45
46              typedef void (*RTCSplitPrimitiveFunction) (
47                const struct RTCBuildPrimitive* primitive,
48                unsigned int dimension,
49                float position,
50                struct RTCBounds* leftBounds,
51                struct RTCBounds* rightBounds,
52                void* userPtr
53              );
54
55              typedef bool (*RTCProgressMonitorFunction)(
56                void* userPtr, double n
57              );
58
59              enum RTCBuildFlags
60              {
61                RTC_BUILD_FLAG_NONE,
62                RTC_BUILD_FLAG_DYNAMIC
63              };
64
65              struct RTCBuildArguments
66              {
67                size_t byteSize;
68
69                enum RTCBuildQuality buildQuality;
70                enum RTCBuildFlags buildFlags;
71                unsigned int maxBranchingFactor;
72                unsigned int maxDepth;
73                unsigned int sahBlockSize;
74                unsigned int minLeafSize;
75                unsigned int maxLeafSize;
76                float traversalCost;
77                float intersectionCost;
78
79                RTCBVH bvh;
80                struct RTCBuildPrimitive* primitives;
81                size_t primitiveCount;
82                size_t primitiveArrayCapacity;
83
84                RTCCreateNodeFunction createNode;
85                RTCSetNodeChildrenFunction setNodeChildren;
86                RTCSetNodeBoundsFunction setNodeBounds;
87                RTCCreateLeafFunction createLeaf;
88                RTCSplitPrimitiveFunction splitPrimitive;
89                RTCProgressMonitorFunction buildProgress;
90                void* userPtr;
91              };
92
93              struct RTCBuildArguments rtcDefaultBuildArguments();
94
95              void* rtcBuildBVH(
96                const struct RTCBuildArguments* args
97              );
98
99   DESCRIPTION
100       The  rtcBuildBVH  function can be used to build a BVH in a user-defined
101       format over arbitrary primitives.  All arguments to  the  function  are
102       provided  through the RTCBuildArguments structure.  The first member of
103       that structure must be set to  the  size  of  the  structure  in  bytes
104       (bytesSize member) which allows future extensions of the structure.  It
105       is recommended to initialize the build arguments  structure  using  the
106       rtcDefaultBuildArguments function.
107
108       The rtcBuildBVH function gets passed the BVH to build (bvh member), the
109       array of primitives (primitives member), the  capacity  of  that  array
110       (primitiveArrayCapacity member), the number of primitives stored inside
111       the array (primitiveCount member), callback function  pointers,  and  a
112       user-defined  pointer  (userPtr  member) that is passed to all callback
113       functions when invoked.  The primitives array can be freed by  the  ap‐
114       plication after the BVH is built.  All callback functions are typically
115       called  from  multiple  threads,  thus  their  implementation  must  be
116       thread-safe.
117
118       Four  callback  functions  must be registered, which are invoked during
119       build to create BVH nodes (createNode member), to set the  pointers  to
120       all children (setNodeChildren member), to set the bounding boxes of all
121       children (setNodeBounds member), and to create a leaf node  (createLeaf
122       member).
123
124       The  function  pointer  to the primitive split function (splitPrimitive
125       member) may be NULL, however, then no spatial splitting in high quality
126       mode  is  possible.   The  function  pointer  used  to report the build
127       progress (buildProgress member) is optional and may also be NULL.
128
129       Further, some build settings are passed to  configure  the  BVH  build.
130       Using  the build quality settings (buildQuality member), one can select
131       between a faster, low quality build which is good for  dynamic  scenes,
132       and  a  standard quality build for static scenes.  One can also specify
133       the desired maximum branching factor  of  the  BVH  (maxBranchingFactor
134       member),  the  maximum depth the BVH should have (maxDepth member), the
135       block size for the SAH heuristic (sahBlockSize member), the minimum and
136       maximum  leaf  size (minLeafSize and maxLeafSize member), and the esti‐
137       mated costs of  one  traversal  step  and  one  primitive  intersection
138       (traversalCost   and  intersectionCost  members).   When  enabling  the
139       RTC_BUILD_FLAG_DYNAMIC build flags (buildFlags member),  re-build  per‐
140       formance  for  dynamic  scenes is improved at the cost of higher memory
141       requirements.
142
143       To spatially split primitives in high quality mode, the  builder  needs
144       extra  space  at the end of the build primitive array to store splitted
145       primitives.  The total capacity of the build primitive array is  passed
146       using  the primitiveArrayCapacity member, and should be about twice the
147       number of primitives when using spatial splits.
148
149       The RTCCreateNodeFunc and  RTCCreateLeafFunc  callbacks  are  passed  a
150       thread  local  allocator object that should be used for fast allocation
151       of nodes using the rtcThreadLocalAlloc function.  We strongly recommend
152       using  this  allocation mechanism, as alternative approaches like stan‐
153       dard malloc can be over 10× slower.  The allocator object passed to the
154       create  callbacks  may  be used only inside the current thread.  Memory
155       allocated using rtcThreadLocalAlloc is  automatically  freed  when  the
156       RTCBVH object is deleted.  If you use your own memory allocation scheme
157       you have to free the memory yourself  when  the  RTCBVH  object  is  no
158       longer used.
159
160       The RTCCreateNodeFunc callback additionally gets the number of children
161       for this node in the range from 2 to maxBranchingFactor (childCount ar‐
162       gument).
163
164       The RTCSetNodeChildFunc callback function gets a pointer to the node as
165       input (nodePtr argument), an array of pointers to the children (childP‐
166       trs argument), and the size of this array (childCount argument).
167
168       The  RTCSetNodeBoundsFunc  callback function gets a pointer to the node
169       as input (nodePtr argument), an array of pointers to the bounding boxes
170       of  the  children (bounds argument), and the size of this array (child‐
171       Count argument).
172
173       The RTCCreateLeafFunc callback additionally gets an array of primitives
174       as  input (primitives argument), and the size of this array (primitive‐
175       Count argument).  The callback should read the geomID and  primID  mem‐
176       bers from the passed primitives to construct the leaf.
177
178       The  RTCSplitPrimitiveFunc  callback is invoked in high quality mode to
179       split a primitive (primitive argument) at the specified position (posi‐
180       tion argument) and dimension (dimension argument).  The callback should
181       return bounds of the clipped left and  right  parts  of  the  primitive
182       (leftBounds and rightBounds arguments).
183
184       The RTCProgressMonitorFunction callback function is called with the es‐
185       timated completion rate n in the range [0, 1].  Returning true from the
186       callback lets the build continue; returning false cancels the build.
187
188   EXIT STATUS
189       On  failure  an  error  code is set that can be queried using rtcGetDe‐
190       viceError.
191
192   SEE ALSO
193       [rtcNewBVH]
194
195
196
197                                                                rtcBuildBVH(3)
Impressum