rtcBuildBVH(3)

💖 NAME 💖

rtcBuildBVH — builds a BVH ✨

like, this is the Embree Ray Tracing Kernels 4 (section 3) manual page for rtcBuildBVH, and bestie, it is the glow-up function. it builds a BVH. that's it. that's the whole vibe. 👑

---

🦋 SYNOPSIS 🦋

#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
);

---

🌸 DESCRIPTION 🌸

okay so, the way that rtcBuildBVH works is that it lets you build a BVH in a user-defined format over arbitrary primitives. iconic. you bring the primitives, it brings the tree. 🌳✨

every single argument to the function goes through the RTCBuildArguments structure. and here's the non-negotiable part, bestie: the first member of that structure must be set to the size of the structure in bytes (the bytesSize member) — that's what lets future extensions of the structure happen without breaking you. 💅 the recommended move is to initialize your build arguments structure using the rtcDefaultBuildArguments function, fr fr.

so rtcBuildBVH gets handed:

• the BVH to build — bvh member
• the array of primitives — primitives member
• the capacity of that array — primitiveArrayCapacity member
• the number of primitives actually stored inside the array — primitiveCount member
• callback function pointers
• and a user-defined pointer — userPtr member — that gets passed to all callback functions whenever they're invoked

you can free the primitives array yourself once the BVH is built, no hard feelings. 🫶

⚠️ all callback functions are typically called from multiple threads, so their implementations must be thread-safe. no cap.

🧚 the four mandatory callbacks

four callback functions must be registered, and they get invoked during the build:

• createNode member — creates BVH nodes
• setNodeChildren member — sets the pointers to all children
• setNodeBounds member — sets the bounding boxes of all children
• createLeaf member — creates a leaf node

🌈 the optional ones

• the function pointer to the primitive split function (splitPrimitive member) may be NULL — however, then no spatial splitting in high quality mode is possible. your loss, honestly.
• the function pointer used to report the build progress (buildProgress member) is optional and may also be NULL.

💜 build settings, aka the fun part

further, some build settings get passed in to configure the BVH build:

• the build quality settings (buildQuality member) let you pick between a faster, low quality build — which is good for dynamic scenes — and a standard quality build for static scenes. choose your fighter. 🥊
• the desired maximum branching factor of the BVH — maxBranchingFactor member
• the maximum depth the BVH should have — maxDepth member
• the block size for the SAH heuristic — sahBlockSize member
• the minimum and maximum leaf size — minLeafSize and maxLeafSize members
• the estimated costs of one traversal step and one primitive intersection — traversalCost and intersectionCost members

and when you enable the RTC_BUILD_FLAG_DYNAMIC build flags (buildFlags member), re-build performance for dynamic scenes is improved — at the cost of higher memory requirements. trade-offs, bestie, they're giving ~balance~. ⚖️

🎀 spatial splits need extra room

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 primitiveArrayCapacity member, and it should be about twice the number of primitives when you're using spatial splits. plan accordingly. 📐

🫧 allocators, or: the 10× thing

the RTCCreateNodeFunc and RTCCreateLeafFunc callbacks get passed a thread local allocator object, and you should use it for fast allocation of nodes via the rtcThreadLocalAlloc function.

🔥 we strongly recommend using this allocation mechanism, because alternative approaches like standard malloc can be over 10× slower.

the allocator object passed to the create callbacks may be used only inside the current thread. memory allocated using rtcThreadLocalAlloc is automatically freed when the RTCBVH object is deleted. if you roll your own memory allocation scheme instead, you have to free that memory yourself once the RTCBVH object is no longer used. your memory, your problem. 💀

⭐ the callbacks in detail

• the RTCCreateNodeFunc callback additionally gets the number of children for this node in the range from 2 to maxBranchingFactor — that's the childCount argument.
• the RTCSetNodeChildFunc callback function gets a pointer to the node as input (nodePtr argument), an array of pointers to the children (childPtrs argument), and the size of this array (childCount argument).
• the RTCSetNodeBoundsFunc callback function gets a pointer to the node as input (nodePtr argument), an array of pointers to the bounding boxes of the children (bounds argument), and the size of this array (childCount argument).
• the RTCCreateLeafFunc callback additionally gets an array of primitives as input (primitives argument), and the size of this array (primitiveCount argument). the callback should read the geomID and primID members from the passed primitives to construct the leaf. ✨
• the RTCSplitPrimitiveFunc callback is invoked in high quality mode to split a primitive (primitive argument) at the specified position (position argument) and dimension (dimension argument). the callback should return bounds of the clipped left and right parts of the primitive (leftBounds and rightBounds arguments).
• the RTCProgressMonitorFunction callback function is called with the estimated completion rate n in the range [0, 1]. returning true from the callback lets the build continue; returning false cancels the build. that's your little emergency brake, use it wisely. 🛑

---

🎯 EXIT STATUS 🎯

on failure an error code is set that can be queried using rtcGetDeviceError. so like, always check, bestie. 🙈

---

👀 SEE ALSO 👀

• [rtcNewBVH]

---

and that's the whole page, you ate it up 💅✨ this was rtcBuildBVH(3) straight outta the Embree Ray Tracing Kernels 4 manual, and it's giving main character energy from the first line to the last. go build something gorgeous. 🦋💖🎀🌸🫶