RenderingBackend: Cleanup doc, tests and logic (#1713)

 - Add logic to print a warning when using offscreen window and interacting
 - Improve testing logic
 - Improve documentation
 - Remove offsreen param from CreateEGL()

.github/actions/coverage-ci/action.yml

@@ -75,12 +75,12 @@ runs:
         -DF3D_PLUGIN_BUILD_USD=ON
         -DF3D_PLUGIN_BUILD_VDB=ON
         -DF3D_STRICT_BUILD=ON
-        -DF3D_TESTING_ENABLE_EXTERNAL_EGL=ON
+        -DF3D_TESTING_ENABLE_EGL_TESTS=ON
         -DF3D_TESTING_ENABLE_EXTERNAL_GLFW=ON
-        -DF3D_TESTING_ENABLE_EXTERNAL_OSMESA=ON
         -DF3D_TESTING_ENABLE_EXTERNAL_QT=ON
-        -DF3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS=ON
         -DF3D_TESTING_ENABLE_GLX_TESTS=ON
+        -DF3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS=ON
+        -DF3D_TESTING_ENABLE_OSMESA_TESTS=ON
 
     - name: Build
       shell: bash

.github/actions/generic-ci/action.yml

@@ -55,7 +55,7 @@ runs:
       with:
         type: 'consumer'
         lfs_sha: ${{inputs.lfs_sha}}
-        cache_postfix: cache-0 
+        cache_postfix: cache-0
 
     - name: Dependencies Dir
       shell: bash
@@ -130,8 +130,7 @@ runs:
       # https://github.com/f3d-app/f3d/issues/1322
       # MacOS x86_64 occasionally segfault with Java
       # https://github.com/f3d-app/f3d/issues/1410
-      # F3D_TESTING_ENABLE_EXTERNAL_(EGL|QT|GLFW) are disabled if no X server is running
-      # EGL is crashing in the CI but not locally
+      # F3D_TESTING_ENABLE_EXTERNAL_(QT|GLFW) are disabled if no X server is running
       # QT/GLFW external tests should be adapted to run offscreen
       # https://github.com/f3d-app/f3d/issues/1670
     - name: Configure
@@ -167,11 +166,11 @@ runs:
         -DF3D_PLUGIN_BUILD_USD=${{ inputs.optional_deps_label == 'optional-deps' && 'ON' || 'OFF' }}
         -DF3D_PLUGIN_BUILD_VDB=${{ matrix.vtk_version != 'v9.2.6' && (runner.os != 'Windows' || matrix.vtk_version != 'v9.3.1') && inputs.optional_deps_label == 'optional-deps' && 'ON' || 'OFF' }}
         -DF3D_STRICT_BUILD=ON
-        -DF3D_TESTING_ENABLE_EXTERNAL_EGL=${{ (runner.os == 'Linux' && inputs.rendering_backend == 'auto') && 'ON' || 'OFF' }}
+        -DF3D_TESTING_ENABLE_EGL_TESTS=${{ runner.os == 'Linux' && 'ON' || 'OFF' }}
         -DF3D_TESTING_ENABLE_EXTERNAL_GLFW=${{ (runner.os == 'Linux' && inputs.rendering_backend == 'auto') && 'ON' || 'OFF' }}
-        -DF3D_TESTING_ENABLE_EXTERNAL_OSMESA=${{ runner.os == 'Linux' && 'ON' || 'OFF' }}
         -DF3D_TESTING_ENABLE_EXTERNAL_QT=${{ (runner.os == 'Linux' && inputs.rendering_backend == 'auto') && 'ON' || 'OFF' }}
-        -DF3D_TESTING_ENABLE_GLX_TESTS=${{ inputs.rendering_backend == 'auto' && 'ON' || 'OFF' }}
+        -DF3D_TESTING_ENABLE_GLX_TESTS=${{ (runner.os == 'Linux' && inputs.rendering_backend == 'auto') && 'ON' || 'OFF' }}
+        -DF3D_TESTING_ENABLE_OSMESA_TESTS=${{ runner.os == 'Linux' && 'ON' || 'OFF' }}
         -DF3D_TESTING_FORCE_RENDERING_BACKEND=${{ inputs.rendering_backend }}
         -DF3D_WINDOWS_GUI=ON
         ${{ runner.os == 'Windows' && '-Ax64 -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL' || null }}
@@ -196,6 +195,14 @@ runs:
       with:
         path: ${{github.workspace}}\build\bin_Release
 
+    # A EGL test is crashing in the CI but not locally
+    - name: Set CI test exception for Linux EGL
+      if:
+        runner.os == 'Linux' &&
+        inputs.rendering_backend != 'auto'
+      shell: bash
+      run: echo "F3D_CTEST_EXCEPTIONS=(TestSDKExternalWindowEGL)" >> $GITHUB_ENV
+
     # Certain tests are failing on macOS with GPU pass through
     # https://github.com/f3d-app/f3d/issues/792
     - name: Set CI test exception for macOS x86_64

.github/actions/sanitizer-ci/action.yml

@@ -77,12 +77,12 @@ runs:
         -DF3D_PLUGIN_BUILD_VDB=OFF
         -DF3D_SANITIZER=${{inputs.sanitizer_type}}
         -DF3D_STRICT_BUILD=ON
-        -DF3D_TESTING_ENABLE_EXTERNAL_EGL=ON
+        -DF3D_TESTING_ENABLE_EGL_TESTS=ON
         -DF3D_TESTING_ENABLE_EXTERNAL_GLFW=ON
-        -DF3D_TESTING_ENABLE_EXTERNAL_OSMESA=ON
         -DF3D_TESTING_ENABLE_EXTERNAL_QT=ON
         -DF3D_TESTING_ENABLE_GLX_TESTS=ON
         -DF3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS=ON
+        -DF3D_TESTING_ENABLE_OSMESA_TESTS=ON
 
     - name: Build
       shell: bash

.github/actions/vtk_commit_sha

@@ -1 +1 @@
-aab695b6405fef4a7472039766ced36bd162221f
+cd73b5dd854a6ff826e729a6cb890101717498e7

CMakeLists.txt

@@ -187,7 +187,10 @@ list(APPEND f3d_link_options_public ${f3d_sanitizer_link_options})
 option(BUILD_TESTING "Build the tests" OFF)
 cmake_dependent_option(F3D_TESTING_ENABLE_RENDERING_TESTS "Enable rendering tests" ON "BUILD_TESTING" OFF)
 cmake_dependent_option(F3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS "Enable long timeout tests" OFF "BUILD_TESTING" OFF)
-cmake_dependent_option(F3D_TESTING_ENABLE_GLX_TESTS "Enable test that require a X server running on Linux" ON "F3D_TESTING_ENABLE_RENDERING_TESTS AND UNIX AND NOT APPLE" OFF)
+cmake_dependent_option(F3D_TESTING_ENABLE_GLX_TESTS "Enable tests that require a X server running on Linux" ON "F3D_TESTING_ENABLE_RENDERING_TESTS AND UNIX AND NOT APPLE" OFF)
+cmake_dependent_option(F3D_TESTING_ENABLE_EGL_TESTS "Enable tests that require EGL to run" ON "F3D_TESTING_ENABLE_RENDERING_TESTS AND UNIX AND NOT APPLE" OFF)
+cmake_dependent_option(F3D_TESTING_ENABLE_OSMESA_TESTS "Enable tests that require OSMESA to run" ON "F3D_TESTING_ENABLE_RENDERING_TESTS AND UNIX AND NOT APPLE" OFF)
+
 if(BUILD_TESTING)
   enable_testing()
 endif()

application/F3DStarter.cxx

@@ -770,7 +770,7 @@ int F3DStarter::Start(int argc, char** argv)
 
     if (this->Internals->AppOptions.RenderingBackend == "egl")
     {
-      this->Internals->Engine = std::make_unique<f3d::engine>(f3d::engine::createEGL(offscreen));
+      this->Internals->Engine = std::make_unique<f3d::engine>(f3d::engine::createEGL());
     }
     else if (this->Internals->AppOptions.RenderingBackend == "osmesa")
     {
@@ -1055,10 +1055,19 @@ int F3DStarter::Start(int argc, char** argv)
       f3d::log::error("This is a headless build of F3D, interactive rendering is not supported");
       return EXIT_FAILURE;
 #else
-      // Create the event loop repeating timer
-      interactor.createTimerCallBack(30, [this]() { this->EventLoop(); });
-      this->RequestRender();
-      interactor.start();
+      if (this->Internals->Engine->getWindow().isOffscreen())
+      {
+        f3d::log::warn(
+          "You are using an offscreen configuration, interactive rendering is disabled");
+        return EXIT_SUCCESS;
+      }
+      else
+      {
+        // Create the event loop repeating timer
+        interactor.createTimerCallBack(30, [this]() { this->EventLoop(); });
+        this->RequestRender();
+        interactor.start();
+      }
 #endif
     }
   }

application/testing/CMakeLists.txt

@@ -1015,15 +1015,24 @@ endif()
 # For some reason the sanitizer detects leaks because of EGL and OSMesa
 f3d_test(NAME TestRenderingBackendAuto DATA cow.vtp RENDERING_BACKEND auto)
 if(UNIX AND NOT APPLE AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.20240914 AND F3D_SANITIZER STREQUAL "none")
-  f3d_test(NAME TestRenderingBackendEGL DATA cow.vtp RENDERING_BACKEND egl)
-  f3d_test(NAME TestRenderingBackendEGLCheckClass DATA cow.vtp RENDERING_BACKEND egl ARGS --verbose REGEXP "vtkEGLRenderWindow" NO_BASELINE)
-  f3d_test(NAME TestRenderingBackendOSMesa DATA cow.vtp RENDERING_BACKEND osmesa)
-  f3d_test(NAME TestRenderingBackendOSMesaCheckClass DATA cow.vtp RENDERING_BACKEND osmesa ARGS --verbose REGEXP "vtkOSOpenGLRenderWindow" NO_BASELINE)
-  f3d_test(NAME TestRenderingBackendWGLFailure DATA cow.vtp RENDERING_BACKEND wgl REGEXP "Cannot use a WGL context on this platform" NO_BASELINE)
+  if(F3D_TESTING_ENABLE_EGL_TESTS)
+    f3d_test(NAME TestRenderingBackendEGL DATA cow.vtp RENDERING_BACKEND egl)
+    f3d_test(NAME TestRenderingBackendEGLCheckClass DATA cow.vtp RENDERING_BACKEND egl ARGS --verbose REGEXP "vtkEGLRenderWindow" NO_BASELINE)
+    f3d_test(NAME TestRenderingBackendEGLNoInteractiveVerbose RENDERING_BACKEND egl REGEXP "You are using an offscreen configuration, interactive rendering is disabled" NO_BASELINE NO_OUTPUT)
+  endif()
+
+  if(F3D_TESTING_ENABLE_OSMESA_TESTS)
+    f3d_test(NAME TestRenderingBackendOSMesa DATA cow.vtp RENDERING_BACKEND osmesa)
+    f3d_test(NAME TestRenderingBackendOSMesaCheckClass DATA cow.vtp RENDERING_BACKEND osmesa ARGS --verbose REGEXP "vtkOSOpenGLRenderWindow" NO_BASELINE)
+    f3d_test(NAME TestRenderingBackendOSMesaNoInteractiveVerbose RENDERING_BACKEND osmesa REGEXP "You are using an offscreen configuration, interactive rendering is disabled" NO_BASELINE NO_OUTPUT)
+  endif()
+
   if(F3D_TESTING_ENABLE_GLX_TESTS)
     f3d_test(NAME TestRenderingBackendGLX DATA cow.vtp RENDERING_BACKEND glx)
     f3d_test(NAME TestRenderingBackendGLXCheckClass DATA cow.vtp RENDERING_BACKEND glx ARGS --verbose REGEXP "vtkXOpenGLRenderWindow" NO_BASELINE)
   endif()
+
+  f3d_test(NAME TestRenderingBackendWGLFailure DATA cow.vtp RENDERING_BACKEND wgl REGEXP "Cannot use a WGL context on this platform" NO_BASELINE)
 endif()
 if(WIN32)
   f3d_test(NAME TestRenderingBackendWGL DATA cow.vtp RENDERING_BACKEND wgl)

doc/dev/TESTING.md

@@ -10,10 +10,10 @@ There are a few CMake options to configure the F3D testing framework:
 * `F3D_TESTING_ENABLE_LONG_TIMEOUT_TESTS`: Certain tests can take some time to run, off by default, requires rendering tests.
 * `F3D_TESTING_FORCE_RENDERING_BACKEND`: Configure the rendering backend to use. Can be `auto` (default), `glx`, `wgl`, `egl` or `osmesa`.
 * `F3D_TESTING_ENABLE_GLX_TESTS`: Enable tests requiring a X11 server running on Linux.
-* `F3D_TESTING_ENABLE_EXTERNAL_GLFW`: Enable test requiring GLFW dependency.
-* `F3D_TESTING_ENABLE_EXTERNAL_QT`: Enable test requiring QT dependency.
-* `F3D_TESTING_ENABLE_EXTERNAL_OSMESA`: Enable test requiring OSMesa dependency.
-* `F3D_TESTING_ENABLE_EXTERNAL_EGL`: Enable test requiring EGL dependency.
+* `F3D_TESTING_ENABLE_OSMESA_TESTS`: Enable tests requiring OSMesa dependency.
+* `F3D_TESTING_ENABLE_EGL_TESTS`: Enable tests requiring EGL dependency.
+* `F3D_TESTING_ENABLE_EXTERNAL_GLFW`: Enable libf3d tests requiring GLFW dependency.
+* `F3D_TESTING_ENABLE_EXTERNAL_QT`: Enable libf3d tests requiring QT dependency.
 
 ## Running the tests
 

doc/user/DESKTOP_INTEGRATION.md

@@ -21,18 +21,26 @@ sudo update-mime-database ~/.local/share/mime/
 sudo update-desktop-database ~/.local/share/applications
 ```
 
-F3D supports rendering in environments with limited graphical contexts, including sandboxes or without Xorg running. In most cases, the default behavior will automatically detect which capabilities are available and use the right rendering backend, it is possible to specify it using `--rendering-backend` CLI option.
+F3D supports rendering in environments with limited graphical contexts, including sandboxes or without Xorg running.
+In most cases, the default behavior will automatically detect which capabilities are available and use the right rendering backend,
+it is possible to specify it using the `--rendering-backend` CLI option.
 
-If `libEGL.so` is available, you can use: `--rendering-backend=egl`.
-If `libOSMesa.so` is available, you can use: `--rendering-backend=osmesa`.
+ - If `libEGL.so` is available, you can use: `--rendering-backend=egl`.
+ - If `libOSMesa.so` is available, you can use: `--rendering-backend=osmesa`.
+ - When using `--rendering-backend=auto`, F3D will try to load the following libraries in order and use the first one it was able to load and use:
+   - `libGLX.so`
+   - `libEGL.so`
+   - `libOSMesa.so`
 
-You can use that feature for thumbnail generation whenever needed (e.g., Nautilus), by modifying the [thumbnail config file](CONFIGURATION_FILE.md), eg:`~/.config/f3d/thumbnail.json `:
+You can use that feature for thumbnail generation whenever needed (e.g., Nautilus or other sandboxing file browser),
+by modifying the [thumbnail config file](CONFIGURATION_FILE.md), eg:`~/.config/f3d/thumbnail.json`:
 
 ```javascript
-    ".*":
-    {
-      "rendering-backend": "egl"
-    },
+{
+    ".*": {
+        "rendering-backend": "egl"
+    }
+}
 ```
 
 If you use the portable archive, make sure to extract it somewhere the sandboxing system has access to, eg: Nautilus uses `bwrap` and gives it access to `/usr` but not to `/opt`.

doc/user/LIMITATIONS_AND_TROUBLESHOOTING.md

@@ -72,7 +72,7 @@ The GCC flag `-latomic` is not being added automatically with specific architect
   * If no formats have working thumbnails, then it is can be an issue with sandboxing or with the `f3d-plugin-xxx.thumbnailer` files.
   * If only big file do not have thumbnails, this is intended, you can modify this behavior in the `thumbnail.d/10_global.json` configuration folder using the `max-size` option.
 
-  > `--rendering-backend` CLI option is not working as expected
+> `--rendering-backend` CLI option is not working as expected
 
 Dynamically switching rendering backend require VTK 9.4.0, you may need to update VTK or to use our [binary release](INSTALLATION.md).
 

doc/user/OPTIONS.md

@@ -22,6 +22,7 @@ Options|Default|Description
 \-\-load-plugins=\<paths or names\>||List of plugins to load separated with a comma. Official plugins are `alembic`, `assimp`, `draco`, `exodus`, `occt`, `usd`, `vdb`. See [plugins](PLUGINS.md) for more info.
 \-\-scan-plugins||Scan standard directories for plugins and display their names, results may be incomplete. See [plugins](PLUGINS.md) for more info.
 \-\-screenshot-filename=\<png file\>|`{app}/{model}_{n}.png`|Filename to save [screenshots](INTERACTIONS.md#taking-screenshots) to. Can use [template variables](#filename-templating).
+\-\-rendering-backend=\<auto|egl|osmesa|glx|wgl\>|auto|Rendering backend to load, `auto` means to let F3D pick the correct one for you depending on your system capabilities. Use `egl` or `osmesa` on linux to force headless rendering.
 
 ## General Options
 

library/public/engine.h

@@ -71,17 +71,16 @@ class F3D_EXPORT engine
   static engine createWGL(bool offscreen = false);
 
   /**
-   * Create an engine with an EGL window.
+   * Create an engine with an offscreen EGL window.
    * VTK >= 9.4 required.
    * If several GPU are available, the environment variable
    * `VTK_DEFAULT_EGL_DEVICE_INDEX` allows its selection.
-   * Optionally, the window can be hidden by setting offscreen to true.
    * Throws engine::loading_exception in case of failure.
    */
-  static engine createEGL(bool offscreen = false);
+  static engine createEGL();
 
   /**
-   * Create an engine with an OSMesa window.
+   * Create an engine with an offscreen OSMesa window.
    * VTK >= 9.4 required.
    * Throws engine::loading_exception in case of window creation failure.
    */

library/src/engine.cxx

@@ -98,9 +98,9 @@ engine engine::createWGL(bool offscreen)
 }
 
 //----------------------------------------------------------------------------
-engine engine::createEGL(bool offscreen)
+engine engine::createEGL()
 {
-  return { window::Type::EGL, offscreen, context::egl() };
+  return { window::Type::EGL, true, context::egl() };
 }
 
 //----------------------------------------------------------------------------

library/testing/CMakeLists.txt

@@ -51,8 +51,6 @@ configure_file("${F3D_SOURCE_DIR}/testing/recordings/TestSDKInteractorDropFullSc
 # External window tests
 option(F3D_TESTING_ENABLE_EXTERNAL_GLFW "Test external GLFW" OFF)
 option(F3D_TESTING_ENABLE_EXTERNAL_QT "Test external QT" OFF)
-option(F3D_TESTING_ENABLE_EXTERNAL_OSMESA "Test external OSMesa" OFF)
-option(F3D_TESTING_ENABLE_EXTERNAL_EGL "Test external GLX" OFF)
 
 set(libf3dSDKTests_link_libs "")
 
@@ -66,7 +64,7 @@ if(F3D_TESTING_ENABLE_EXTERNAL_QT)
   list(APPEND libf3dSDKTests_list TestSDKExternalWindowQT.cxx)
   list(APPEND libf3dSDKTests_link_libs Qt5::OpenGL)
 endif()
-if(F3D_TESTING_ENABLE_EXTERNAL_OSMESA AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.20240914)
+if(F3D_TESTING_ENABLE_OSMESA_TESTS AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.20240914)
   find_library(OSMesa_LIB OSMesa REQUIRED)
   list(APPEND libf3dSDKTests_list TestSDKExternalWindowOSMesa.cxx)
   list(APPEND libf3dSDKTests_link_libs "${OSMesa_LIB}")
@@ -77,7 +75,7 @@ if(F3D_TESTING_ENABLE_GLX_TESTS AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.202409
   list(APPEND libf3dSDKTests_list TestSDKExternalWindowGLX.cxx)
   list(APPEND libf3dSDKTests_link_libs OpenGL::GLX "${X11_LIB}")
 endif()
-if(F3D_TESTING_ENABLE_EXTERNAL_EGL AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.20240914)
+if(F3D_TESTING_ENABLE_EGL_TESTS AND VTK_VERSION VERSION_GREATER_EQUAL 9.3.20240914)
   find_package(OpenGL COMPONENTS EGL REQUIRED)
   list(APPEND libf3dSDKTests_list TestSDKExternalWindowEGL.cxx)
   list(APPEND libf3dSDKTests_link_libs OpenGL::EGL)