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       Different configuration options should be separated by commas, e.g.:
85
86              rtcNewDevice("threads=1,isa=avx");
87
88   EXIT STATUS
89       On  success returns a handle of the created device.  On failure returns
90       NULL as device and sets a per-thread error code  that  can  be  queried
91       using rtcDeviceGetError(NULL).
92
93   SEE ALSO
94       [rtcRetainDevice], [rtcReleaseDevice]
95
96
97
98                                                               rtcNewDevice(3)