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 ap‐
43       plication folder), and each user has the option to modify the  configu‐
44       ration 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 up‐
65         front.  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 Lin‐
75         ux 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  de‐
82         tails.
83
84       · ignore_config_files=[0/1]: When set to 1, configuration files are ig‐
85         nored.  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:
94
95       a) simd128 to run at highest frequency
96
97       b) simd256 to run at AVX2-heavy frequency level
98
99       c) simd512 to run at heavy AVX512 frequency level.  When some frequency
100          level  is  specified, Embree will avoid doing optimizations that may
101          reduce the frequency level below the level specified.  E.g.  if your
102          app  does not use AVX instructions setting "frequency_level=simd128"
103          will cause some CPUs to run at highest frequency, which  may  result
104          in  higher  application  performance if you do much shading.  If you
105          application heavily uses AVX code, you should best set the frequency
106          level  to  simd256.   Per default Embree tries to avoid reducing the
107          frequency of the CPU by setting the simd256 level only when the  CPU
108          has no significant down clocking.
109
110       Different configuration options should be separated by commas, e.g.:
111
112              rtcNewDevice("threads=1,isa=avx");
113
114   EXIT STATUS
115       On  success returns a handle of the created device.  On failure returns
116       NULL as device and sets a per-thread error code that can be queried us‐
117       ing rtcGetDeviceError(NULL).
118
119   SEE ALSO
120       [rtcRetainDevice], [rtcReleaseDevice]
121
122
123
124                                                               rtcNewDevice(3)