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