Magnum::Trade::StbImageImporter class

#include <MagnumPlugins/StbImageImporter/StbImageImporter.h>

Usage

This plugin depends on the Trade library and is built if MAGNUM_WITH_STBIMAGEIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "StbImageImporter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following:

set(MAGNUM_WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::StbImageImporter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake into your modules/ directory, request the StbImageImporter component of the MagnumPlugins package and link to the MagnumPlugins::StbImageImporter target:

find_package(MagnumPlugins REQUIRED StbImageImporter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::StbImageImporter)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.

Behavior and limitations

LDR images are imported as PixelFormat::RGB8Unorm / PixelFormat::RGB16Unorm, PixelFormat::RGBA8Unorm / PixelFormat::RGBA16Unorm, PixelFormat::R8Unorm / PixelFormat::R16Unorm for grayscale or PixelFormat::RG8Unorm / PixelFormat::RG16Unorm for grayscale + alpha, HDR images as PixelFormat::RGB32F, PixelFormat::RGBA32F, PixelFormat::R32F or PixelFormat::RG32F. Paletted images are automatically converted to RGB(A). Certain formats support only some channel counts (for example Radiance HDR can only be three-component), however it's possible to override the desired channel count using the forceChannelCount configuration option. The forceBitDepth option makes it possible to convert the images to a different bit depth.

Images are imported with default PixelStorage parameters except for alignment, which may be changed to 1 if the data require it.

The importer is thread-safe if Corrade and Magnum is compiled with CORRADE_BUILD_MULTITHREADED enabled. The importer recognizes ImporterFlag::Verbose, printing additional info when the flag is enabled.

if(!importer->importerState())
    Fatal{} << "Not an animated GIF.";

Containers::ArrayView<const Int> frameDelays{
    reinterpret_cast<const Int*>(importer->importerState()),
    importer->image2DCount()};

for(UnsignedInt i = 0; i != importer->image2DCount(); ++i) {
    // display the image ...

    Utility::System::sleep(frameDelays[i]);
}

Plugin-specific configuration

For some formats, it's possible to tune various output options through configuration(). See below for all options and their default values:

[configuration]
# Override image channel count. Allowed values are 0-4, with zero keeping the
# original channel count. If set to something different than the image has,
# stb_image does a rather complex conversion. The main rules are the
# following, for precise behavior please see the stb_image source:
#
# - for a two- and four-channel output, the last channel is treated as alpha,
#   and either copied from the source (if it's two-/four-channel) or set to
#   255 / 1.0f
# - reducing a three- or four-channel image to one or two channels will cause
#   the first channel to be filled with Y (luminance) of the RGB input, the
#   second channel is then alpha, filled according to the first rule
# - expanding a single- or two-channel image to three or four channels will
#   cause the first channel to be repeated three times and second channel
#   treated as alpha according to the first rule
forceChannelCount=0

# Override channel bit depth. Allowed values are 0, 8, 16 and 32, with zero
# keeping the original bit depth. Value of 32 imports the channels as 32-bit
# floating point values.
forceBitDepth=0

See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.

Base classes

class AbstractImporter

Base for importer plugins.

Constructors, destructors, conversion operators

StbImageImporter() explicit

Default constructor.

StbImageImporter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit

Plugin manager constructor.