1rtcJoinCommitScene(3)    Embree Ray Tracing Kernels 3    rtcJoinCommitScene(3)
2
3
4
5   NAME
6              rtcJoinCommitScene - commits the scene from multiple threads
7
8   SYNOPSIS
9              #include <embree3/rtcore.h>
10
11              void rtcJoinCommitScene(RTCScene scene);
12
13   DESCRIPTION
14       The  rtcJoinCommitScene  function commits all changes for the specified
15       scene (scene argument).  In contrast to  the  rtcCommitScene  function,
16       the  rtcJoinCommitScene  function  can be called from multiple threads,
17       which all cooperate in the same scene commit.  All threads will  return
18       from  this  function  after  the scene commit is finished.  All threads
19       must consistently call rtcJoinCommitScene and not rtcCommitScene.
20
21       The scene commit internally triggers building of a spatial acceleration
22       structure  for  the  scene.   Ray  queries can be performed after scene
23       changes got properly committed.
24
25       The rtcJoinCommitScene feature allows a flexible way to  lazily  create
26       hierarchies  during rendering.  A thread reaching a not-yet-constructed
27       sub-scene of a two-level scene can generate the sub-scene geometry  and
28       call rtcJoinCommitScene on that just generated scene.  During construc‐
29       tion, further threads reaching the not-yet-built  scene  can  join  the
30       build  operation  by  also  invoking rtcJoinCommitScene.  A thread that
31       calls rtcJoinCommitScene after the build finishes will directly  return
32       from the rtcJoinCommitScene call.
33
34       Multiple  scene commit operations on different scenes can be running at
35       the same time, hence it is possible to commit many small scenes in par‐
36       allel, distributing the commits to many threads.
37
38       When  using  Embree with the Intel® Threading Building Blocks (which is
39       the default), threads that call rtcJoinCommitScene will join the  build
40       operation,  but  other TBB worker threads might also participate in the
41       build.  To avoid thread oversubscription, we recommend using  TBB  also
42       inside  the  application.   Further,  the join mode only works properly
43       starting with TBB v4.4 Update 1.  For  earlier  TBB  versions,  threads
44       that  call rtcJoinCommitScene to join a running build will just trigger
45       the build and wait for the build to finish.  Further, old TBB  versions
46       with TBB_INTERFACE_VERSION_MAJOR < 8 do not support rtcJoinCommitScene,
47       and invoking this function will result in an error.
48
49       When using Embree with the internal tasking system, only  threads  that
50       call  rtcJoinCommitScene will perform the build operation, and no addi‐
51       tional worker threads will be scheduled.
52
53       When using Embree with the Parallel Patterns Library (PPL), rtcJoinCom‐
54       mitScene  is  not supported and calling that function will result in an
55       error.
56
57       To detect whether rtcJoinCommitScene is supported, use the  rtcGetDevi‐
58       ceProperty function.
59
60   EXIT STATUS
61       On  failure  an  error  code is set that can be queried using rtcGetDe‐
62       viceError.
63
64   SEE ALSO
65       [rtcCommitScene], [rtcGetDeviceProperty]
66
67
68
69                                                         rtcJoinCommitScene(3)