Magnum::Trade::StbImageConverter class

Image converter plugin using stb_image_write.

Creates files in one of the following formats using the stb_image_write library:

If the conversion results in lost channels (such as saving RGBA to a JPEG, losing the alpha in process), a warning is printed to the output.

Besides StbBmpImageConverter, StbHdrImageConverter, StbJpegImageConverter, StbPngImageConverter and StbTgaImageConverter aliases this plugin provides also BmpImageConverter, HdrImageConverter, JpegImageConverter, PngImageConverter and TgaImageConverter plugins, but note that this plugin may generate slightly larger files and the performance might be worse than when using plugins dedicated for given format.


This plugin depends on the Trade library and is built if MAGNUM_WITH_STBIMAGECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load one of the "StbBmpImageConverter", "StbHdrImageConverter", "StbPngImageConverter", "StbTgaImageConverter" plugins via Corrade::PluginManager::Manager. If you would load the plugin as just "StbImageConverter", it won't be able to guess the desired output format.

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

add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

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

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

find_package(MagnumPlugins REQUIRED StbImageConverter)

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

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

Behavior and limitations

None of the formats supported by this plugin have any way to distinguish between 2D and 1D array images. If an image has ImageFlag2D::Array set, a warning is printed and the file is saved as a regular 2D image.

Arithmetic JPEG encoding

Arithmetic coding is implemented neither in stb_image_write nor in stb_image.

16-bit PNGs

Conversion to 16-bit PNGs is not supported. Use PngImageConverter instead if you need to deal with 16-bit pixel formats.

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:


# Compression quality for JPEG output (0 - 1, 1 is the best). Corresponds to
# the same option in JpegImageConverter.

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

Base classes

class AbstractImageConverter
Base for image converter plugins.

Public types

enum class Format: Int { Bmp = 1, Jpeg, Hdr, Png, Tga }
Output file format.

Constructors, destructors, conversion operators

StbImageConverter(Format format) explicit
Default constructor.
StbImageConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.

Enum documentation

enum class Magnum::Trade::StbImageConverter::Format: Int

Output file format.


Output BMP images


Output JPEG images


Output HDR images


Output PNG images


Output TGA images

Function documentation

Magnum::Trade::StbImageConverter::StbImageConverter(Format format) explicit

Default constructor.

The converter outputs files in format defined by Format.

Magnum::Trade::StbImageConverter::StbImageConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit

Plugin manager constructor.

Outputs files in format based on which alias was used to load the plugin.