1rtcBuildBVH(3) Embree Ray Tracing Kernels 3 rtcBuildBVH(3)
2 NAME
6 rtcBuildBVH - builds a BVH
7 SYNOPSIS
9 #include <embree3/rtcore.h>
10 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 typedef void* (*RTCCreateNodeFunction) (
20 RTCThreadLocalAllocator allocator,
21 unsigned int childCount,
22 void* userPtr
23 );
24 typedef void (*RTCSetNodeChildrenFunction) (
26 void* nodePtr,
27 void** children,
28 unsigned int childCount,
29 void* userPtr
30 );
31 typedef void (*RTCSetNodeBoundsFunction) (
33 void* nodePtr,
34 const struct RTCBounds** bounds,
35 unsigned int childCount,
36 void* userPtr
37 );
38 typedef void* (*RTCCreateLeafFunction) (
40 RTCThreadLocalAllocator allocator,
41 const struct RTCBuildPrimitive* primitives,
42 size_t primitiveCount,
43 void* userPtr
44 );
45 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 typedef bool (*RTCProgressMonitorFunction)(
56 void* userPtr, double n
57 );
58 enum RTCBuildFlags
60 {
61 RTC_BUILD_FLAG_NONE,
62 RTC_BUILD_FLAG_DYNAMIC
63 };
64 struct RTCBuildArguments
66 {
67 size_t byteSize;
68 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 RTCBVH bvh;
80 struct RTCBuildPrimitive* primitives;
81 size_t primitiveCount;
82 size_t primitiveArrayCapacity;
83 RTCCreateNodeFunction createNode;
85 RTCSetNodeChildrenFunction setNodeChildren;
86 RTCSetNodeBoundsFunction setNodeBounds;
87 RTCCreateLeafFunction createLeaf;
88 RTCSplitPrimitiveFunction splitPrimitive;
89 RTCProgressMonitorFunction buildProgress;
90 void* userPtr;
91 };
92 struct RTCBuildArguments rtcDefaultBuildArguments();
94 void* rtcBuildBVH(
96 const struct RTCBuildArguments* args
97 );
98 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 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
114 application after the BVH is built. All callback functions are typi‐
115 cally called from multiple threads, thus their implementation must be
116 thread-safe.
117 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 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 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 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 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 The RTCCreateNodeFunc callback additionally gets the number of children
161 for this node in the range from 2 to maxBranchingFactor (childCount
162 argument).
163 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 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 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 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 The RTCProgressMonitorFunction callback function is called with the
185 estimated completion rate n in the range [0, 1]. Returning true from
186 the callback lets the build continue; returning false cancels the
187 build.
188 EXIT STATUS
190 On failure an error code is set that can be queried using rtcGetDe‐
191 viceError.
192 SEE ALSO
194 [rtcNewBVH]
195 rtcBuildBVH(3)