libigl_Martin/build2/install/share/man/man3/rtcJoinCommitScene.3embree3

.TH "rtcJoinCommitScene" "3" "" "" "Embree Ray Tracing Kernels 3"
.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).
In contrast to the \f[C]rtcCommitScene\f[] function, the
\f[C]rtcJoinCommitScene\f[] function can be called from multiple
threads, which all cooperate in the same scene commit.
All threads will return from this function after the scene commit is
finished.
All threads must consistently call \f[C]rtcJoinCommitScene\f[] and not
\f[C]rtcCommitScene\f[].
.PP
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[] 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]