rtcJoinCommitScene(3)

💅 rtcJoinCommitScene — bestie edition

okay so you found the rtcJoinCommitScene(3) page, and it lives in the Embree Ray Tracing Kernels 4 manual, so you already know it's the real deal. sit down, hydrate, we're learning how to commit a scene from a whole crowd of threads at once 🫶

---

✨ NAME ✨

rtcJoinCommitScene — commits the scene from multiple threads 💖

---

🎀 SYNOPSIS 🎀

#include <embree4/rtcore.h>

void rtcJoinCommitScene(RTCScene scene);

---

🌸 DESCRIPTION 🌸

so rtcJoinCommitScene commits all the changes you made to the scene you pass in as the scene argument. and like, "commits" here is doing the heavy lifting: internally the commit triggers building a spatial acceleration structure for the scene. only after those scene changes got properly committed can you actually go do ray queries. no skipping the line, bestie 🚧

here's the iconic part: rtcJoinCommitScene can get called from multiple user threads, and all of them will cooperate in the build operation. every thread that calls into this function returns from rtcJoinCommitScene once the scene commit is finished. and it's all or nothing — all threads must consistently call rtcJoinCommitScene and not rtcCommitScene. no mixing, that's the rule ✋

okay so contrast time, because this is the whole vibe of the function. rtcCommitScene can only get called from multiple TBB worker threads when used concurrently. rtcJoinCommitScene is the one that can be called from multiple user threads. and here's the part you're gonna want to hear: for optimal performance we strongly recommend using TBB inside the application together with the rtcCommitScene function, and to avoid using the rtcJoinCommitScene function. like, yes the join one is cooler, but the boring one is faster in the recommended setup 😭

now the fun use case. rtcJoinCommitScene lets you lazily create hierarchies during rendering, which is very flexible and honestly very main character. picture it: a thread reaches a not-yet-constructed sub-scene of a two-level scene, so it generates that sub-scene geometry and calls rtcJoinCommitScene on the just-generated scene. while construction is happening, further threads that reach the not-yet-built scene can join the build operation by also invoking rtcJoinCommitScene. and a thread that calls rtcJoinCommitScene after the build finishes just directly returns from the rtcJoinCommitScene call. no drama, no waiting 🦋

also!! multiple scene commit operations on different scenes can be running at the same time. so yes, you can commit many small scenes in parallel and distribute the commits to many threads. parallel queen behaviour 👑

now the messy details, because there are several, and you need all of them:

• when you're using Embree with the Intel® Threading Building Blocks (which is the default), threads that call rtcJoinCommitScene will join the build operation, but other TBB worker threads might also participate in the build. to avoid thread oversubscription, we recommend using TBB also inside the application.
• further, the join mode only works properly starting with TBB v4.4 Update 1. for earlier TBB versions, threads that call rtcJoinCommitScene to join a running build will just trigger the build and wait for the build to finish. so like, they're joining in spirit only 🙈
• further, old TBB versions with TBB_INTERFACE_VERSION_MAJOR < 8 do not support rtcJoinCommitScene, and invoking this function will result in an error. not a vibe. an error.
• when you're using Embree with the internal tasking system, only threads that call rtcJoinCommitScene will perform the build operation, and no additional worker threads will be scheduled.
• when you're using Embree with the Parallel Patterns Library (PPL), rtcJoinCommitScene is not supported and calling that function will result in an error.

💀 PPL girlies and ancient-TBB girlies, this function is simply not for you and it will error out. check before you call, always.

and to detect whether rtcJoinCommitScene is supported at all, use the rtcGetDeviceProperty function. that's your vibe check 🔍

---

⚠️ EXIT STATUS ⚠️

on failure an error code is set that can be queried using rtcGetDeviceError. so if something went wrong, that's where the receipts live 🧾

---

👀 SEE ALSO 👀

• rtcCommitScene
• rtcGetDeviceProperty

---

that's the whole page, bestie, you ate it 💅✨ this was page rtcJoinCommitScene(3) from the Embree Ray Tracing Kernels 4 manual — go forth and commit responsibly, and remember: all threads consistent, no mixing, periodt 🎀🫶🌈