Skip to main content
Version: 🚧 Nightly

Class f3d::engine

Definition: engine.h (line 38)

Class used to create instance of other classes.

The main class of the libf3d to create all other instances. Configured on creation using an enum, then all objects can be accessed through their getter.

Example usage for adding some files in the scene

f3d::engine eng = f3d::engine::create();
f3d::scene& sce = eng.getscene();
sce.add({"path/to/file", "path/to/another/file"});
f3d::interactor& inter = eng.getInteractor();
inter.start();

Inner classes​

Members​

Private attributes​

Variable Internals​

Definition: engine.h (line 385)

internals* f3d::engine::Internals

Type: internals *

Public static functions​

Function create​

static engine f3d::engine::create(bool offscreen=false)

Create an engine with an automatic window. Optionally, the window can be hidden by setting offscreen to true. For VTK < 9.3, the window type will depend on the VTK build options. For VTK >= 9.4: Linux: Try GLX, then EGL, then OSMesa. Windows: Try Win32, then EGL, then OSMesa. macOS: Always use Cocoa.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Parameters:

  • bool offscreen = false

Return type: engine

Function createNone​

static engine f3d::engine::createNone()

Create an engine with no window.

Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createGLX​

static engine f3d::engine::createGLX(bool offscreen=false)

Create an engine with a GLX window. Works on Linux only. VTK >= 9.4 required. Optionally, the window can be hidden by setting offscreen to true.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Parameters:

  • bool offscreen = false

Return type: engine

Function createWGL​

static engine f3d::engine::createWGL(bool offscreen=false)

Create an engine with a WGL window. Works on Windows only. VTK >= 9.4 required. Optionally, the window can be hidden by setting offscreen to true.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Parameters:

  • bool offscreen = false

Return type: engine

Function createEGL​

static engine f3d::engine::createEGL()

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.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createOSMesa​

static engine f3d::engine::createOSMesa()

Create an engine with an offscreen OSMesa window. VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createExternal​

static engine f3d::engine::createExternal(const context::function &getProcAddress)

Create an engine with an external window. A context to retrieve OpenGL symbols is required. Here's an example if a GLFW window is used:

f3d::engine eng = f3d::engine::createExternal(glfwGetProcAddress);

Throws a engine::no_window_exception if the window cannot be created. Throws a engine::cache_exception if the default cache directory cannot be used.

Parameters:

  • const context::function & getProcAddress

Return type: engine

Function createExternalGLX​

static engine f3d::engine::createExternalGLX()

Create an engine with an external GLX context. Equivalent to createExternal(f3d::context::glx()); VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createExternalWGL​

static engine f3d::engine::createExternalWGL()

Create an engine with an external WGL context. Equivalent to createExternal(f3d::context::wgl()); VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createExternalCOCOA​

static engine f3d::engine::createExternalCOCOA()

Create an engine with an external COCOA context. Equivalent to createExternal(f3d::context::cocoa()); VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createExternalEGL​

static engine f3d::engine::createExternalEGL()

Create an engine with an external EGL context. Equivalent to createExternal(f3d::context::egl()); VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function createExternalOSMesa​

static engine f3d::engine::createExternalOSMesa()

Create an engine with an external OSMesa context. Equivalent to createExternal(f3d::context::osmesa()); VTK >= 9.4 required.

Throws a context::loading_exception if a needed graphic library cannot be loaded. Throws a context::symbol_exception if a needed symbol cannot be found in graphic library. Throws a engine::no_window_exception if the window cannot be created for another reason. Throws a engine::cache_exception if the default cache directory cannot be used.

Return type: engine

Function getRenderingBackendList​

static std::map< std::string, bool > f3d::engine::getRenderingBackendList()

List rendering backends supported by libf3d. All backends have an associated boolean flag indicating if it can be used.

Return type: std::map< std::string, bool >

Function loadPlugin​

static void f3d::engine::loadPlugin(const std::string &pathOrName, const std::vector< std::filesystem::path > &pluginSearchPaths={})

Load a plugin. The provided pathOrName can be a full path, relative path, or plugin name. First try to load the plugin by name from the static plugins. Then try to load the path provided as if it is a full path to a plugin. Then try to load a plugin by its name looking into the provided plugin search paths (used as is). Then try to load a plugin by its name relying on internal system (eg: LD_LIBRARY_PATH).

The plugin "native" is always available and includes native VTK readers. If built and available in your build, F3D is providing 6 additional plugins: "alembic", "assimp", "draco", "hdf", "occt", "usd", "vdb".

Custom plugins can also be available that F3D is not supporting officially. Throws a engine::plugin_exception if the plugin can't be loaded for some reason.

Parameters:

  • const std::string & pathOrName
  • const std::vector< std::filesystem::path > & pluginSearchPaths =

Return type: void

Function autoloadPlugins​

static void f3d::engine::autoloadPlugins()

Automatically load all the static plugins. The plugin "native" is guaranteed to be static.

Return type: void

Function getPluginsList​

static std::vector< std::string > f3d::engine::getPluginsList(const std::filesystem::path &pluginPath)

List plugins based on associated json files located in the given directory, used as is. Listed plugins can be loaded using engine::loadPlugin function. Note that the listed plugins may fail to load if the library is not found or incompatible.

Return available plugins if any, or an empty vector if there are none or the provided path does not exist.

Parameters:

  • const std::filesystem::path & pluginPath

Return type: std::vector< std::string >

Function getAllReaderOptionNames​

static std::vector< std::string > f3d::engine::getAllReaderOptionNames()

Get all plugin option names that can be set using setReaderOption This vector can be expanded when loading plugin using loadPlugin

Return type: std::vector< std::string >

Function setReaderOption​

static void f3d::engine::setReaderOption(const std::string &name, const std::string &value)

Set a specific reader option from a plugin to provided value if it exists. Throws a options::inexistent_exception if the option does not exists in any reader of any plugin.

Parameters:

  • const std::string & name
  • const std::string & value

Return type: void

Function getLibInfo​

static libInformation f3d::engine::getLibInfo()

Get a struct containing info about the libf3d.

Return type: libInformation

Function getReadersInfo​

static std::vector< readerInformation > f3d::engine::getReadersInfo()

Get a vector of struct containing info about the supported readers.

Return type: std::vector< readerInformation >

Public functions​

Function ~engine​

f3d::engine::~engine()

Engine destructor, delete all object instances as well.

Return type:

Function engine​

f3d::engine::engine(const engine &other)=delete

Engine copy is not possible but move is allowed.

Parameters:

Return type:

Function engine​

f3d::engine::engine(engine &&other) noexcept

Parameters:

Return type:

Function operator=​

engine & f3d::engine::operator=(const engine &other)=delete

Parameters:

Return type: engine &

Function operator=​

engine & f3d::engine::operator=(engine &&other) noexcept

Parameters:

Return type: engine &

Function setCachePath​

engine & f3d::engine::setCachePath(const std::filesystem::path &cachePath)

Set the cache path. The provided path is used as is. Currently, it's only used to store HDRI baked textures. By default, the cache path is:

  • Windows: LOCALAPPDATA%\f3d

  • Linux: ~/.cache/f3d

  • macOS: ~/Library/Caches/f3d

Throws a engine::cache_exception if the provided cachePath cannot be used.

Parameters:

  • const std::filesystem::path & cachePath

Return type: engine &

Function setOptions​

engine & f3d::engine::setOptions(const options &opt)

Engine provide a default options that you can use using engine::getOptions(). But you can use this setter to use other options directly. It will copy options into engine.

Parameters:

Return type: engine &

Function setOptions​

engine & f3d::engine::setOptions(options &&opt)

Engine provide a default options that you can use using engine::getOptions(). But you can use this setter to use other options directly. It will move options into engine.

Parameters:

Return type: engine &

Function getOptions​

options & f3d::engine::getOptions()

Get the default options provided by the engine.

Return type: options &

Function getWindow​

window & f3d::engine::getWindow()

Get the window provided by the engine, if any. If not, will throw a engine::no_window_exception.

Return type: window &

Function getScene​

scene & f3d::engine::getScene()

Get the loaded provided by the engine.

Return type: scene &

Function getInteractor​

interactor & f3d::engine::getInteractor()

Get the interactor provided by the engine, if any. If not, will throw a engine::no_interactor_exception.

Return type: interactor &

Private functions​

Function engine​

f3d::engine::engine(const std::optional< window::Type > &windowType, bool offscreen, const context::function &loader)

Engine constructor. This is a private method. The user must rely on factories to create the engine instance.

Parameters:

  • const std::optional< window::Type > & windowType
  • bool offscreen
  • const context::function & loader

Return type: