1rtcNewDevice(3)          Embree Ray Tracing Kernels 3          rtcNewDevice(3)
2
3
4
5   NAME
6              rtcNewDevice - creates a new device
7
8   SYNOPSIS
9              #include <embree3/rtcore.h>
10
11              RTCDevice rtcNewDevice(const char* config);
12
13   DESCRIPTION
14       This function creates a new device and returns a handle to this device.
15       The device object is reference counted with an initial reference  count
16       of 1.  The handle can be released using the rtcReleaseDevice API call.
17
18       The  device  object acts as a class factory for all other object types.
19       All objects created from the device  (like  scenes,  geometries,  etc.)
20       hold  a  reference to the device, thus the device will not be destroyed
21       unless these objects are destroyed first.
22
23       Objects are only compatible if they belong to the same device,  e.g  it
24       is  not  allowed  to create a geometry in one device and attach it to a
25       scene created with a different device.
26
27       A configuration string (config argument) can be passed  to  the  device
28       construction.  This configuration string can be NULL to use the default
29       configuration.
30
31       When creating the device, Embree reads configurations  for  the  device
32       from the following locations in order:
33
34       1) config string passed to the rtcNewDevice function
35
36       2) .embree3 file in the application folder
37
38       3) .embree3 file in the home folder
39
40       Settings  performed  later  overwrite  previous settings.  This way the
41       configuration for the  application  can  be  changed  globally  (either
42       through  the  rtcNewDevice  call  or  through  the .embree3 file in the
43       application folder), and each user has the option to modify the config‐
44       uration to fit their needs.
45
46       The following configuration is supported:
47
48       · threads=[int]:  Specifies  a number of build threads to use.  A value
49         of 0 enables all detected hardware threads.  By default all  hardware
50         threads are used.
51
52       · user_threads=[int]:  Sets the number of user threads that can be used
53         to join and participate in a scene commit  using  rtcJoinCommitScene.
54         The  tasking  system  will  only use threads-user_threads many worker
55         threads, thus if the app wants to solely use its  threads  to  commit
56         scenes, just set threads equal to user_threads.  This option only has
57         effect with the Intel(R) Threading Building Blocks (TBB) tasking sys‐
58         tem.
59
60       · set_affinity=[0/1]:  When  enabled,  build threads are affinitized to
61         hardware threads.  This option is disabled  by  default  on  standard
62         CPUs, and enabled by default on Xeon Phi Processors.
63
64       · start_threads=[0/1]:  When  enabled,  the  build  threads are started
65         upfront.  This can be useful for benchmarking to exclude thread  cre‐
66         ation time.  This option is disabled by default.
67
68       · isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]:  Use  specified  ISA.
69         By default the ISA is selected automatically.
70
71       · max_isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]:  Configures   the
72         automated ISA selection to use maximally the specified ISA.
73
74       · hugepages=[0/1]:  Enables  or  disables  usage  of huge pages.  Under
75         Linux huge pages are used by default but under Windows and macOS they
76         are disabled by default.
77
78       · enable_selockmemoryprivilege=[0/1]:  When  set to 1, this enables the
79         SeLockMemoryPrivilege privilege with is required to use huge pages on
80         Windows.  This option has an effect only under Windows and is ignored
81         on other  platforms.   See  Section  [Huge  Page  Support]  for  more
82         details.
83
84       · ignore_config_files=[0/1]:  When  set  to  1, configuration files are
85         ignored.  Default is 0.
86
87       · verbose=[0,1,2,3]: Sets the verbosity of the output.  When set to  0,
88         no  output is printed by Embree, when set to a higher level more out‐
89         put is printed.  By default Embree does not  print  anything  on  the
90         console.
91
92       · frequency_level=[simd128,simd256,simd512]:  Specifies  the  frequency
93         level the application want to run on, which can be either: a) simd128
94         for  apps  that do not use AVX instructions, b) simd256 for apps that
95         use heavy AVX instruction, c) simd512 for apps that use heavy AVX-512
96         instructions.   When  some  frequency level is specified, Embree will
97         avoid doing optimizations that may reduce the frequency  level  below
98         the level specified.  E.g.  if your app does not use AVX instructions
99         setting "frequency_level=simd128" will cause  some  CPUs  to  run  at
100         highest  frequency,  which  may  result in higher application perfor‐
101         mance.  However, this will prevent Embree from  using  AVX  optimiza‐
102         tions  to  achieve  higher ray tracing performance, thus applications
103         that trace many rays may still perform better with the  default  set‐
104         ting of simd256, even though this reduces frequency on some CPUs.
105
106       Different configuration options should be separated by commas, e.g.:
107
108              rtcNewDevice("threads=1,isa=avx");
109
110   EXIT STATUS
111       On  success returns a handle of the created device.  On failure returns
112       NULL as device and sets a per-thread error code  that  can  be  queried
113       using rtcGetDeviceError(NULL).
114
115   SEE ALSO
116       [rtcRetainDevice], [rtcReleaseDevice]
117
118
119
120                                                               rtcNewDevice(3)