Deploying to gh-pages from @ 71ba9dd 🚀

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/libf3d/doxygen/_sources/api/program_listing_file_public_engine.h.rst

@@ -38,7 +38,7 @@ Program Listing for File engine.h
    
      static engine createWGL(bool offscreen = false);
    
-     static engine createEGL(bool offscreen = false);
+     static engine createEGL();
    
      static engine createOSMesa();
    

doc/libf3d/doxygen/api/classf3d_1_1engine.html

@@ -462,15 +462,15 @@ <h2>Class Documentation<a class="headerlink" href="#class-documentation" title="
 </dd></dl>
 
 <dl class="cpp function">
-<dt class="sig sig-object cpp" id="_CPPv4N3f3d6engine9createEGLEb">
-<span id="_CPPv3N3f3d6engine9createEGLEb"></span><span id="_CPPv2N3f3d6engine9createEGLEb"></span><span id="f3d::engine::createEGL__b"></span><span class="target" id="classf3d_1_1engine_1aa1c0b3bed6fc34546d4bb7aab67abcc8"></span><span class="k"><span class="pre">static</span></span><span class="w"> </span><a class="reference internal" href="#_CPPv4N3f3d6engineE" title="f3d::engine"><span class="n"><span class="pre">engine</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">createEGL</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">offscreen</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="k"><span class="pre">false</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N3f3d6engine9createEGLEb" title="Permalink to this definition">#</a><br /></dt>
-<dd><p>Create an engine with an EGL window. VTK &gt;= 9.4 required. If several GPU are available, the environment variable <code class="docutils literal notranslate"><span class="pre">VTK_DEFAULT_EGL_DEVICE_INDEX</span></code> allows its selection. Optionally, the window can be hidden by setting offscreen to true. Throws engine::loading_exception in case of failure. </p>
+<dt class="sig sig-object cpp" id="_CPPv4N3f3d6engine9createEGLEv">
+<span id="_CPPv3N3f3d6engine9createEGLEv"></span><span id="_CPPv2N3f3d6engine9createEGLEv"></span><span id="f3d::engine::createEGL"></span><span class="target" id="classf3d_1_1engine_1af2ad280d2be4c58a8f30eec351cd3bf4"></span><span class="k"><span class="pre">static</span></span><span class="w"> </span><a class="reference internal" href="#_CPPv4N3f3d6engineE" title="f3d::engine"><span class="n"><span class="pre">engine</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">createEGL</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N3f3d6engine9createEGLEv" title="Permalink to this definition">#</a><br /></dt>
+<dd><p>Create an engine with an offscreen EGL window. VTK &gt;= 9.4 required. If several GPU are available, the environment variable <code class="docutils literal notranslate"><span class="pre">VTK_DEFAULT_EGL_DEVICE_INDEX</span></code> allows its selection. Throws engine::loading_exception in case of failure. </p>
 </dd></dl>
 
 <dl class="cpp function">
 <dt class="sig sig-object cpp" id="_CPPv4N3f3d6engine12createOSMesaEv">
 <span id="_CPPv3N3f3d6engine12createOSMesaEv"></span><span id="_CPPv2N3f3d6engine12createOSMesaEv"></span><span id="f3d::engine::createOSMesa"></span><span class="target" id="classf3d_1_1engine_1a1ea3b63b10d5f826528545a562297cd1"></span><span class="k"><span class="pre">static</span></span><span class="w"> </span><a class="reference internal" href="#_CPPv4N3f3d6engineE" title="f3d::engine"><span class="n"><span class="pre">engine</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">createOSMesa</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N3f3d6engine12createOSMesaEv" title="Permalink to this definition">#</a><br /></dt>
-<dd><p>Create an engine with an OSMesa window. VTK &gt;= 9.4 required. Throws engine::loading_exception in case of window creation failure. </p>
+<dd><p>Create an engine with an offscreen OSMesa window. VTK &gt;= 9.4 required. Throws engine::loading_exception in case of window creation failure. </p>
 </dd></dl>
 
 <dl class="cpp function">

doc/libf3d/doxygen/api/program_listing_file_public_engine.h.html

@@ -340,7 +340,7 @@ <h1>Program Listing for File engine.h</h1>
 
 <span class="w">  </span><span class="k">static</span><span class="w"> </span><span class="n">engine</span><span class="w"> </span><span class="nf">createWGL</span><span class="p">(</span><span class="kt">bool</span><span class="w"> </span><span class="n">offscreen</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">);</span>
 
-<span class="w">  </span><span class="k">static</span><span class="w"> </span><span class="n">engine</span><span class="w"> </span><span class="nf">createEGL</span><span class="p">(</span><span class="kt">bool</span><span class="w"> </span><span class="n">offscreen</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">);</span>
+<span class="w">  </span><span class="k">static</span><span class="w"> </span><span class="n">engine</span><span class="w"> </span><span class="nf">createEGL</span><span class="p">();</span>
 
 <span class="w">  </span><span class="k">static</span><span class="w"> </span><span class="n">engine</span><span class="w"> </span><span class="nf">createOSMesa</span><span class="p">();</span>
 

doc/libf3d/doxygen/genindex.html

@@ -358,7 +358,7 @@ <h2 id="F">F</h2>
 </li>
       <li><a href="api/classf3d_1_1engine.html#_CPPv4N3f3d6engine6createEb">f3d::engine::create (C++ function)</a>
 </li>
-      <li><a href="api/classf3d_1_1engine.html#_CPPv4N3f3d6engine9createEGLEb">f3d::engine::createEGL (C++ function)</a>
+      <li><a href="api/classf3d_1_1engine.html#_CPPv4N3f3d6engine9createEGLEv">f3d::engine::createEGL (C++ function)</a>
 </li>
       <li><a href="api/classf3d_1_1engine.html#_CPPv4N3f3d6engine14createExternalERKN7context8functionE">f3d::engine::createExternal (C++ function)</a>
 </li>

doc/user/DESKTOP_INTEGRATION.html

@@ -2,10 +2,11 @@
 <span class="nb">tar</span> <span class="nt">-xzvf</span> f3d-1.3.0-Linux.tar.gz <span class="nt">-C</span> ~/.local/
 <span class="nb">sudo </span>update-mime-database ~/.local/share/mime/
 <span class="nb">sudo </span>update-desktop-database ~/.local/share/applications
-</code></pre></div></div> <p>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 <code class="language-plaintext highlighter-rouge">--rendering-backend</code> CLI option.</p> <p>If <code class="language-plaintext highlighter-rouge">libEGL.so</code> is available, you can use: <code class="language-plaintext highlighter-rouge">--rendering-backend=egl</code>. If <code class="language-plaintext highlighter-rouge">libOSMesa.so</code> is available, you can use: <code class="language-plaintext highlighter-rouge">--rendering-backend=osmesa</code>.</p> <p>You can use that feature for thumbnail generation whenever needed (e.g., Nautilus), by modifying the <a href="/doc/user/CONFIGURATION_FILE.html">thumbnail config file</a>, eg:<code class="language-plaintext highlighter-rouge">~/.config/f3d/thumbnail.json </code>:</p> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    <span class="dl">"</span><span class="s2">.*</span><span class="dl">"</span><span class="p">:</span>
-    <span class="p">{</span>
-      <span class="dl">"</span><span class="s2">rendering-backend</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">egl</span><span class="dl">"</span>
-    <span class="p">},</span>
+</code></pre></div></div> <p>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 <code class="language-plaintext highlighter-rouge">--rendering-backend</code> CLI option.</p> <ul> <li>If <code class="language-plaintext highlighter-rouge">libEGL.so</code> is available, you can use: <code class="language-plaintext highlighter-rouge">--rendering-backend=egl</code>.</li> <li>If <code class="language-plaintext highlighter-rouge">libOSMesa.so</code> is available, you can use: <code class="language-plaintext highlighter-rouge">--rendering-backend=osmesa</code>.</li> <li>When using <code class="language-plaintext highlighter-rouge">--rendering-backend=auto</code>, F3D will try to load the following libraries in order and use the first one it was able to load and use: <ul> <li><code class="language-plaintext highlighter-rouge">libGLX.so</code></li> <li><code class="language-plaintext highlighter-rouge">libEGL.so</code></li> <li><code class="language-plaintext highlighter-rouge">libOSMesa.so</code></li> </ul> </li> </ul> <p>You can use that feature for thumbnail generation whenever needed (e.g., Nautilus or other sandboxing file browser), by modifying the <a href="/doc/user/CONFIGURATION_FILE.html">thumbnail config file</a>, eg:<code class="language-plaintext highlighter-rouge">~/.config/f3d/thumbnail.json</code>:</p> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span>
+    <span class="dl">"</span><span class="s2">.*</span><span class="dl">"</span><span class="p">:</span> <span class="p">{</span>
+        <span class="dl">"</span><span class="s2">rendering-backend</span><span class="dl">"</span><span class="p">:</span> <span class="dl">"</span><span class="s2">egl</span><span class="dl">"</span>
+    <span class="p">}</span>
+<span class="p">}</span>
 </code></pre></div></div> <p>If you use the portable archive, make sure to extract it somewhere the sandboxing system has access to, eg: Nautilus uses <code class="language-plaintext highlighter-rouge">bwrap</code> and gives it access to <code class="language-plaintext highlighter-rouge">/usr</code> but not to <code class="language-plaintext highlighter-rouge">/opt</code>.</p> <h2 id="windows"> <a href="#windows" class="anchor-heading" aria-labelledby="windows"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Windows </h2> <p>For Windows desktop integration, F3D rely on a registered shell extension.</p> <p>Using the F3D NSIS installer (.exe) is the simplest way to enable thumbnails and integrate F3D on windows.</p> <p>It is also possible to do it manually when using the zipped binary release archive, on installation, just run:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd C:\path\to\f3d\bin\
 regsvr32 F3DShellExtension.dll
 </code></pre></div></div> <p>To remove the shell extension, run:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cd C:\path\to\f3d\bin\

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