rtcNewDevice(3)

rtcNewDevice(3) 💖

okay bestie, we're in the Embree Ray Tracing Kernels 4 manual and this is the page about rtcNewDevice(3) — the lil function that spawns a whole device for you. it's giving main character energy, fr fr. 🎀

---

✨ NAME ✨

rtcNewDevice — creates a new device 🦋

---

✨ SYNOPSIS ✨

#include <embree4/rtcore.h>

RTCDevice rtcNewDevice(const char* config);

---

✨ DESCRIPTION ✨

so this function literally creates a brand new device for you to use for CPU ray tracing, and hands you back a handle to it. that's it, that's the vibe. ✨

the device object is reference counted, and it starts life with an initial reference count of 1. when you're done with it you can let it go using the rtcReleaseDevice API call. 🫶

here's the tea tho: the device object is basically a class factory for every other object type. every single object you create from the device (scenes, geometries, etc.) holds its own reference to that device — so bestie, the device will not be destroyed unless all those objects get destroyed first. it's holding on for dear life 😭

and like… objects are only compatible if they belong to the same device. you can't make a geometry in one device and attach it to a scene that was created with a different device. no cross-device situationships allowed, periodt. 💅

you can also pass a configuration string (the config argument) to the device construction. that config string can be NULL if you just want the default configuration. easy.

the config options that are supported 🎀

• threads=[int] — specifies how many build threads to use. a value of 0 enables all detected hardware threads. by default, all hardware threads are used. ⭐
• user_threads=[int] — sets the number of user threads that are allowed to join and participate in a scene commit using rtcJoinCommitScene. the tasking system will only use threads-user_threads many worker threads, so if your app wants to solely use its own threads to commit scenes, just set threads equal to user_threads. heads up: this option only has effect with the Intel(R) Threading Building Blocks (TBB) tasking system.
• set_affinity=[0/1] — when enabled, build threads get affinitized to hardware threads. this one is disabled by default on standard CPUs, and enabled by default on Xeon Phi Processors. 👑
• start_threads=[0/1] — when enabled, the build threads get started upfront. lowkey useful for benchmarking so you can exclude thread creation time from your numbers. this option is disabled by default.
• isa=[sse2,sse4.2,avx,avx2,avx512] — use the specified ISA. by default the ISA is selected automatically. 🤖
• max_isa=[sse2,sse4.2,avx,avx2,avx512] — configures the automated ISA selection to use maximally the specified ISA.
• hugepages=[0/1] — enables or disables usage of huge pages. under Linux huge pages are used by default, but under Windows and macOS they're disabled by default. 🐘
• enable_selockmemoryprivilege=[0/1] — when set to 1, this enables the SeLockMemoryPrivilege privilege, which is required to use huge pages on Windows. this option only has an effect under Windows and is ignored on other platforms. see Section [Huge Page Support] for more details.
• verbose=[0,1,2,3] — 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. (silent queen 💀)
• frequency_level=[simd128,simd256,simd512] — specifies the frequency level the application wants to run on, which can be either:
  • a) simd128 — to run at highest frequency
  • b) simd256 — to run at AVX2-heavy frequency level
  • c) simd512 — to run at heavy AVX512 frequency level. 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 if you do much shading. if your application heavily uses AVX code, you should best set the frequency level to simd256. per default Embree tries to avoid reducing the frequency of the CPU by setting the simd256 level only when the CPU has no significant down clocking. 🌸

different configuration options should be separated by commas, e.g.:

rtcNewDevice("threads=1,isa=avx");

---

✨ EXIT STATUS ✨

on success, it returns a handle of the created device. 🎉

on failure, it returns NULL as the device and sets a per-thread error code that you can query using rtcGetDeviceError(NULL). 😭 (so like, always check, bestie, no cap.)

---

✨ SEE ALSO ✨

• [rtcRetainDevice]
• [rtcReleaseDevice]
• [rtcNewSYCLDevice]

---

okay that's the whole page, you ate it 💅✨ this was rtcNewDevice(3) from the Embree Ray Tracing Kernels 4 manpage — go forth and build your device, iykyk 🦋💖👑