1rtcNewDevice(3)          Embree Ray Tracing Kernels 4          rtcNewDevice(3)
2
3
4
5   NAME
6              rtcNewDevice - creates a new device
7
8   SYNOPSIS
9              #include <embree4/rtcore.h>
10
11              RTCDevice rtcNewDevice(const char* config);
12
13   DESCRIPTION
14       This  function  creates a new device to be used for CPU ray tracing and
15       returns a handle to this device.  The device object is reference count‐
16       ed  with  an  initial reference count of 1.  The handle can be released
17       using the rtcReleaseDevice API call.
18
19       The device object acts as a class factory for all other  object  types.
20       All  objects  created  from  the device (like scenes, geometries, etc.)
21       hold a reference to the device, thus the device will not  be  destroyed
22       unless these objects are destroyed first.
23
24       Objects  are  only compatible if they belong to the same device, e.g it
25       is not allowed to create a geometry in one device and attach  it  to  a
26       scene created with a different device.
27
28       A  configuration  string  (config argument) can be passed to the device
29       construction.  This configuration string can be NULL to use the default
30       configuration.
31
32       The following configuration is supported:
33
34       • threads=[int]:  Specifies  a number of build threads to use.  A value
35         of 0 enables all detected hardware threads.  By default all  hardware
36         threads are used.
37
38       • user_threads=[int]:  Sets the number of user threads that can be used
39         to join and participate in a scene commit  using  rtcJoinCommitScene.
40         The  tasking  system  will  only use threads-user_threads many worker
41         threads, thus if the app wants to solely use its  threads  to  commit
42         scenes, just set threads equal to user_threads.  This option only has
43         effect with the Intel(R) Threading Building Blocks (TBB) tasking sys‐
44         tem.
45
46       • set_affinity=[0/1]:  When  enabled,  build threads are affinitized to
47         hardware threads.  This option is disabled  by  default  on  standard
48         CPUs, and enabled by default on Xeon Phi Processors.
49
50       • start_threads=[0/1]:  When enabled, the build threads are started up‐
51         front.  This can be useful for benchmarking to  exclude  thread  cre‐
52         ation time.  This option is disabled by default.
53
54       • isa=[sse2,sse4.2,avx,avx2,avx512]: Use specified ISA.  By default the
55         ISA is selected automatically.
56
57       • max_isa=[sse2,sse4.2,avx,avx2,avx512]: Configures the  automated  ISA
58         selection to use maximally the specified ISA.
59
60       • hugepages=[0/1]: Enables or disables usage of huge pages.  Under Lin‐
61         ux huge pages are used by default but under Windows  and  macOS  they
62         are disabled by default.
63
64       • enable_selockmemoryprivilege=[0/1]:  When  set to 1, this enables the
65         SeLockMemoryPrivilege privilege with is required to use huge pages on
66         Windows.  This option has an effect only under Windows and is ignored
67         on other platforms.  See Section [Huge Page  Support]  for  more  de‐
68         tails.
69
70       • verbose=[0,1,2,3]:  Sets the verbosity of the output.  When set to 0,
71         no output is printed by Embree, when set to a higher level more  out‐
72         put  is  printed.   By  default Embree does not print anything on the
73         console.
74
75       • frequency_level=[simd128,simd256,simd512]:  Specifies  the  frequency
76         level the application want to run on, which can be either:
77
78         a) simd128 to run at highest frequency
79
80         b) simd256 to run at AVX2-heavy frequency level
81
82         c) simd512  to  run  at heavy AVX512 frequency level.  When some fre‐
83            quency level is specified, Embree will avoid  doing  optimizations
84            that  may  reduce  the  frequency level below the level specified.
85            E.g.  if your app does not use AVX instructions setting  “frequen‐
86            cy_level=simd128”  will cause some CPUs to run at highest frequen‐
87            cy, which may result in higher application performance if  you  do
88            much  shading.   If  you  application  heavily  uses AVX code, you
89            should best set the frequency level to simd256.  Per  default  Em‐
90            bree  tries  to avoid reducing the frequency of the CPU by setting
91            the simd256 level only when the CPU has no significant down clock‐
92            ing.
93
94       Different configuration options should be separated by commas, e.g.:
95
96              rtcNewDevice("threads=1,isa=avx");
97
98   EXIT STATUS
99       On  success returns a handle of the created device.  On failure returns
100       NULL as device and sets a per-thread error code that can be queried us‐
101       ing rtcGetDeviceError(NULL).
102
103   SEE ALSO
104       [rtcRetainDevice], [rtcReleaseDevice], [rtcNewSYCLDevice]
105
106
107
108                                                               rtcNewDevice(3)
Impressum