Create a public vtkext module that can be used by both libf3d and plugins

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

@@ -219,7 +219,7 @@ runs:
       working-directory: ${{github.workspace}}/build
       run: cmake --install . --component mimetypes
 
-    - name: Install optional component
+    - name: Install optional component for libf3d
       shell: bash
       working-directory: ${{github.workspace}}/build
       run: |
@@ -256,11 +256,18 @@ runs:
       working-directory: ${{github.workspace}}
       run: ctest --test-dir build_examples -C Release -VV
 
+    - name: Install optional component f3d plugins
+      shell: bash
+      working-directory: ${{github.workspace}}/build
+      run: cmake --install . --component plugin_sdk
+
+      # CMAKE_MODULE_PATH is required because of
+      # https://github.com/AcademySoftwareFoundation/openvdb/issues/1160
     - name: Build plugin examples
       shell: bash
       working-directory: ${{github.workspace}}
       run: |
-        cmake -Werror=dev -Werror=deprecated --warn-uninitialized -Df3d_DIR:PATH=$(pwd)/install/lib/cmake/f3d -DCMAKE_PREFIX_PATH:PATH=$(pwd)/dependencies/install/ -DCMAKE_INSTALL_PREFIX=$(pwd)/install/ -DBUILD_TESTING=ON -DCMAKE_OSX_ARCHITECTURES=${{ inputs.cpu }} -B build_plugins source/examples/plugins
+        cmake -Werror=dev -Werror=deprecated --warn-uninitialized -DCMAKE_MODULE_PATH=$(pwd)/dependencies/install/lib/cmake/OpenVDB/ -Df3d_DIR=$(pwd)/install/lib/cmake/f3d -DCMAKE_PREFIX_PATH:PATH=$(pwd)/dependencies/install/ -DCMAKE_INSTALL_PREFIX=$(pwd)/install/ -DBUILD_TESTING=ON -DCMAKE_OSX_ARCHITECTURES=${{ inputs.cpu }} -B build_plugins source/examples/plugins
         cmake --build build_plugins --config Release
 
     - name: Test plugin examples

.github/actions/vtk_commit_sha

@@ -1 +1 @@
-697646db54ce4de95ff5adb500799e49feee4935
+1312f8a7263f9a960a038b1f72d121f3d47f1f17

CMakeLists.txt

@@ -158,6 +158,22 @@ if(NOT F3D_SANITIZER STREQUAL "none")
   set(f3d_sanitizer_link_options -fsanitize=${F3D_SANITIZER})
 endif()
 
+# Construct generic build and link options
+set(f3d_compile_options_private "")
+set(f3d_compile_options_public "")
+set(f3d_link_options_public "")
+
+## F3D_STRICT_BUILD
+list(APPEND f3d_compile_options_private ${f3d_strict_build_compile_options})
+
+## Coverage
+list(APPEND f3d_compile_options_public ${f3d_coverage_compile_options})
+list(APPEND f3d_link_options_public ${f3d_coverage_link_options})
+
+## Sanitizer
+list(APPEND f3d_compile_options_public ${f3d_sanitizer_compile_options})
+list(APPEND f3d_link_options_public ${f3d_sanitizer_link_options})
+
 # Testing
 option(BUILD_TESTING "Build the tests" OFF)
 cmake_dependent_option(F3D_TESTING_DISABLE_DEFAULT_LIGHTS_TESTS_COMPARISON "Disable image comparison on tests using the default lights" OFF "BUILD_TESTING" OFF)
@@ -189,6 +205,9 @@ endif()
 # F3D Application
 cmake_dependent_option(F3D_BUILD_APPLICATION "Build the application" ON "NOT ANDROID AND NOT EMSCRIPTEN" OFF)
 
+# Build VTK extension moddules
+add_subdirectory(vtkext)
+
 # plugins
 option(F3D_PLUGINS_STATIC_BUILD "Make all plugins static (embedded into libf3d) and automatically loaded by F3D" ON)
 mark_as_advanced(F3D_PLUGINS_STATIC_BUILD)

application/CMakeLists.txt

@@ -175,6 +175,21 @@ install(TARGETS f3d
   RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT application
   BUNDLE DESTINATION "." COMPONENT application)
 
+# The targets and config file are only installed with the sdk
+install(EXPORT f3dTargets
+  NAMESPACE f3d::
+  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/f3d"
+  COMPONENT sdk
+  EXCLUDE_FROM_ALL)
+
+install(
+  FILES
+    "${F3D_SOURCE_DIR}/cmake/application-config.cmake"
+  DESTINATION
+    "${CMAKE_INSTALL_LIBDIR}/cmake/f3d"
+  COMPONENT sdk
+  EXCLUDE_FROM_ALL)
+
 # Default config files
 install(
   DIRECTORY "${F3D_SOURCE_DIR}/resources/configs/"

cmake/application-config.cmake

@@ -0,0 +1,9 @@
+# Provide f3d::f3d target
+include("${CMAKE_CURRENT_LIST_DIR}/f3dTargets.cmake")
+
+# Provide a f3d_embed_file method for embedding image into source code
+include("${CMAKE_CURRENT_LIST_DIR}/f3dEmbed.cmake")
+
+# Set the required variable
+message(STATUS "Found f3d application component")
+set(f3d_application_FOUND TRUE) 

cmake/f3dConfig.cmake.in

@@ -1,24 +1,47 @@
-# When this file is run by CMake through the find_package command, the
-# following targets will exist:
+# When this file is run by CMake through the find_package command
+#
+# The following variables will be defined:
+#
+#   f3d_BINDINGS_JAVA              Will be enabled if F3D was built with java bindings
+#   f3d_BINDINGS_PYTHON            Will be enabled if F3D was built with python bindings
+#   f3d_BUILD_APPLICATION          Will be enabled if F3D application was built
+#   f3d_CONFIG_DIR                 Path to F3D configuration directory, can be absolute or relative
+#   f3d_MODULE_EXR                 Will be enabled if F3D was built with OpenEXR images support
+#   f3d_MODULE_EXTERNAL_RENDERING  Will be enabled if F3D was built with external rendering support
+#   f3d_MODULE_RAYTRACING          Will be enabled if F3D was built with raytracing support
+#   f3d_PLUGINS_INSTALL_DIR        Path to the location to install plugins so that F3D can find them
+#
+# It is also possible to look for optional components.
+#
+# Optional components are:
+#
+# `application`: If found, it the following target will exist
 #
 #   f3d::f3d           Target that contains the F3D executable
 #
+# `library`: If found, it the following target will exist
+#
 #   f3d::libf3d        Target that contains the libf3d
 #
-# The following local variables will also be defined:
+# And the following local variable will also be defined
 #
-#   f3d_BUILD_APPLICATION          Will be enabled if F3D application was built
-#   f3d_MODULE_EXTERNAL_RENDERING  Will be enabled if F3D was built with external rendering support
-#   f3d_MODULE_RAYTRACING          Will be enabled if F3D was built with raytracing support
-#   f3d_MODULE_EXR                 Will be enabled if F3D was built with OpenEXR images support
-#   f3d_BINDINGS_PYTHON            Will be enabled if F3D was built with python bindings
-#   f3d_BINDINGS_JAVA              Will be enabled if F3D was built with java bindings
 #   f3d_INCLUDE_DIR                Absolute path to the include directory of public f3d library classes
-#   f3d_CONFIG_DIR                 Path to F3D configuration directory, can be absolute or relative
-#   f3d_PLUGINS_INSTALL_DIR        Relative path to F3D plugins install directory
+#
+# `pluginsdk`: If found many plugin related cmake macros will be available as well as the following target:
+#
+#   f3d::vtkext
+#
+# And the following local variable will also be defined
+#
+#   f3d_INCLUDE_DIR                Absolute path to the include directory of classes needed to build a plugin
+#
+# Please note, if no components are set, `library` will be added by default
 
 @PACKAGE_INIT@
 
+include(${CMAKE_CURRENT_LIST_DIR}/f3dConfigVersion.cmake)
+message(STATUS "Found f3d ${PACKAGE_VERSION}")
+
 set(f3d_BUILD_APPLICATION "@F3D_BUILD_APPLICATION@")
 set(f3d_MODULE_EXTERNAL_RENDERING "@F3D_MODULE_EXTERNAL_RENDERING@")
 set(f3d_MODULE_RAYTRACING "@F3D_MODULE_RAYTRACING@")
@@ -28,12 +51,23 @@ set(f3d_BINDINGS_JAVA "@F3D_BINDINGS_JAVA@")
 set(f3d_CONFIG_DIR "@f3d_config_dir@")
 set(f3d_PLUGINS_INSTALL_DIR "@F3D_PLUGINS_INSTALL_DIR@")
 
-# Provide a f3d_embed_file method for embedding image into source code
-include("${CMAKE_CURRENT_LIST_DIR}/f3dEmbed.cmake")
+# If no components specified, look for `library` component
+if(NOT f3d_FIND_COMPONENTS)
+  set(f3d_FIND_COMPONENTS library)
+  set(f3d_FIND_REQUIRED_library TRUE)
+endif()
 
-# Provide macros used to create a plugin
-include("${CMAKE_CURRENT_LIST_DIR}/f3dPlugin.cmake")
+foreach(component ${f3d_FIND_COMPONENTS})
+  # For requested component, execute its "config" script
+  if(EXISTS ${CMAKE_CURRENT_LIST_DIR}/${component}-config.cmake)
+    include(${CMAKE_CURRENT_LIST_DIR}/${component}-config.cmake)
+  else()
+    if (${f3d_FIND_REQUIRED_${component}})
+      message(FATAL_ERROR "${component} was requested but could not be found, "
+        "${CMAKE_CURRENT_LIST_DIR}/${component}-config.cmake is missing, "
+        "please check component was installed")
+    endif ()
+  endif()
+endforeach()
 
-include("${CMAKE_CURRENT_LIST_DIR}/f3dTargets.cmake")
-set_and_check(f3d_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")
 check_required_components(f3d)

cmake/f3dPlugin.cmake

@@ -172,10 +172,8 @@ macro(f3d_plugin_build)
   cmake_parse_arguments(F3D_PLUGIN "FREEDESKTOP;FORCE_STATIC" "NAME;DESCRIPTION;VERSION" "VTK_MODULES;ADDITIONAL_RPATHS;MIMETYPE_XML_FILES;CONFIGURATION_DIRS" ${ARGN})
 
   find_package(VTK 9.0 REQUIRED COMPONENTS
-    CommonCore
-    CommonExecutionModel
-    IOImport
-    ${F3D_PLUGIN_VTK_MODULES})
+               CommonCore CommonExecutionModel IOImport
+               ${F3D_PLUGIN_VTK_MODULES})
 
   if(F3D_PLUGIN_FORCE_STATIC OR F3D_PLUGINS_STATIC_BUILD)
     set(F3D_PLUGIN_TYPE "STATIC")
@@ -249,11 +247,14 @@ macro(f3d_plugin_build)
     EXPORT_FILE_NAME plugin_export.h
     EXPORT_MACRO_NAME F3D_PLUGIN_EXPORT)
 
-  if(UNIX)
+  # Add rpath origin so the vtkext lib can be found
+  if (APPLE)
+    set_target_properties(f3d-plugin-${F3D_PLUGIN_NAME} PROPERTIES INSTALL_RPATH @loader_path)
+  elseif (UNIX)
     # On Unix, add the RPATH to VTK install folder
     get_target_property(target_type VTK::CommonCore TYPE)
     if (target_type STREQUAL SHARED_LIBRARY)
-      list(APPEND F3D_PLUGIN_ADDITIONAL_RPATHS "$<TARGET_FILE_DIR:VTK::CommonCore>")
+      list(APPEND F3D_PLUGIN_ADDITIONAL_RPATHS "$ORIGIN:$<TARGET_FILE_DIR:VTK::CommonCore>")
     endif ()
     set_target_properties(f3d-plugin-${F3D_PLUGIN_NAME} PROPERTIES
       INSTALL_RPATH "${F3D_PLUGIN_ADDITIONAL_RPATHS}")
@@ -289,7 +290,7 @@ macro(f3d_plugin_build)
   list(TRANSFORM F3D_PLUGIN_VTK_MODULES PREPEND "VTK::")
 
   target_link_libraries(f3d-plugin-${F3D_PLUGIN_NAME} PRIVATE
-    VTK::CommonCore VTK::CommonExecutionModel VTK::IOImport
+    VTK::CommonCore VTK::CommonExecutionModel VTK::IOImport f3d::vtkext
     ${F3D_PLUGIN_VTK_MODULES}
     ${modules})
 

cmake/library-config.cmake

@@ -0,0 +1,9 @@
+# Provide f3d::libf3d target
+include("${CMAKE_CURRENT_LIST_DIR}/f3dLibraryTargets.cmake")
+
+# Provide f3d_INCLUDE_DIR
+set_and_check(f3d_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")
+
+# Set the required variable
+message(STATUS "Found f3d library component")
+set(f3d_library_FOUND TRUE) 

cmake/pluginsdk-config.cmake

@@ -0,0 +1,15 @@
+# Find VTK and other dependencies at top level as f3d_vtkext-targets need it
+if (UNIX AND NOT APPLE)
+  find_package(X11)
+endif()
+find_package(OpenGL)
+find_package(VTK 9.0 REQUIRED COMPONENTS CommonCore CommonExecutionModel IOImport)
+include("${CMAKE_CURRENT_LIST_DIR}/f3dPlugin.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/../f3d_vtkext/f3d_vtkext-targets.cmake")
+
+# Provide f3d_INCLUDE_DIR
+set_and_check(f3d_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")
+
+# Set the required variable
+message(STATUS "Found f3d plugin component")
+set(f3d_pluginsdk_FOUND TRUE) 

doc/dev/BUILD.md

@@ -75,16 +75,17 @@ Here is the list of all the components:
 
 Name|Installed by default|Operating system|Description
 ------|------|------|------
-`application`|YES|ALL|F3D application
+`application`|YES|ALL|F3D application.
 `configuration`|NO|ALL|Default configuration files, `config` and `thumbnail`.
-`library`|YES|ALL|libf3d library binaries
-`plugin`|YES|ALL|libf3d plugins
+`library`|YES|ALL|libf3d library binaries.
+`plugin`|YES|ALL|libf3d plugins.
 `dependencies`|NO|ALL|libf3d runtime dependencies. Can be used to create a self-contained and relocatable package. System libraries are excluded.
-`sdk`|NO|ALL|libf3d SDK (headers and CMake config files)
-`licenses`|YES|ALL|F3D and third party licenses
-`documentation`|YES|Linux|`man` documentation
-`shellext`|YES|Windows/Linux|Desktop integration
-`python`|YES|ALL|Python bindings
-`java`|YES|ALL|Java bindings
-`mimetypes`|NO|Linux|Plugins mimetype XML files for integration with Freedesktop
-`assets`|YES|Linux|Assets for integration with Freedesktop
+`sdk`|NO|ALL|libf3d SDK (headers and CMake config files) for `library` and `application` find_package components.
+`plugin_sdk`|NO|ALL|libf3d plugin SDK (headers and CMake config files including macros) for `pluginsdk` find_package components.
+`licenses`|YES|ALL|F3D and third party licenses.
+`documentation`|YES|Linux|`man` documentation.
+`shellext`|YES|Windows/Linux|Desktop integration.
+`python`|YES|ALL|Python bindings.
+`java`|YES|ALL|Java bindings.
+`mimetypes`|NO|Linux|Plugins mimetype XML files for integration with Freedesktop.
+`assets`|YES|Linux|Assets for integration with Freedesktop.

doc/libf3d/OVERVIEW.md

@@ -125,15 +125,25 @@ For the complete documentation, please consult the [libf3d doxygen documentation
 
 ## Building against the libf3d
 
-Please follow instructions in the [F3D build guide](../dev/BUILD.md), then use CMake to find the libf3d
+Please follow instructions in the [F3D build guide](../dev/BUILD.md), and make sure to install the `sdk` component then use CMake to find the libf3d
 and link against it like this in your CMakeLists.txt:
 
 ```cmake
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 [...]
 target_link_libraries(target f3d::libf3d)
 ```
 
+## find_package COMPONENTS
+
+When using `find_package(f3d)` and `sdk` CMake component have been installed, you can require specific components:
+ - `application`: access to f3d::f3d target
+ - `library`: access to f3d::libf3d target and include dir
+ - `plugin_sdk`: access to CMake macros to create plugins, the f3d::vtkext target and include dir
+
+see the installed `f3dConfig.cmake` file for more info.
+
 ## Extending libf3d with plugins
 
 In order to add new supported file format to libf3d, you can create a plugin using CMake macros. Please follow instructions in the [F3D plugin SDK guide](PLUGINS.md).
+Also make sure the `plugin_sdk` component have been installed as well as the `sdk` component.

doc/libf3d/PLUGINS.md

@@ -1,6 +1,6 @@
 # Plugin SDK
 
-When calling `find_package(f3d)` in CMake, a few macros are made available to you to generate a plugin which allow you to extend libf3d to support your own file format.
+When calling `find_package(f3d REQUIRED COMPONENTS pluginsdk)` in CMake, 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](../../CONTRIBUTING.md) your plugin in [F3D directly](https://github.com/f3d-app/f3d/tree/master/plugins) if you think it can be useful to the community.
 > You can also consider contributing directly [in VTK](https://gitlab.kitware.com/vtk/vtk/blob/master/Documentation/dev/git/develop.md).
 
@@ -61,3 +61,11 @@ The list of existing mimetypes can be find [here](https://www.iana.org/assignmen
 
 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
+
+See respective header of these class for a more complete documentation.

examples/README.md

@@ -1,6 +1,6 @@
 # Examples
 
-This folder contains examples on how to use `libf3d`. All the examples are using `find_package(f3d)` so they are intended to be built against an existing f3d installation.
+This folder contains examples on how to use `libf3d`. All the examples are using some form of `find_package(f3d)` so they are intended to be built against an existing f3d installation with the `sdk` or `plugin_sdk` component installed.
 The code is documented in a didactic way to help with understanding them.
 
 ## libf3d
@@ -9,7 +9,7 @@ Examples usages of the libf3d, which requires the `sdk` cmake component to be in
 
 ## plugins
 
-Examples plugins for the libf3d, which also requires the `sdk` cmake component to be installed.
+Examples plugins for the libf3d, which also requires the `plugin_sdk` cmake component to be installed.
 
 ## Building
 

examples/libf3d/cpp/CMakeLists.txt

@@ -1,4 +1,4 @@
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 
 if(BUILD_TESTING)
   enable_testing()

examples/libf3d/cpp/check-engine/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 
 project(check-engine)
 
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 
 # Check correctness of variables returned by f3dConfig.cmake
 function(check_variable_defined f3d_var)

examples/libf3d/cpp/multi-geom/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 
 project(multi-geom)
 
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 
 add_executable(multi-geom main.cxx)
 target_link_libraries(multi-geom f3d::libf3d)

examples/libf3d/cpp/render-image/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 
 project(render-image)
 
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 
 add_executable(render-image main.cxx)
 target_link_libraries(render-image f3d::libf3d)

examples/libf3d/cpp/render-interact/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 
 project(render-interact)
 
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS library)
 
 add_executable(render-interact main.cxx)
 target_link_libraries(render-interact f3d::libf3d)

examples/plugins/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.19)
 
 project(libf3d-examples)
 
-find_package(f3d REQUIRED)
+find_package(f3d REQUIRED COMPONENTS pluginsdk)
 
 if(BUILD_TESTING)
   enable_testing()