Deploying to gh-pages from @ d9fa161 🚀

doc/dev/TESTING.md

@@ -8,6 +8,12 @@ There are a few CMake options to configure the F3D testing framework:
 * `BUILD_TESTING`: Enable the test framework, off by default. Requires [git LFS](https://git-lfs.com/) if repository is cloned.
 * `F3D_TESTING_ENABLE_RENDERING_TESTS`: An option to enable/disable test that require rendering capabilities, on by default.
 * `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.
 
 ## Running the tests
 

doc/libf3d/CLASSES.md

@@ -7,7 +7,16 @@ For the complete documentation, please consult the [libf3d doxygen documentation
 
 The engine class is the main class that needs to be instantiated. All other classes instance are provided by the engine using getters, `getScene`, `getWindow`, `getInteractor`, `getOptions`.
 
-The engine constructor lets you choose the type of window in its constructor, `NONE`, `NATIVE`, `NATIVE_OFFSCREEN`, `EXTERNAL`. Default is `NATIVE`. See [Window class](#window-class) documentation for more info. Please note that the engine will not provide a interactor with `NONE` and `EXTERNAL`.
+The engine factory lets you choose between the different types of OpenGL rendering backend.
+The generic `create()` is recommended in most cases and will use the best context possible available on your system.
+However, it's possible to force the rendering backend in some specific use cases:
+* `createGLX()`: force usage of GLX backend, works on Linux only and requires a X11 server to run.
+* `createWGL()`: force usage of WGL native backend on Windows.
+* `createEGL()`: force usage of EGL backend, recommended when doing offscreen rendering with a GPU available. Requires EGL library available. No interactor provided.
+* `createOSMesa()`: force usage of OSMesa backend (software rendering), recommended when doing offscreen rendering without any GPU. Requires OSMesa library available. No interactor provided.
+* `createNone()`: do not use any rendering. Useful to retrieve metadata only.
+* `createExternal()`: the user is responsible of the rendering stack. It lets the user integrate libf3d in other frameworks like Qt or GLFW. No interactor provided. See [Context](#context-class) documentation for more info.
+An additional boolean argument is available to specify if offscreen rendering is requested when relevant on the selected rendering backend.
 
 A static function `loadPlugin` can also be called to load reader plugins. It must be called before loading any file. An internal plugin containing VTK native readers can be loaded by calling `f3d::engine::loadPlugin("native");`. Other plugins maintained by F3D team are available if their build is enabled: `alembic`, `assimp`, `draco`, `exodus`, `occt` and `usd`.
 If CMake option `F3D_PLUGINS_STATIC_BUILD` is enabled, the plugins listed above are also static just like `native` plugin.
@@ -18,18 +27,13 @@ All static plugins can be loaded using `f3d::engine::autoloadPlugins()`.
 The scene class is responsible to `add` file from the disk into the scene. It supports reading multiple files at the same time and even mesh from memory.
 It is possible to `clear` the scene and to check if the scene `supports` a file.
 
-## Window class
-
-The window class is responsible for rendering the meshes. It supports multiple modes.
-
-* `NONE`: A window that will not render anything, very practical when only trying to recover meta-information about the data.
+## Context class
 
-* `NATIVE`: Default mode where a window is shown onscreen using native graphical capabilities.
+Convenience class providing generic context API when using a external rendering backend (using `f3d::engine::createExternal()` factory).
 
-* `NATIVE_OFFSCREEN`: Use native graphical capabilities for rendering, but unto an offscreen window, which will not appear on screen, practical when generating screenshots.
-
-* `EXTERNAL`: A window where the OpenGL context is not created but assumed to have been created externally. To be used with other frameworks like Qt or GLFW.
+## Window class
 
+The window class is responsible for rendering the data.
 Window lets you `render`, `renderToImage` and control other parameters of the window, like icon or windowName.
 
 ## Interactor class

doc/libf3d/OPTIONS.md

@@ -119,7 +119,7 @@ There are three APIs to access the options
 The most straightforward and easy to use API, just access it through the structs available in the options instance, eg:
 
 ```cpp
-  f3d::engine eng(f3d::window::Type::NATIVE);
+  f3d::engine eng = f3d::engine::create();
   f3d::options& opt = eng.getOptions();
   opt.render.show_edges = true;
   opt.render.grid.enable = true;
@@ -130,7 +130,7 @@ The most straightforward and easy to use API, just access it through the structs
 Please note that when accessing optional options, special care must be used, eg:
 
 ```cpp
-  f3d::engine eng(f3d::window::Type::NATIVE);
+  f3d::engine eng = f3d::engine::create();
   f3d::options& opt = eng.getOptions();
   if (opt.render.line_width.has_value())
   {
@@ -147,7 +147,7 @@ The most generic and flexible API, as it rely on parsing and string generation.
 The documentation about option parsing is upcoming.
 
 ```cpp
-  f3d::engine eng(f3d::window::Type::NATIVE);
+  f3d::engine eng = f3d::engine::create();
   f3d::options& opt = eng.getOptions();
   opt.setAsString("render.show_edges", "true");
   opt.setAsString("render.grid.enable", "true");
@@ -158,7 +158,7 @@ The documentation about option parsing is upcoming.
 When using this API make sure to catch exceptions has needed, eg:
 
 ```cpp
-  f3d::engine eng(f3d::window::Type::NATIVE);
+  f3d::engine eng = f3d::engine::create();
   f3d::options& opt = eng.getOptions();
 
   try
@@ -180,7 +180,7 @@ When using this API make sure to catch exceptions has needed, eg:
 An API that is similar to the F3D 2.0 options API thanks to std::variant.
 
 ```cpp
-  f3d::engine eng(f3d::window::Type::NATIVE);
+  f3d::engine eng = f3d::engine::create();
   f3d::options& opt = eng.getOptions();
   opt.set("render.show_edges", true);
   opt.set("render.grid.enable", true);

doc/libf3d/OVERVIEW.html

@@ -52,8 +52,8 @@
 <span class="c1">// Load VTK native readers</span>
 <span class="n">f3d</span><span class="o">::</span><span class="n">engine</span><span class="o">::</span><span class="n">autoloadPlugins</span><span class="p">();</span>
 
-<span class="c1">// Create a f3d::engine</span>
-<span class="n">f3d</span><span class="o">::</span><span class="n">engine</span> <span class="nf">eng</span><span class="p">(</span><span class="n">f3d</span><span class="o">::</span><span class="n">window</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">NATIVE_OFFSCREEN</span><span class="p">);</span>
+<span class="c1">// Create a f3d::engine with a offscreen window</span>
+<span class="n">f3d</span><span class="o">::</span><span class="n">engine</span> <span class="n">eng</span> <span class="o">=</span> <span class="n">f3d</span><span class="o">::</span><span class="n">engine</span><span class="o">::</span><span class="n">create</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
 
 <span class="c1">// Load a geometry</span>
 <span class="n">eng</span><span class="p">.</span><span class="n">getScene</span><span class="p">().</span><span class="n">add</span><span class="p">(</span><span class="s">"path/to/file.ext"</span><span class="p">);</span>

doc/libf3d/OVERVIEW.md

@@ -80,8 +80,8 @@ Manipulating the window directly can be done this way:
 // Load VTK native readers
 f3d::engine::autoloadPlugins();
 
-// Create a f3d::engine
-f3d::engine eng(f3d::window::Type::NATIVE_OFFSCREEN);
+// Create a f3d::engine with a offscreen window
+f3d::engine eng = f3d::engine::create(true);
 
 // Load a geometry
 eng.getScene().add("path/to/file.ext");

doc/libf3d/doxygen/_sources/api/class_structf3d_1_1exception.rst

@@ -18,6 +18,8 @@ Base Type
 Derived Types
 *************
 
+- ``public f3d::context::loading_exception`` (:ref:`exhale_struct_structf3d_1_1context_1_1loading__exception`)
+- ``public f3d::context::symbol_exception`` (:ref:`exhale_struct_structf3d_1_1context_1_1symbol__exception`)
 - ``public f3d::engine::no_interactor_exception`` (:ref:`exhale_struct_structf3d_1_1engine_1_1no__interactor__exception`)
 - ``public f3d::engine::no_window_exception`` (:ref:`exhale_struct_structf3d_1_1engine_1_1no__window__exception`)
 - ``public f3d::engine::plugin_exception`` (:ref:`exhale_struct_structf3d_1_1engine_1_1plugin__exception`)

doc/libf3d/doxygen/_sources/api/classf3d_1_1context.rst

@@ -0,0 +1,28 @@
+.. _exhale_class_classf3d_1_1context:
+
+Class context
+=============
+
+- Defined in :ref:`file_public_context.h`
+
+
+Nested Relationships
+--------------------
+
+
+Nested Types
+************
+
+- :ref:`exhale_struct_structf3d_1_1context_1_1loading__exception`
+- :ref:`exhale_struct_structf3d_1_1context_1_1symbol__exception`
+
+
+Class Documentation
+-------------------
+
+
+.. doxygenclass:: f3d::context
+   :project: libf3d
+   :members:
+   :protected-members:
+   :undoc-members:

doc/libf3d/doxygen/_sources/api/dir_public.rst

@@ -12,6 +12,7 @@ Files
 -----
 
 - :ref:`file_public_camera.h`
+- :ref:`file_public_context.h`
 - :ref:`file_public_engine.h`
 - :ref:`file_public_exception.h`
 - :ref:`file_public_image.h`

doc/libf3d/doxygen/_sources/api/file_public_context.h.rst

@@ -0,0 +1,68 @@
+
+.. _file_public_context.h:
+
+File context.h
+==============
+
+|exhale_lsh| :ref:`Parent directory <dir_public>` (``public``)
+
+.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS
+
+
+.. contents:: Contents
+   :local:
+   :backlinks: none
+
+Definition (``public/context.h``)
+---------------------------------
+
+
+.. toctree::
+   :maxdepth: 1
+
+   program_listing_file_public_context.h.rst
+
+
+
+
+
+Includes
+--------
+
+
+- ``exception.h`` (:ref:`file_public_exception.h`)
+
+- ``export.h``
+
+- ``functional``
+
+- ``string``
+
+
+
+Included By
+-----------
+
+
+- :ref:`file_public_engine.h`
+
+
+
+
+Namespaces
+----------
+
+
+- :ref:`namespace_f3d`
+
+
+Classes
+-------
+
+
+- :ref:`exhale_struct_structf3d_1_1context_1_1loading__exception`
+
+- :ref:`exhale_struct_structf3d_1_1context_1_1symbol__exception`
+
+- :ref:`exhale_class_classf3d_1_1context`
+

doc/libf3d/doxygen/_sources/api/file_public_engine.h.rst

@@ -30,6 +30,8 @@ Includes
 --------
 
 
+- ``context.h`` (:ref:`file_public_context.h`)
+
 - ``exception.h`` (:ref:`file_public_exception.h`)
 
 - ``export.h``

doc/libf3d/doxygen/_sources/api/file_public_exception.h.rst

@@ -40,6 +40,8 @@ Included By
 -----------
 
 
+- :ref:`file_public_context.h`
+
 - :ref:`file_public_engine.h`
 
 - :ref:`file_public_image.h`

doc/libf3d/doxygen/_sources/api/namespace_f3d.rst

@@ -19,6 +19,10 @@ Classes
 
 - :ref:`exhale_struct_structf3d_1_1camera__state__t`
 
+- :ref:`exhale_struct_structf3d_1_1context_1_1loading__exception`
+
+- :ref:`exhale_struct_structf3d_1_1context_1_1symbol__exception`
+
 - :ref:`exhale_struct_structf3d_1_1engine_1_1libInformation`
 
 - :ref:`exhale_struct_structf3d_1_1engine_1_1no__interactor__exception`
@@ -45,6 +49,8 @@ Classes
 
 - :ref:`exhale_class_classf3d_1_1camera`
 
+- :ref:`exhale_class_classf3d_1_1context`
+
 - :ref:`exhale_class_classf3d_1_1engine`
 
 - :ref:`exhale_class_structf3d_1_1exception`

doc/libf3d/doxygen/_sources/api/program_listing_file_public_context.h.rst

@@ -0,0 +1,54 @@
+
+.. _program_listing_file_public_context.h:
+
+Program Listing for File context.h
+==================================
+
+|exhale_lsh| :ref:`Return to documentation for file <file_public_context.h>` (``public/context.h``)
+
+.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS
+
+.. code-block:: cpp
+
+   #ifndef f3d_context_h
+   #define f3d_context_h
+   
+   #include "exception.h"
+   #include "export.h"
+   
+   #include <functional>
+   #include <string>
+   
+   namespace f3d
+   {
+   class F3D_EXPORT context
+   {
+   public:
+     using fptr = void (*)();
+     using function = std::function<fptr(const char*)>;
+   
+     static function glx();
+   
+     static function wgl();
+   
+     static function cocoa();
+   
+     static function egl();
+   
+     static function osmesa();
+   
+     static function getSymbol(const std::string& lib, const std::string& func);
+   
+     struct loading_exception : public exception
+     {
+       explicit loading_exception(const std::string& what = "");
+     };
+   
+     struct symbol_exception : public exception
+     {
+       explicit symbol_exception(const std::string& what = "");
+     };
+   };
+   }
+   
+   #endif

doc/libf3d/doxygen/_sources/api/program_listing_file_public_engine.h.rst

@@ -13,6 +13,7 @@ Program Listing for File engine.h
    #ifndef f3d_engine_h
    #define f3d_engine_h
    
+   #include "context.h"
    #include "exception.h"
    #include "export.h"
    #include "interactor.h"
@@ -29,10 +30,38 @@ Program Listing for File engine.h
    class F3D_EXPORT engine
    {
    public:
-     explicit engine(window::Type windowType = window::Type::NATIVE);
+     static engine create(bool offscreen = false);
+   
+     static engine createNone();
+   
+     static engine createGLX(bool offscreen = false);
+   
+     static engine createWGL(bool offscreen = false);
+   
+     static engine createEGL(bool offscreen = false);
+   
+     static engine createOSMesa();
+   
+     static engine createExternal(const context::function& getProcAddress);
+   
+     static engine createExternalGLX();
+   
+     static engine createExternalWGL();
+   
+     static engine createExternalCOCOA();
+   
+     static engine createExternalEGL();
+   
+     static engine createExternalOSMesa();
    
      ~engine();
    
+   
+     engine(const engine& other) = delete;
+     engine(engine&& other) noexcept;
+     engine& operator=(const engine& other) = delete;
+     engine& operator=(engine&& other) noexcept;
+   
      void setCachePath(const std::string& cachePath);
    
      engine& setOptions(const options& opt);
@@ -100,10 +129,9 @@ Program Listing for File engine.h
    private:
      class internals;
      internals* Internals;
-     engine(const engine& opt) = delete;
-     engine(engine&& opt) = delete;
-     engine& operator=(const engine& opt) = delete;
-     engine& operator=(engine&& opt) = delete;
+   
+     engine(
+       const std::optional<window::Type>& windowType, bool offscreen, const context::function& loader);
    };
    }