rtcGetDeviceError(3)

💖 rtcGetDeviceError — from the Embree Ray Tracing Kernels 4 manual, page rtcGetDeviceError(3) ✨

okay bestie, sit down, we're doing error codes and honestly this one is a little sleeper hit 💅

🌸 NAME 🌸

rtcGetDeviceError — it hands you back the error code of the device, that's it, that's the job 🎀

---

✨ SYNOPSIS ✨

#include <embree4/rtcutil.h>

wait no, let me not do that, here's the real one, verbatim, do not come for me:

#include <embree4/rtcore.h>

RTCError rtcGetDeviceError(RTCDevice device);

---

🦋 DESCRIPTION 🦋

okay so every single thread has its own error code, per device. yes, per thread AND per device. it's giving very personalized, very bespoke 🫶

when you call an API function and something goes wrong, that error code gets set to the error that happened — but only if it's not already storing a previous error. so it's like, first one in gets to stay, everyone after that is just standing outside the club 💀

rtcGetDeviceError reads the currently stored error, returns it, and then clears the error code. which means — and this is the whole point, the main character mechanic — the error you get back is always the first error that happened since the last time you called rtcGetDeviceError. no cap. that's the guarantee. 🔥

---

🌈 the possible error codes it can return 🌈

• RTC_ERROR_NONE — literally nothing went wrong. iconic. we love a clean slate 💖
• RTC_ERROR_UNKNOWN — an unknown error happened. mysterious. unbothered. not telling us anything 🙈
• RTC_ERROR_INVALID_ARGUMENT — you passed an invalid argument, bestie. check yourself 💅
• RTC_ERROR_INVALID_OPERATION — that operation is not allowed for the object you specified. not every object can do every thing, it's called boundaries ✋
• RTC_ERROR_OUT_OF_MEMORY — there's not enough memory left to finish the operation. she's full. no more room 😭
• RTC_ERROR_UNSUPPORTED_CPU — the CPU is not supported, because it doesn't support the lowest ISA Embree is compiled for. yeah. the bar was on the floor and the CPU tripped over it 💀
• RTC_ERROR_CANCELLED — the operation got canceled, either by a memory monitor callback or a progress monitor callback function. not us, it was the callback 👀
• RTC_ERROR_LEVEL_ZERO_RAYTRACING_SUPPORT_MISSING — okay so this one can pop up when you're creating an Embree device with SYCL support using rtcNewSYCLDevice and it fails. this error probably means your GPU driver is too old or not installed properly. the fix: install a new GPU driver, and on Linux make sure the package intel-level-zero-gpu-raytracing is installed. for general driver installation info on Linux, go look at https://dgpu-docs.intel.com — that's the link, go there, fr fr 🔗

---

🧚 the whole NULL device situation (important, pay attention) 🧚

when the device construction fails, rtcNewDevice returns NULL as the device. and to detect the error code of a failed device construction like that, you pass NULL as the device to rtcGetDeviceError. that's the one and only exception, the special little loophole 👑

for all other invocations of rtcGetDeviceError, you must specify a proper device pointer. no NULLs anywhere else, periodt.

⚠️ if you pass a real device pointer where a NULL is expected, or NULL where a real one is expected, you're doing it wrong. the NULL pass is strictly for the failed-construction case, bestie.

---

💜 more details, more context 💜

the API function rtcGetDeviceLastErrorMessage can be used to get more details about the last RTCError a RTCDevice encountered. so when you want the tea, not just the headline, that's your girl ☕

and for convenient reporting of an RTCError, the API function rtcGetErrorString can be used — it returns a string representation of a given RTCError. so you can actually print it and show your friends instead of staring at an enum number 🎀

---

👑 EXIT STATUS 👑

returns the error code for the device. simple. elegant. done. 💅

---

⭐ SEE ALSO ⭐

• rtcSetDeviceErrorFunction
• rtcGetDeviceLastErrorMessage
• rtcGetErrorString

---

and that's the whole page, bestie, you're so welcome 💖

this was rtcGetDeviceError(3) from the Embree Ray Tracing Kernels 4 manual, and yes the footer really does just say rtcGetDeviceError(3) again because manpages love a lil echo 🌸 go forth and check your error codes, mwah 🫶✨