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       · set_affinity=[0/1]:  When  enabled,  build threads are affinitized to
53         hardware threads.  This option is disabled  by  default  on  standard
54         CPUs, and enabled by default on Xeon Phi Processors.
55
56       · start_threads=[0/1]:  When  enabled,  the  build  threads are started
57         upfront.  This can be useful for benchmarking to exclude thread  cre‐
58         ation time.  This option is disabled by default.
59
60       · isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]:  Use  specified  ISA.
61         By default the ISA is selected automatically.
62
63       · max_isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]:  Configures   the
64         automated ISA selection to use maximally the specified ISA.
65
66       · hugepages=[0/1]:  Enables  or  disables  usage  of huge pages.  Under
67         Linux huge pages are used by default but under Windows and macOS they
68         are disabled by default.
69
70       · enable_selockmemoryprivilege=[0/1]:  When  set to 1, this enables the
71         SeLockMemoryPrivilege privilege with is required to use huge pages on
72         Windows.  This option has an effect only under Windows and is ignored
73         on other  platforms.   See  Section  [Huge  Page  Support]  for  more
74         details.
75
76       · ignore_config_files=[0/1]:  When  set  to  1, configuration files are
77         ignored.  Default is 0.
78
79       · verbose=[0,1,2,3]: Sets the verbosity of the output.  When set to  0,
80         no  output is printed by Embree, when set to a higher level more out‐
81         put is printed.  By default Embree does not  print  anything  on  the
82         console.
83
84       · frequency_level=[simd128,simd256,simd512]:  Specifies  the  frequency
85         level the application want to run on, which can be either: a) simd128
86         for  apps  that do not use AVX instructions, b) simd256 for apps that
87         use heavy AVX instruction, c) simd512 for apps that use heavy AVX-512
88         instructions.   When  some  frequency level is specified, Embree will
89         avoid doing optimizations that may reduce the frequency  level  below
90         the level specified.  E.g.  if your app does not use AVX instructions
91         setting "frequency_level=simd128" will cause  some  CPUs  to  run  at
92         highest  frequency,  which  may  result in higher application perfor‐
93         mance.  However, this will prevent Embree from  using  AVX  optimiza‐
94         tions  to  achieve  higher ray tracing performance, thus applications
95         that trace many rays may still perform better with the  default  set‐
96         ting of simd256, even though this reduces frequency on some CPUs.
97
98       Different configuration options should be separated by commas, e.g.:
99
100              rtcNewDevice("threads=1,isa=avx");
101
102   EXIT STATUS
103       On  success returns a handle of the created device.  On failure returns
104       NULL as device and sets a per-thread error code  that  can  be  queried
105       using rtcGetDeviceError(NULL).
106
107   SEE ALSO
108       [rtcRetainDevice], [rtcReleaseDevice]
109
110
111
112                                                               rtcNewDevice(3)