rtcCommitScene(3)

💖 rtcCommitScene — like, the glow-up moment for your scene 💖

okay bestie, this is rtcCommitScene(3) from the Embree Ray Tracing Kernels 4 era, and she is THE main character of scene setup. let's get into it 🫶

---

✨ NAME ✨

rtcCommitScene — commits scene changes. that's it, that's the job, and she ate 💅

---

🌸 SYNOPSIS 🌸

#include <embree4/rtcore.h>

void rtcCommitScene(RTCScene scene);

---

🦋 DESCRIPTION 🦋

so the rtcCommitScene function commits all changes for the specified scene — that's the scene argument, bestie, the one you're handing over. internally? it triggers building of a spatial acceleration structure for the scene, and it uses all available worker threads to do it. like, it's giving full squad energy. 🏃‍♀️💨

and here's the tea: ray queries can be performed only after committing all scene changes. no commit, no rays. periodt.

if your app uses TBB 2019 Update 9 or later for parallelization of rendering, then lazy scene construction during rendering is supported by rtcCommitScene. so yes, rtcCommitScene can get called from multiple TBB worker threads concurrently for the same scene — iconic multitasking. when that happens, the function will internally isolate the scene construction using a tbb::isolated_task_group. 🧚

there's also the alternative approach of using rtcJoinCommitScene, which uses an tbb:task_arena internally, but honestly? not recommended — that one comes with high runtime overhead. 💀

now listen, this part is important:

if scene geometries get modified or attached or detached, the rtcCommitScene call must be invoked before performing any further ray queries for the scene. otherwise the effect of the ray query is undefined. 😭

the modification of a geometry, committing the scene, and tracing of rays must always happen sequentially, and never at the same time. and any API call that sets a property of the scene or geometries contained in the scene counts as scene modification — yes, even including setting of intersection filter functions. 👑

the kind of acceleration structure built can be influenced using scene flags (see rtcSetSceneFlags), and the quality can be specified using the rtcSetSceneBuildQuality function. choose your fighter ✨

also, Embree silently ignores primitives during spatial acceleration structure construction that would cause numerical issues — like primitives containing NaNs, INFs, or values greater than 1.844E18f. because no reasonable calculations can be performed with such values without causing overflows. she's just not doing that math, fr fr 🙈

and if the RTCDevice associated with the scene is a SYCL device, rtcCommitScene will internally create a temporary SYCL queue to issue memory transfers from host to device memory. in this case, the call to rtcCommitScene will be blocking and return only after the memory transfers are completed and SYCL kernels can traverse the scene savely on the device. 🫶

if you want to commit all changes for the specified scene asynchronously instead, the function rtcCommitSceneWithQueue is your girl. and heads up: handles to traversal objects (RTCTraversable type) that have been aquired before a call to rtcCommitScene will be invalidated. use rtcGetSceneTraversable to get a valid handle from the scene after every scene commit. don't forget, bestie, i'm begging 🙏

---

💀 EXIT STATUS 💀

on failure an error code is set that can be queried using rtcGetDeviceError. so check it. no cap.

---

🌈 SEE ALSO 🌈

• [rtcCommitSceneWithQueue]
• [rtcJoinCommitScene]

---

and that's the whole page, gorgeous ✨ this was rtcCommitScene(3), straight outta Embree Ray Tracing Kernels 4 — stay committed, stay slay, and go build that acceleration structure 💖🎀🦋