Plugin SDK

Please follow instructions in the F3D build guide, make sure to build with BUILD_SHARED_LIBS=ON and to install the plugin_sdk component. You will then be able to call find_package(f3d REQUIRED COMPONENTS pluginsdk) in your plugin CMakeLists.txt, a few macros are made available to you to generate a plugin which allow you to extend libf3d to support your own file format. Access to a f3d::vtkext VTK module is also provided if needed.

Please consider contributing your plugin in F3D directly if you think it can be useful to the community. You can also consider contributing directly in VTK.

Creating a plugin

You can take a look at the example in the examples/plugin directory or at the official plugins.

The first thing (and most difficult part) you have to do is creating a VTK reader (or a VTK importer if you want to support a full scene with materials, lights and cameras), and wrap it into a VTK module. You can create several readers/importers in the same VTK module if you need to support several file formats in a single plugin.

Then, declare the reader(s) and the plugin using the CMake macros:

f3d_plugin_init()

f3d_plugin_declare_reader(
  NAME "ReaderName"
  EXTENSIONS "myext"                # set the extensions the reader can support
  MIMETYPES "application/vnd.myext" # set the mimetypes the reader can support
  VTK_READER ${vtk_classname}       # set the name of the VTK reader class you have created
  FORMAT_DESCRIPTION "description"  # set the proper name of the file format
  EXCLUDE_FROM_THUMBNAILER          # add this flag if you don't want thumbnail generation for this reader
  OPTIONS "option1" "option2"       # use this to define reader specific option that can be defined by the user
)

f3d_plugin_declare_reader(
  NAME "ReaderNameWithScene"
  EXTENSIONS "myext2"                # set the extensions the reader can support
  MIMETYPES "application/vnd.myext2" # set the mimetypes the reader can support
  VTK_IMPORTER ${vtk_classname}      # set the name of the VTK importer class you have created
  FORMAT_DESCRIPTION "description"   # set the proper name of the file format
  CUSTOM_CODE "file.inl"             # set this to add a custom code when instancing your class, this is where reader options should be processed
)

# More f3d_plugin_declare_reader calls are possible

f3d_plugin_build(
  NAME "PluginName"
  VERSION 1.0
  DESCRIPTION "Plugin description"
  VTK_MODULES CommonCore CommonExecutionModel # Add more VTK modules if necessary
)

If the build succeeds, a library called libf3d-plugin-<name>.so will be created (f3d-plugin-<name>.dll on Windows) A JSON file of the following form will also be generated. It’s used by F3D internally to get information about supported file formats.

{
  "description": "Plugin description",
  "name": "PluginName",
  "readers": [
    {
      "description": "Reader description",
      "extensions": ["myext"],
      "mimetypes": ["application/vnd.myext"],
      "name": "ReaderName"
    }
  ],
  "type": "MODULE",
  "version": "1.0"
}

The list of existing mimetypes can be find here. If your file format is not listed, the mimetype should be application/vnd.${extension}

Loading your plugin

The plugin can be loaded using f3d::engine::loadPlugin("path or name") API if you are using libf3d, or --load-plugins="path or name" option if you are using F3D application. The option can also be set in a configuration file that you could distribute with your plugin.

f3d::vtkext

F3D provides access to a VTK modules containing utilities that may be useful for plugin developers:

  • vtkF3DFaceVaryingPointDispatcher: A VTK filter that manipulates point data so that F3D can display them as face-varying data (used by usd plugin)
  • vtkF3DBitonicSort: A VTK class that perform Bitonic Sort algorithm on the GPU (used by the splat point sprites rendering algorithm
  • vtkF3DImporter: An Importer class that abstract away support for different version of VTK after some API changes.
  • vtkF3DGLTFImporter: An custom glTF importer class that support armatures, useful when creating other plugin supporting glTF extensions.

For the complete documentation, please consult the vtkext doxygen documentation..