class
StbImageConverterImage converter plugin using stb_image_write.
Creates Windows Bitmap (*.bmp
), Radiance HDR (*.hdr
), JPEG (*.jpg
, *.jpe
, *.jpeg
), Portable Network Graphics (*.png
) or Truevision TGA (*.tga
, *.vda
, *.icb
, *.vst
) files using the stb_
This plugin provides StbBmpImageConverter
, StbHdrImageConverter
, StbJpegImageConverter
, StbPngImageConverter
and StbTgaImageConverter
aliases as well as also BmpImageConverter
, HdrImageConverter
, JpegImageConverter
, PngImageConverter
and TgaImageConverter
Usage
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::"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:
set(MAGNUM_WITH_STBIMAGECONVERTER ON CACHE BOOL "" FORCE) 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
Supports the following input and output format combinations:
- Windows Bitmap (
*.bmp
) if the plugin was loaded asStbBmpImageConverter
/BmpImageConverter
, if convertToFile() was called with the corresponding extension or if Format::Bmp was passed to the constructor. Accepts PixelFormat:: R8Unorm, PixelFormat:: RG8Unorm, PixelFormat:: RGB8Unorm and PixelFormat:: RGBA8Unorm. Single- and two-channel inputs are converted to three-channel with the the first channel repeated three times (and second ignored), four-channel input loses alpha. - Radiance HDR (
*.hdr
) if the plugin was loaded asStbHdrImageConverter
/HdrImageConverter
, if convertToFile() was called with the corresponding extension or if Format::Hdr was passed to the constructor. Accepts PixelFormat:: R32F, PixelFormat:: RG32F, PixelFormat:: RGB32F or PixelFormat:: RGBA32F. R and RG inputs are converted to three-channel RRR with G ignored, four-channel input loses alpha. - JPEG (
*.jpg
,*.jpe
,*.jpeg
) if the plugin was loaded asStbJpegImageConverter
/JpegImageConverter
, if convertToFile() was called with one of the corresponding extensions or if Format::Jpeg was passed to the constructor. Accepts PixelFormat:: R8Unorm, PixelFormat:: RG8Unorm, PixelFormat:: RGB8Unorm and PixelFormat:: RGBA8Unorm. Single- and two-channel inputs are converted to three-channel with the first channel repeated three times (and second ignored), four-channel input loses alpha. - Portable Network Graphics (
*.png
) if the plugin was loaded asStbPngImageConverter
/PngImageConverter
, if convertToFile() was called with the corresponding extension or if Format::Png was passed to the constructor. Accepts PixelFormat:: R8Unorm, PixelFormat:: RG8Unorm, PixelFormat:: RGB8Unorm and PixelFormat:: RGBA8Unorm, output has the same amount of channels as input. - Truevision TGA (
*.tga
,*.vda
,*.icb
,*.vst
) if the plugin was loaded asStbTgaImageConverter
/TgaImageConverter
, if convertToFile() was called with one of the corresponding extensions or if Format::Tga was passed to the constructor. Accepts PixelFormat:: R8Unorm, PixelFormat:: RG8Unorm, PixelFormat:: RGB8Unorm and PixelFormat:: RGBA8Unorm, output has the same amount of channels as input.
While the plugin provides generic aliases such as PngImageConverter
, it may generate slightly larger files and the performance might be worse than when using plugins dedicated for given format such as PngImageConverter.
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.
None of the formats supported by this plugin have any way to distinguish between 2D and 1D array images. If an image has ImageFlag2D::
Depending on the alias under which the plugin was loaded or the Format passed to constructor, extension() is one of "bmp"
, "hdr"
, "jpg"
, "png"
or "tga"
, picking always the most common for each format; the mimeType() is one of "image/bmp"
, "image/vnd.radiance"
, "image/jpeg"
, "image/png"
or "image/x-tga"
. Returned values are consistent with what JpegImageConverter, PngImageConverter and TgaImageConverter use, see their documentation for more information. If the plugin is loaded as StbImageConverter
or no format is passed to the constructor, both extension() and mimeType() return an empty string. The returned values are also independent of what file extension is used in a call to convertToFile().
The plugin recognizes ImageConverterFlag::
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.
RLE encoding of TGA files
TGA files produced by TgaImageConverter are often slightly smaller than files produced by stb_image_write
. Same case is for TGA files produced by ImageMagick and -compress RunLengthEncoded
, they're slightly different than files produced by stb_image_write
but also larger. The cause is currently unknown, could be some unhandled optimization corner case in both libraries.
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] # Compression quality for JPEG output (0 - 1, 1 is the best). Corresponds to # the same option in JpegImageConverter. jpegQuality=0.8
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
Constructors, destructors, conversion operators
- StbImageConverter(Format format) explicit
- Default constructor.
-
StbImageConverter(PluginManager::
AbstractManager& manager, const Containers:: StringView& plugin) explicit - Plugin manager constructor.
Enum documentation
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.