libigl_Martin/build2/install/share/man/man3/rtcBuildBVH.3embree3

.TH "rtcBuildBVH" "3" "" "" "Embree Ray Tracing Kernels 3"
.SS NAME
.IP
.nf
\f[C]
rtcBuildBVH\ \-\ builds\ a\ BVH
\f[]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include\ <embree3/rtcore.h>

struct\ RTC_ALIGN(32)\ RTCBuildPrimitive
{
\ \ float\ lower_x,\ lower_y,\ lower_z;\ 
\ \ unsigned\ int\ geomID;
\ \ float\ upper_x,\ upper_y,\ upper_z;
\ \ unsigned\ int\ primID;
};

typedef\ void*\ (*RTCCreateNodeFunction)\ (
\ \ RTCThreadLocalAllocator\ allocator,
\ \ unsigned\ int\ childCount,
\ \ void*\ userPtr
);

typedef\ void\ (*RTCSetNodeChildrenFunction)\ (
\ \ void*\ nodePtr,
\ \ void**\ children,
\ \ unsigned\ int\ childCount,
\ \ void*\ userPtr
);

typedef\ void\ (*RTCSetNodeBoundsFunction)\ (
\ \ void*\ nodePtr,
\ \ const\ struct\ RTCBounds**\ bounds,
\ \ unsigned\ int\ childCount,
\ \ void*\ userPtr
);

typedef\ void*\ (*RTCCreateLeafFunction)\ (
\ \ RTCThreadLocalAllocator\ allocator,
\ \ const\ struct\ RTCBuildPrimitive*\ primitives,
\ \ size_t\ primitiveCount,
\ \ void*\ userPtr
);

typedef\ void\ (*RTCSplitPrimitiveFunction)\ (
\ \ const\ struct\ RTCBuildPrimitive*\ primitive,
\ \ unsigned\ int\ dimension,
\ \ float\ position,
\ \ struct\ RTCBounds*\ leftBounds,
\ \ struct\ RTCBounds*\ rightBounds,
\ \ void*\ userPtr
);

typedef\ bool\ (*RTCProgressMonitorFunction)(
\ \ void*\ userPtr,\ double\ n
);

enum\ RTCBuildFlags
{
\ \ RTC_BUILD_FLAG_NONE,
\ \ RTC_BUILD_FLAG_DYNAMIC
};

struct\ RTCBuildArguments
{
\ \ size_t\ byteSize;

\ \ enum\ RTCBuildQuality\ buildQuality;
\ \ enum\ RTCBuildFlags\ buildFlags;
\ \ unsigned\ int\ maxBranchingFactor;
\ \ unsigned\ int\ maxDepth;
\ \ unsigned\ int\ sahBlockSize;
\ \ unsigned\ int\ minLeafSize;
\ \ unsigned\ int\ maxLeafSize;
\ \ float\ traversalCost;
\ \ float\ intersectionCost;

\ \ RTCBVH\ bvh;
\ \ struct\ RTCBuildPrimitive*\ primitives;
\ \ size_t\ primitiveCount;
\ \ size_t\ primitiveArrayCapacity;
\ \ 
\ \ RTCCreateNodeFunction\ createNode;
\ \ RTCSetNodeChildrenFunction\ setNodeChildren;
\ \ RTCSetNodeBoundsFunction\ setNodeBounds;
\ \ RTCCreateLeafFunction\ createLeaf;
\ \ RTCSplitPrimitiveFunction\ splitPrimitive;
\ \ RTCProgressMonitorFunction\ buildProgress;
\ \ void*\ userPtr;
};

struct\ RTCBuildArguments\ rtcDefaultBuildArguments();

void*\ rtcBuildBVH(
\ \ const\ struct\ RTCBuildArguments*\ args
);
\f[]
.fi
.SS DESCRIPTION
.PP
The \f[C]rtcBuildBVH\f[] function can be used to build a BVH in a
user\-defined format over arbitrary primitives.
All arguments to the function are provided through the
\f[C]RTCBuildArguments\f[] structure.
The first member of that structure must be set to the size of the
structure in bytes (\f[C]bytesSize\f[] member) which allows future
extensions of the structure.
It is recommended to initialize the build arguments structure using the
\f[C]rtcDefaultBuildArguments\f[] function.
.PP
The \f[C]rtcBuildBVH\f[] function gets passed the BVH to build
(\f[C]bvh\f[] member), the array of primitives (\f[C]primitives\f[]
member), the capacity of that array (\f[C]primitiveArrayCapacity\f[]
member), the number of primitives stored inside the array
(\f[C]primitiveCount\f[] member), callback function pointers, and a
user\-defined pointer (\f[C]userPtr\f[] member) that is passed to all
callback functions when invoked.
The \f[C]primitives\f[] array can be freed by the application after the
BVH is built.
All callback functions are typically called from multiple threads, thus
their implementation must be thread\-safe.
.PP
Four callback functions must be registered, which are invoked during
build to create BVH nodes (\f[C]createNode\f[] member), to set the
pointers to all children (\f[C]setNodeChildren\f[] member), to set the
bounding boxes of all children (\f[C]setNodeBounds\f[] member), and to
create a leaf node (\f[C]createLeaf\f[] member).
.PP
The function pointer to the primitive split function
(\f[C]splitPrimitive\f[] member) may be \f[C]NULL\f[], however, then no
spatial splitting in high quality mode is possible.
The function pointer used to report the build progress
(\f[C]buildProgress\f[] member) is optional and may also be
\f[C]NULL\f[].
.PP
Further, some build settings are passed to configure the BVH build.
Using the build quality settings (\f[C]buildQuality\f[] member), one can
select between a faster, low quality build which is good for dynamic
scenes, and a standard quality build for static scenes.
One can also specify the desired maximum branching factor of the BVH
(\f[C]maxBranchingFactor\f[] member), the maximum depth the BVH should
have (\f[C]maxDepth\f[] member), the block size for the SAH heuristic
(\f[C]sahBlockSize\f[] member), the minimum and maximum leaf size
(\f[C]minLeafSize\f[] and \f[C]maxLeafSize\f[] member), and the
estimated costs of one traversal step and one primitive intersection
(\f[C]traversalCost\f[] and \f[C]intersectionCost\f[] members).
When enabling the \f[C]RTC_BUILD_FLAG_DYNAMIC\f[] build flags
(\f[C]buildFlags\f[] member), re\-build performance for dynamic scenes
is improved at the cost of higher memory requirements.
.PP
To spatially split primitives in high quality mode, the builder needs
extra space at the end of the build primitive array to store splitted
primitives.
The total capacity of the build primitive array is passed using the
\f[C]primitiveArrayCapacity\f[] member, and should be about twice the
number of primitives when using spatial splits.
.PP
The \f[C]RTCCreateNodeFunc\f[] and \f[C]RTCCreateLeafFunc\f[] callbacks
are passed a thread local allocator object that should be used for fast
allocation of nodes using the \f[C]rtcThreadLocalAlloc\f[] function.
We strongly recommend using this allocation mechanism, as alternative
approaches like standard \f[C]malloc\f[] can be over 10× slower.
The allocator object passed to the create callbacks may be used only
inside the current thread.
Memory allocated using \f[C]rtcThreadLocalAlloc\f[] is automatically
freed when the \f[C]RTCBVH\f[] object is deleted.
If you use your own memory allocation scheme you have to free the memory
yourself when the \f[C]RTCBVH\f[] object is no longer used.
.PP
The \f[C]RTCCreateNodeFunc\f[] callback additionally gets the number of
children for this node in the range from 2 to
\f[C]maxBranchingFactor\f[] (\f[C]childCount\f[] argument).
.PP
The \f[C]RTCSetNodeChildFunc\f[] callback function gets a pointer to the
node as input (\f[C]nodePtr\f[] argument), an array of pointers to the
children (\f[C]childPtrs\f[] argument), and the size of this array
(\f[C]childCount\f[] argument).
.PP
The \f[C]RTCSetNodeBoundsFunc\f[] callback function gets a pointer to
the node as input (\f[C]nodePtr\f[] argument), an array of pointers to
the bounding boxes of the children (\f[C]bounds\f[] argument), and the
size of this array (\f[C]childCount\f[] argument).
.PP
The \f[C]RTCCreateLeafFunc\f[] callback additionally gets an array of
primitives as input (\f[C]primitives\f[] argument), and the size of this
array (\f[C]primitiveCount\f[] argument).
The callback should read the \f[C]geomID\f[] and \f[C]primID\f[] members
from the passed primitives to construct the leaf.
.PP
The \f[C]RTCSplitPrimitiveFunc\f[] callback is invoked in high quality
mode to split a primitive (\f[C]primitive\f[] argument) at the specified
position (\f[C]position\f[] argument) and dimension (\f[C]dimension\f[]
argument).
The callback should return bounds of the clipped left and right parts of
the primitive (\f[C]leftBounds\f[] and \f[C]rightBounds\f[] arguments).
.PP
The \f[C]RTCProgressMonitorFunction\f[] callback function is called with
the estimated completion rate \f[C]n\f[] in the range [0, 1].
Returning \f[C]true\f[] from the callback lets the build continue;
returning \f[C]false\f[] cancels the build.
.SS EXIT STATUS
.PP
On failure an error code is set that can be queried using
\f[C]rtcGetDeviceError\f[].
.SS SEE ALSO
.PP
[rtcNewBVH]