Magnum::Trade::StbImageImporter class
#include <MagnumPlugins/StbImageImporter/StbImageImporter.h>

Image importer plugin using stb_image.

Imports the following formats using the stb_image library:

  • Windows Bitmap (*.bmp), details
  • Graphics Interchange Format (*.gif) including animations, details
  • Radiance HDR (*.hdr)
  • JPEG (*.jpg, *.jpe, *.jpeg), details
  • Portable Graymap (*.pgm)
  • Softimage PIC (*.pic)
  • Portable Network Graphics (*.png), details
  • Portable Pixmap (*.ppm)
  • Adobe Photoshop (*.psd), details
  • Truevision TGA (*.tga, *.vda, *.icb, *.vst)

You can use StbImageConverter to encode images into a subset of the above formats.

This plugin provides the BmpImporter, GifImporter, HdrImporter, JpegImporter, PgmImporter, PicImporter, PngImporter, PpmImporter, PsdImporter and TgaImporter plugins, but note that this plugin doesn't have complete support for all format quirks and the performance might be worse than when using a plugin dedicated for given format.

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.

BMP support

1bpp and RLE files are not supported.

Animated GIFs

In case the file is an animated GIF, the importer will report frame count in image2DCount() and you can then import each frame separately. Additionally, for the lack of better APIs at the moment, frame delays are exposed through importerState() as an array of Int, where each entry is number of milliseconds to wait before advancing to the next frame. Example usage:

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]);
}

Note that the support for GIF transitions is currently incomplete, see nothings/stb#683 for details.

Arithmetic JPEG decoding

Arithmetic coding is not implemented in stb_image, use JpegImporter together with libjpeg-turbo or mozjpeg instead.

PNG files

Both 8- and 16-bit images are supported, lower bit counts and paletted images are expanded to 8-bit.

CgBI is a proprietary Apple-specific extension to PNG (details here). The importer detects those files and converts BGRA channels back to RGBA.

PSD files

Both 8- and 16-bit images are supported. Only the composited view, there's no way to import individual layers.

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() deprecated in Git master explicit
Default constructor.
StbImageImporter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.

Function documentation

Magnum::Trade::StbImageImporter::StbImageImporter() explicit

Default constructor.