.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "rtcCommitScene" "3" "" "" "Embree Ray Tracing Kernels 4"
.SS NAME
.IP
.EX
rtcCommitScene \- commits scene changes
.EE
.SS SYNOPSIS
.IP
.EX
#include <embree4/rtcore.h>

void rtcCommitScene(RTCScene scene);
.EE
.SS DESCRIPTION
The \f[CR]rtcCommitScene\f[R] function commits all changes for the
specified scene (\f[CR]scene\f[R] argument).
This internally triggers building of a spatial acceleration structure
for the scene using all available worker threads.
Ray queries can be performed only after committing all scene changes.
.PP
If the application uses TBB 2019 Update 9 or later for parallelization
of rendering, lazy scene construction during rendering is supported by
\f[CR]rtcCommitScene\f[R].
Therefore \f[CR]rtcCommitScene\f[R] can get called from multiple TBB
worker threads concurrently for the same scene.
The \f[CR]rtcCommitScene\f[R] function will then internally isolate the
scene construction using a tbb::isolated_task_group.
The alternative approach of using \f[CR]rtcJoinCommitScene\f[R] which
uses an tbb:task_arena internally, is not recommended due to it\[cq]s
high runtime overhead.
.PP
If scene geometries get modified or attached or detached, the
\f[CR]rtcCommitScene\f[R] 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.
Any API call that sets a property of the scene or geometries contained
in the scene count as scene modification, e.g.\ including setting of
intersection filter functions.
.PP
The kind of acceleration structure built can be influenced using scene
flags (see \f[CR]rtcSetSceneFlags\f[R]), and the quality can be
specified using the \f[CR]rtcSetSceneBuildQuality\f[R] function.
.PP
Embree silently ignores primitives during spatial acceleration structure
construction that would cause numerical issues, e.g.\ primitives
containing NaNs, INFs, or values greater than 1.844E18f (as no
reasonable calculations can be performed with such values without
causing overflows).
.PP
In case the RTCDevice associated with the \f[CR]scene\f[R] is a SYCL
device, \f[CR]rtcCommitScene\f[R] will internally create a temporary
SYCL queue to issue memory transfers from host to device memory.
In this case, the call to \f[CR]rtcCommitScene\f[R] will be blocking and
return only after the memory transfers are completed and SYCL kernels
can traverse the scene savely on the device.
The function \f[CR]rtcCommitSceneWithQueue\f[R] can be used to commit
all changes for the specified scene asynchronously.
Handles to traversal objects (\f[CR]RTCTraversable\f[R] type) that have
been aquired before a call to \f[CR]rtcCommitScene\f[R] will be
invalidated.
Use \f[CR]rtcGetSceneTraversable\f[R] to get a valid handle from the
scene after every scene commit.
.SS EXIT STATUS
On failure an error code is set that can be queried using
\f[CR]rtcGetDeviceError\f[R].
.SS SEE ALSO
[rtcCommitSceneWithQueue], [rtcJoinCommitScene]