Magnum::Trade::BasisImageConverter class new in 2019.10

Basis Universal image converter plugin.

Creates Basis Universal (*.basis) files from images with format PixelFormat::R8Unorm, PixelFormat::RG8Unorm, PixelFormat::RGB8Unorm or PixelFormat::RGBA8Unorm. Use BasisImporter to import images in this format.

This plugin depends on the Trade and Basis Universal libraries and is built if WITH_BASISIMAGECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, you need to load the "BasisImageConverter" plugin from MAGNUM_PLUGINS_IMAGECONVERTER_DIR. To use as a static plugin or as a dependency of another plugin with CMake, you need to request the BasisImageConverter component of the MagnumPlugins package and link to the MagnumPlugins::BasisImageConverter target. See Downloading and building plugins, Plugin usage with CMake and Loading and using plugins for more information.

Plugin-specific configuration

Basis compression can be configured to produce better quality or reduce encoding time. Configuration options are equivalent to options of the basisu tool. The full form of the configuration is shown below:

[configuration]
# All following options correspond to options of the basisu tool, grouped in
# the same way. Names follow the Basis C++ API and may differ from what the
# tool exposes.

# Options
quality_level=128
# sRGB images should have this enabled, turn this flag off for linear images
perceptual=true
debug=false
debug_images=false
compute_stats=false
compression_level=1

# More options
max_endpoint_clusters=512
max_selector_clusters=512
y_flip=true
# The `normal_map` setting is just an alias disabling `perceptual` and
# `mip_srgb` and enabling `no_selector_rdo` & `no_endpoint_rdo`
check_for_alpha=true
force_alpha=false
separate_rg_to_color_alpha=false
# Number of threads Basis should use during compression, 0 sets it to the
# value returned by std::thread::hardware_concurrency(), 1 disables
# multithreading. This value is clamped to std::thread::hardware_concurrency()
# internally by Basis itself.
threads=1
disable_hierarchical_endpoint_codebooks=false

# Mipmap generation options
mip_gen=false
# Generate mipmaps assuming sRGB input, turn this flag off for linear images
mip_srgb=true
mip_scale=1.0
mip_filter=kaiser
mip_renormalize=false
mip_wrapping=true
mip_smallest_dimension=1

# Backend endpoint/selector RDO codec options
no_selector_rdo=false
selector_rdo_threshold=1.25
no_endpoint_rdo=false
endpoint_rdo_threshold=1.5

# Hierarchical virtual selector codebook options
global_selector_palette=false
auto_global_selector_palette=false
no_hybrid_selector_codebook=false
global_palette_bits=8
global_modifier_bits=8
hybrid_selector_codebook_quality_threshold=2.0

# Set various fields in the Basis file header
userdata0=0
userdata1=0

Loading the plugin fails undefined symbol: pthread_create

On Linux it may happen that loading the plugin will fail with undefined symbol: pthread_create. The Basis encoder is optionally multithreaded and while linking the dynamic plugin library to pthread would resolve this particular error, the actual thread creation (if the threads= option is set to something else than 1) later would crash on a null function pointer call. Unfortunately there's no way to detect this case at runtime and fail gracefully, so instead the plugin requires the application to link to pthread instead. With CMake it can be done like this:

find_package(Threads REQUIRED)
target_link_libraries(your-application PRIVATE Threads::Threads)

Base classes

class AbstractImageConverter
Base for image converter plugins.

Constructors, destructors, conversion operators

BasisImageConverter() explicit
Default constructor.
BasisImageConverter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.