.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "rtcBuildBVH" "3" "" "" "Embree Ray Tracing Kernels 4"
.hy
.SS NAME
.IP
.nf
\f[C]
rtcBuildBVH - builds a BVH
\f[R]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <embree4/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[R]
.fi
.SS DESCRIPTION
.PP
The \f[C]rtcBuildBVH\f[R] 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[R] structure.
The first member of that structure must be set to the size of the
structure in bytes (\f[C]bytesSize\f[R] member) which allows future
extensions of the structure.
It is recommended to initialize the build arguments structure using the
\f[C]rtcDefaultBuildArguments\f[R] function.
.PP
The \f[C]rtcBuildBVH\f[R] function gets passed the BVH to build
(\f[C]bvh\f[R] member), the array of primitives (\f[C]primitives\f[R]
member), the capacity of that array (\f[C]primitiveArrayCapacity\f[R]
member), the number of primitives stored inside the array
(\f[C]primitiveCount\f[R] member), callback function pointers, and a
user-defined pointer (\f[C]userPtr\f[R] member) that is passed to all
callback functions when invoked.
The \f[C]primitives\f[R] 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[R] member), to set the
pointers to all children (\f[C]setNodeChildren\f[R] member), to set the
bounding boxes of all children (\f[C]setNodeBounds\f[R] member), and to
create a leaf node (\f[C]createLeaf\f[R] member).
.PP
The function pointer to the primitive split function
(\f[C]splitPrimitive\f[R] member) may be \f[C]NULL\f[R], however, then
no spatial splitting in high quality mode is possible.
The function pointer used to report the build progress
(\f[C]buildProgress\f[R] member) is optional and may also be
\f[C]NULL\f[R].
.PP
Further, some build settings are passed to configure the BVH build.
Using the build quality settings (\f[C]buildQuality\f[R] 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[R] member), the maximum depth the BVH should
have (\f[C]maxDepth\f[R] member), the block size for the SAH heuristic
(\f[C]sahBlockSize\f[R] member), the minimum and maximum leaf size
(\f[C]minLeafSize\f[R] and \f[C]maxLeafSize\f[R] member), and the
estimated costs of one traversal step and one primitive intersection
(\f[C]traversalCost\f[R] and \f[C]intersectionCost\f[R] members).
When enabling the \f[C]RTC_BUILD_FLAG_DYNAMIC\f[R] build flags
(\f[C]buildFlags\f[R] 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 split
primitives.
The total capacity of the build primitive array is passed using the
\f[C]primitiveArrayCapacity\f[R] member, and should be about twice the
number of primitives when using spatial splits.
.PP
The \f[C]RTCCreateNodeFunc\f[R] and \f[C]RTCCreateLeafFunc\f[R]
callbacks are passed a thread local allocator object that should be used
for fast allocation of nodes using the \f[C]rtcThreadLocalAlloc\f[R]
function.
We strongly recommend using this allocation mechanism, as alternative
approaches like standard \f[C]malloc\f[R] can be over 10\[tmu] slower.
The allocator object passed to the create callbacks may be used only
inside the current thread.
Memory allocated using \f[C]rtcThreadLocalAlloc\f[R] is automatically
freed when the \f[C]RTCBVH\f[R] object is deleted.
If you use your own memory allocation scheme you have to free the memory
yourself when the \f[C]RTCBVH\f[R] object is no longer used.
.PP
The \f[C]RTCCreateNodeFunc\f[R] callback additionally gets the number of
children for this node in the range from 2 to
\f[C]maxBranchingFactor\f[R] (\f[C]childCount\f[R] argument).
.PP
The \f[C]RTCSetNodeChildFunc\f[R] callback function gets a pointer to
the node as input (\f[C]nodePtr\f[R] argument), an array of pointers to
the children (\f[C]childPtrs\f[R] argument), and the size of this array
(\f[C]childCount\f[R] argument).
.PP
The \f[C]RTCSetNodeBoundsFunc\f[R] callback function gets a pointer to
the node as input (\f[C]nodePtr\f[R] argument), an array of pointers to
the bounding boxes of the children (\f[C]bounds\f[R] argument), and the
size of this array (\f[C]childCount\f[R] argument).
.PP
The \f[C]RTCCreateLeafFunc\f[R] callback additionally gets an array of
primitives as input (\f[C]primitives\f[R] argument), and the size of
this array (\f[C]primitiveCount\f[R] argument).
The callback should read the \f[C]geomID\f[R] and \f[C]primID\f[R]
members from the passed primitives to construct the leaf.
.PP
The \f[C]RTCSplitPrimitiveFunc\f[R] callback is invoked in high quality
mode to split a primitive (\f[C]primitive\f[R] argument) at the
specified position (\f[C]position\f[R] argument) and dimension
(\f[C]dimension\f[R] argument).
The callback should return bounds of the clipped left and right parts of
the primitive (\f[C]leftBounds\f[R] and \f[C]rightBounds\f[R]
arguments).
.PP
The \f[C]RTCProgressMonitorFunction\f[R] callback function is called
with the estimated completion rate \f[C]n\f[R] in the range
[0,\[u2006]1].
Returning \f[C]true\f[R] from the callback lets the build continue;
returning \f[C]false\f[R] cancels the build.
.SS EXIT STATUS
.PP
On failure an error code is set that can be queried using
\f[C]rtcGetDeviceError\f[R].
.SS SEE ALSO
.PP
[rtcNewBVH]