Migrate from v3.5

This guide explains how to migrate the libf3d code base from v3.5 to v4.0.

warning

This guide assumes all deprecation warnings have been addressed, since the deprecated APIs have been removed.

Packagers

CMake variables change

F3D_LINUX_INSTALL_DEFAULT_CONFIGURATION_FILE_IN_PREFIX has been removed in favor of F3D_LINUX_INSTALL_DEFAULT_CONFIGURATION_FILE_IN_SYSCONFDIR, which default to OFF. The default installation location for configuration files is now /usr/share/f3d/configs.

Install components

These components are now installed by default:

• configuration
• sdk
• plugin_sdk
• mimetypes
• colormaps

See building documentation for more information.

Enable options

Many enable libf3d options have been removed in favor of extending possible values on the mode/type related libf3d options.

render.effect.blending.enable have been removed in favor of setting render.effect.blending.mode to none, which is its new default. So to enable blending, just set the mode to the value that used to be the default, ddp.

render.effect.antialiasing.enable have been removed in favor of setting render.effect.antialiasing.mode to none, which is its new default. So to enable anti-aliasing, just set the mode to the value that used to be the default, fxaa.

model.point_sprites.enable have been removed in favor of setting model.point_sprites.type to none, which is its new default. So to enable point sprites, just set the type to the value that used to be the default, sphere.

User callback

When calling f3d::interactor::start() or f3d::interactor::playInteraction(), it was possible to set a user callback automatically called at each event loop. If you were setting such callback, please call f3d::interactor::setEventLoopUserCallback() manually before calling start() or playInteractor(). The callback takes an argument of type f3d::interactor::interactor_state_t allowing you to retrieve useful information about the interactor state.

F3D_PLUGINS_PATH

When running F3D, it was possible to specify the path for loading plugins using the environment variable F3D_PLUGINS_PATH. This variable has been removed in favor of the CLI option --plugins-path which is more secure.

Commands

The following commands have been removed and should be replaced:

• cycle_anti_aliasing -> cycle render.effect.antialiasing.mode
• cycle_blending -> cycle render.effect.blending.mode
• cycle_point_sprites -> cycle model.point_sprites.type
• increase_light_intensity -> increase render.light.intensity (increments are different)
• decrease_light_intensity -> decrease render.light.intensity (increments are different)
• increase_opacity -> increase model.color.opacity
• decrease_opacity -> decrease model.color.opacity
• cycle_interactor_style -> cycle interactor.style

The jump_to_frame and jump_to_keyframe commands no longer take a second boolean argument and now always perform an absolute jump. To perform a relative jump, use the new jump_to_frame_relative and jump_to_keyframe_relative commands:

• jump_to_frame 10 false -> jump_to_frame 10
• jump_to_frame 1 true -> jump_to_frame_relative 1
• jump_to_keyframe 4 false -> jump_to_keyframe 4
• jump_to_keyframe 1 true -> jump_to_keyframe_relative 1

ui.animation_progress

The ui.animation_progress option (CLI --animation-progress) was a boolean toggling a progress bar during animation playback. It is now a string selecting the progress bar mode: none (hidden), default (the progress bar alone) or advanced (the progress bar with time range, animation name, current time labels and keyframe markers). Replace true with default (or advanced) and false with none.

Context symbol

The function f3d::context::getSymbol function is now expecting a library full path or a filename. The library prefix and extension is not appended automatically anymore.

DPI scaling

f3d::window::getDPIScale() should now be used instead of the static f3d::utils::getDPIScale() API to get the DPI scaling value.

Bindings

Python

The following Python setter methods have been removed in favor of new properties, which can also be read.

• window.set_position(x, y) -> window.position = (x, y)
• engine.set_cache_path(path) -> engine.cache_path = path

WebAssembly

The following WebAssembly methods have been removed in favor of new properties, which can also be read.

• engine.setCachePath(path) -> engine.cachePath = path

C

Some functions has been renamed for consistency. All functions allocating an object have the word create and all functions deleting an object have the word destroy.

3.5	4.0
f3d_*_new*	f3d_*_create*
f3d_*_free*	f3d_*_destroy*
f3d_*_delete*	f3d_*_destroy*

scene.supports method

scene::supports() method signature changed, it now returns f3d::file_availability enum instead of bool. Here is how you can check if a file is supported now:

if (scene.supports("some.obj") == f3d::file_availability::SUPPORTED)

Other languages API behavior changed accordingly:

• C API:
  • f3d_scene_supports() used to return 1 if the file was supported and 0 otherwise. It now returns an int: 0 if supported, 1 for unsupported extension, 2 for unsupported content, -1 if the scene or file path is NULL.
  • f3d_interactor_add_binding now requires a repeat argument, which specifies that the binding is repeatedly applied when holding down the key.
• Java API:
  • Scene.supports() used to return a boolean. It now returns the Scene.FileAvailability enum and throws IllegalArgumentException if the file path is null.
  • Interactor.addBinding() now requires a repeat argument which specifies that the binding is repeatedly applied when holding down the key.
• Python API: scene.supports() used to return bool. Now returns f3d.FileAvailability.
• Webassembly API: scene.supports() used to return bool. Now returns enum FileAvailability.

Plugin developers

If you were using the VTK extension module with your plugin, headers are now located in f3d/vtk_ext/ folder instead of f3d/ directly.