fix(egl): fail fast when rendering is requested without egl

Author: juelg

python/rcs/camera/sim.py

@@ -11,6 +11,7 @@
 from rcs._core.sim import SimCameraConfig
 from rcs._core.sim import SimCameraSet as _SimCameraSet
 from rcs.camera.interface import BaseCameraSet, CameraFrame, DataFrame, Frame, FrameSet
+from rcs.sim import egl_bootstrap
 
 from rcs import sim
 
@@ -31,6 +32,7 @@ def __init__(
         self.cameras = cameras
         self.physical_units = physical_units
 
+        egl_bootstrap.require("simulation camera rendering")
         super().__init__(simulation, cameras, render_on_demand=render_on_demand)
         self._sim: sim.Sim
 

python/rcs/sim/egl_bootstrap.py

@@ -10,12 +10,15 @@
 import os
 
 _egl_available = False
+_egl_error = None
 _addr_make_current = None
 _egl_display = None
 _egl_context = None
 
 name = ctypes.util.find_library("EGL")
-if name is not None:
+if name is None:
+    _egl_error = "Could not find libEGL via ctypes.util.find_library('EGL')."
+else:
     try:
         import mujoco.egl
         from mujoco.egl import GLContext
@@ -26,8 +29,28 @@
         _egl_display = int(mujoco.egl.EGL_DISPLAY.address)
         _egl_context = int(_ctx._context.address)
         _egl_available = True
-    except Exception:
-        pass
+    except Exception as exc:
+        _egl_error = f"Failed to initialize MuJoCo EGL context: {exc!r}"
+
+
+def is_available() -> bool:
+    return _egl_available
+
+
+def failure_reason() -> str | None:
+    return _egl_error
+
+
+def require(feature: str = "offscreen rendering"):
+    if _egl_available:
+        return
+    reason = _egl_error or "unknown EGL initialization failure"
+    message = (
+        f"EGL is required for {feature}, but it is not available. {reason} "
+        "If you do not need rendering, run RCS without simulation cameras/viewers. "
+        "If you do need headless rendering, install the system EGL/OpenGL runtime libraries."
+    )
+    raise RuntimeError(message)
 
 
 def bootstrap():

src/rcs/utils.cpp

@@ -18,6 +18,14 @@ void bootstrap_egl(uintptr_t fn_addr, uintptr_t dpy, uintptr_t ctx) {
 }
 
 void ensure_current() {
+  if (g_makeCurrent == nullptr || g_display == EGL_NO_DISPLAY ||
+      g_context == EGL_NO_CONTEXT) {
+    throw std::runtime_error(
+        "EGL rendering was requested, but EGL was not bootstrapped. "
+        "This usually means libEGL or the MuJoCo EGL context is unavailable. "
+        "Run without cameras/viewers if you do not need rendering, or install "
+        "the required system EGL/OpenGL runtime libraries.");
+  }
   if (!g_makeCurrent(g_display, g_surface, g_surface, g_context))
     throw std::runtime_error("eglMakeCurrent failed");
 }