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       The following configuration is supported:
32
33       • threads=[int]: Specifies a number of build threads to use.   A  value
34         of  0 enables all detected hardware threads.  By default all hardware
35         threads are used.
36
37       • user_threads=[int]: Sets the number of user threads that can be  used
38         to  join  and participate in a scene commit using rtcJoinCommitScene.
39         The tasking system will only  use  threads-user_threads  many  worker
40         threads,  thus  if  the app wants to solely use its threads to commit
41         scenes, just set threads equal to user_threads.  This option only has
42         effect with the Intel(R) Threading Building Blocks (TBB) tasking sys‐
43         tem.
44
45       • set_affinity=[0/1]: When enabled, build threads  are  affinitized  to
46         hardware  threads.   This  option  is disabled by default on standard
47         CPUs, and enabled by default on Xeon Phi Processors.
48
49       • start_threads=[0/1]: When enabled, the build threads are started  up‐
50         front.   This  can  be useful for benchmarking to exclude thread cre‐
51         ation time.  This option is disabled by default.
52
53       • isa=[sse2,sse4.2,avx,avx2,avx512]: Use specified ISA.  By default the
54         ISA is selected automatically.
55
56       • max_isa=[sse2,sse4.2,avx,avx2,avx512]:  Configures  the automated ISA
57         selection to use maximally the specified ISA.
58
59       • hugepages=[0/1]: Enables or disables usage of huge pages.  Under Lin‐
60         ux  huge  pages  are used by default but under Windows and macOS they
61         are disabled by default.
62
63       • enable_selockmemoryprivilege=[0/1]: When set to 1, this  enables  the
64         SeLockMemoryPrivilege privilege with is required to use huge pages on
65         Windows.  This option has an effect only under Windows and is ignored
66         on  other  platforms.   See  Section [Huge Page Support] for more de‐
67         tails.
68
69       • verbose=[0,1,2,3]: Sets the verbosity of the output.  When set to  0,
70         no  output is printed by Embree, when set to a higher level more out‐
71         put is printed.  By default Embree does not  print  anything  on  the
72         console.
73
74       • frequency_level=[simd128,simd256,simd512]:  Specifies  the  frequency
75         level the application want to run on, which can be either:
76
77         a) simd128 to run at highest frequency
78
79         b) simd256 to run at AVX2-heavy frequency level
80
81         c) simd512 to run at heavy AVX512 frequency level.   When  some  fre‐
82            quency  level  is specified, Embree will avoid doing optimizations
83            that may reduce the frequency level  below  the  level  specified.
84            E.g.   if your app does not use AVX instructions setting “frequen‐
85            cy_level=simd128” will cause some CPUs to run at highest  frequen‐
86            cy,  which  may result in higher application performance if you do
87            much shading.  If you  application  heavily  uses  AVX  code,  you
88            should  best  set the frequency level to simd256.  Per default Em‐
89            bree tries to avoid reducing the frequency of the CPU  by  setting
90            the simd256 level only when the CPU has no significant down clock‐
91            ing.
92
93       Different configuration options should be separated by commas, e.g.:
94
95              rtcNewDevice("threads=1,isa=avx");
96
97   EXIT STATUS
98       On success returns a handle of the created device.  On failure  returns
99       NULL as device and sets a per-thread error code that can be queried us‐
100       ing rtcGetDeviceError(NULL).
101
102   SEE ALSO
103       [rtcRetainDevice], [rtcReleaseDevice]
104
105
106
107                                                               rtcNewDevice(3)