.\" Automatically generated by Pandoc 1.17.0.3
.\"
.TH "rtcJoinCommitScene" "3" "" "" "Embree Ray Tracing Kernels 3"
.hy
.SS NAME
.IP
.nf
\f[C]
rtcJoinCommitScene\ \-\ commits\ the\ scene\ from\ multiple\ threads
\f[]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include\ <embree3/rtcore.h>

void\ rtcJoinCommitScene(RTCScene\ scene);
\f[]
.fi
.SS DESCRIPTION
.PP
The \f[C]rtcJoinCommitScene\f[] function commits all changes for the
specified scene (\f[C]scene\f[] argument).
The scene commit internally triggers building of a spatial acceleration
structure for the scene.
Ray queries can be performed after scene changes got properly committed.
.PP
The \f[C]rtcJoinCommitScene\f[] function can get called from multiple
user threads which will all cooperate in the build operation.
All threads calling into this function will return from
\f[C]rtcJoinCommitScene\f[] after the scene commit is finished.
All threads must consistently call \f[C]rtcJoinCommitScene\f[] and not
\f[C]rtcCommitScene\f[].
.PP
In contrast to the \f[C]rtcCommitScene\f[] function, the
\f[C]rtcJoinCommitScene\f[] function can be called from multiple user
threads, while the \f[C]rtcCommitScene\f[] can only get called from
multiple TBB worker threads when used concurrently.
For optimal performance we strongly recommend using TBB inside the
application together with the \f[C]rtcCommitScene\f[] function and to
avoid using the \f[C]rtcJoinCommitScene\f[] function.
.PP
The \f[C]rtcJoinCommitScene\f[] feature allows a flexible way to lazily
create hierarchies during rendering.
A thread reaching a not\-yet\-constructed sub\-scene of a two\-level
scene can generate the sub\-scene geometry and call
\f[C]rtcJoinCommitScene\f[] on that just generated scene.
During construction, further threads reaching the not\-yet\-built scene
can join the build operation by also invoking
\f[C]rtcJoinCommitScene\f[].
A thread that calls \f[C]rtcJoinCommitScene\f[] after the build finishes
will directly return from the \f[C]rtcJoinCommitScene\f[] call.
.PP
Multiple scene commit operations on different scenes can be running at
the same time, hence it is possible to commit many small scenes in
parallel, distributing the commits to many threads.
.PP
When using Embree with the Intel® Threading Building Blocks (which is
the default), threads that call \f[C]rtcJoinCommitScene\f[] 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 \f[C]rtcJoinCommitScene\f[]
to join a running build will just trigger the build and wait for the
build to finish.
Further, old TBB versions with
\f[C]TBB_INTERFACE_VERSION_MAJOR\ <\ 8\f[] do not support
\f[C]rtcJoinCommitScene\f[], and invoking this function will result in
an error.
.PP
When using Embree with the internal tasking system, only threads that
call \f[C]rtcJoinCommitScene\f[] will perform the build operation, and
no additional worker threads will be scheduled.
.PP
When using Embree with the Parallel Patterns Library (PPL),
\f[C]rtcJoinCommitScene\f[] is not supported and calling that function
will result in an error.
.PP
To detect whether \f[C]rtcJoinCommitScene\f[] is supported, use the
\f[C]rtcGetDeviceProperty\f[] function.
.SS EXIT STATUS
.PP
On failure an error code is set that can be queried using
\f[C]rtcGetDeviceError\f[].
.SS SEE ALSO
.PP
[rtcCommitScene], [rtcGetDeviceProperty]