libigl_Martin/build2/install/share/man/man3/rtcNewDevice.3embree3

.TH "rtcNewDevice" "3" "" "" "Embree Ray Tracing Kernels 3"
.SS NAME
.IP
.nf
\f[C]
rtcNewDevice\ \-\ creates\ a\ new\ device
\f[]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include\ <embree3/rtcore.h>

RTCDevice\ rtcNewDevice(const\ char*\ config);
\f[]
.fi
.SS DESCRIPTION
.PP
This function creates a new device and returns a handle to this device.
The device object is reference counted with an initial reference count
of 1.
The handle can be released using the \f[C]rtcReleaseDevice\f[] API call.
.PP
The device object acts as a class factory for all other object types.
All objects created from the device (like scenes, geometries, etc.) hold
a reference to the device, thus the device will not be destroyed unless
these objects are destroyed first.
.PP
Objects are only compatible if they belong to the same device, e.g it is
not allowed to create a geometry in one device and attach it to a scene
created with a different device.
.PP
A configuration string (\f[C]config\f[] argument) can be passed to the
device construction.
This configuration string can be \f[C]NULL\f[] to use the default
configuration.
.PP
When creating the device, Embree reads configurations for the device
from the following locations in order:
.IP "1)" 3
\f[C]config\f[] string passed to the \f[C]rtcNewDevice\f[] function
.IP "2)" 3
\f[C]\&.embree3\f[] file in the application folder
.IP "3)" 3
\f[C]\&.embree3\f[] file in the home folder
.PP
Settings performed later overwrite previous settings.
This way the configuration for the application can be changed globally
(either through the \f[C]rtcNewDevice\f[] call or through the
\f[C]\&.embree3\f[] file in the application folder), and each user has
the option to modify the configuration to fit their needs.
.PP
The following configuration is supported:
.IP \[bu] 2
\f[C]threads=[int]\f[]: Specifies a number of build threads to use.
A value of 0 enables all detected hardware threads.
By default all hardware threads are used.
.IP \[bu] 2
\f[C]set_affinity=[0/1]\f[]: When enabled, build threads are affinitized
to hardware threads.
This option is disabled by default on standard CPUs, and enabled by
default on Xeon Phi Processors.
.IP \[bu] 2
\f[C]start_threads=[0/1]\f[]: When enabled, the build threads are
started upfront.
This can be useful for benchmarking to exclude thread creation time.
This option is disabled by default.
.IP \[bu] 2
\f[C]isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]\f[]: Use specified
ISA.
By default the ISA is selected automatically.
.IP \[bu] 2
\f[C]max_isa=[sse2,sse4.2,avx,avx2,avx512knl,avx512skx]\f[]: Configures
the automated ISA selection to use maximally the specified ISA.
.IP \[bu] 2
\f[C]hugepages=[0/1]\f[]: Enables or disables usage of huge pages.
Under Linux huge pages are used by default but under Windows and macOS
they are disabled by default.
.IP \[bu] 2
\f[C]enable_selockmemoryprivilege=[0/1]\f[]: When set to 1, this enables
the \f[C]SeLockMemoryPrivilege\f[] privilege with is required to use
huge pages on Windows.
This option has an effect only under Windows and is ignored on other
platforms.
See Section [Huge Page Support] for more details.
.IP \[bu] 2
\f[C]ignore_config_files=[0/1]\f[]: When set to 1, configuration files
are ignored.
Default is 0.
.IP \[bu] 2
\f[C]verbose=[0,1,2,3]\f[]: Sets the verbosity of the output.
When set to 0, no output is printed by Embree, when set to a higher
level more output is printed.
By default Embree does not print anything on the console.
.IP \[bu] 2
\f[C]frequency_level=[simd128,simd256,simd512]\f[]: Specifies the
frequency level the application want to run on, which can be either: a)
simd128 for apps that do not use AVX instructions, b) simd256 for apps
that use heavy AVX instruction, c) simd512 for apps that use heavy
AVX\-512 instructions.
When some frequency level is specified, Embree will avoid doing
optimizations that may reduce the frequency level below the level
specified.
E.g.
if your app does not use AVX instructions setting
"frequency_level=simd128" will cause some CPUs to run at highest
frequency, which may result in higher application performance.
However, this will prevent Embree from using AVX optimizations to
achieve higher ray tracing performance, thus applications that trace
many rays may still perform better with the default setting of simd256,
even though this reduces frequency on some CPUs.
.PP
Different configuration options should be separated by commas, e.g.:
.IP
.nf
\f[C]
rtcNewDevice("threads=1,isa=avx");
\f[]
.fi
.SS EXIT STATUS
.PP
On success returns a handle of the created device.
On failure returns \f[C]NULL\f[] as device and sets a per\-thread error
code that can be queried using \f[C]rtcGetDeviceError(NULL)\f[].
.SS SEE ALSO
.PP
[rtcRetainDevice], [rtcReleaseDevice]