Magnum::Trade::AbstractImageConverter class

Base for image converter plugins.

Provides functionality for converting images between various internal formats or compressing them. See Loading and using plugins for more information and *ImageConverter classes in Trade namespace for available image converter plugins.

Data dependency

The instances returned from various functions by design have no dependency on the converter instance and neither on the dynamic plugin module. In other words, you don't need to keep the converter instance (or the plugin manager instance) around in order to have the *Data instances valid. Moreover, all returned Containers::Array instances and Containers::Array instances returned through ImageData are only allowed to have default deleters — this is to avoid potential dangling function pointer calls when destructing such instances after the plugin module has been unloaded.

Subclassing

The plugin needs to implement the doFeatures() function and one or more of doConvert(), doConvertToData() or doConvertToFile() functions based on what features are supported.

You don't need to do most of the redundant sanity checks, these things are checked by the implementation:

Derived classes

class AnyImageConverter
Any image converter plugin.
class BasisImageConverter new in 2019.10
Basis Universal image converter plugin.
class JpegImageConverter
JPEG image converter plugin.
class MiniExrImageConverter
OpenEXR image converter plugin using miniexr.
class OpenExrImageConverter new in Git master
OpenEXR image converter plugin.
class PngImageConverter
PNG image converter plugin.
class StbImageConverter
Image converter plugin using stb_image_write.
class TgaImageConverter
TGA image converter plugin.

Public types

using Feature = ImageConverterFeature deprecated in 2020.06
Features supported by an image converter.
using Features = ImageConverterFeatures deprecated in 2020.06
Features supported by an image converter.

Public static functions

static auto pluginInterface() -> std::string
Plugin interface.
static auto pluginSearchPaths() -> std::vector<std::string>
Plugin search paths.

Constructors, destructors, conversion operators

AbstractImageConverter() explicit
Default constructor.
AbstractImageConverter(PluginManager::Manager<AbstractImageConverter>& manager) explicit
Constructor with access to plugin manager.
AbstractImageConverter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.

Public functions

auto features() const -> ImageConverterFeatures
Features supported by this converter.
auto flags() const -> ImageConverterFlags new in 2020.06
Converter flags.
void setFlags(ImageConverterFlags flags) new in 2020.06
Set converter flags.
void addFlags(ImageConverterFlags flags) new in Git master
Add converter flags.
void clearFlags(ImageConverterFlags flags) new in Git master
Clear converter flags.
auto convert(const ImageView1D& image) -> Containers::Optional<ImageData1D> new in Git master
Convert a 1D image.
auto convert(const ImageView2D& image) -> Containers::Optional<ImageData2D> new in Git master
Convert a 2D image.
auto exportToImage(const ImageView2D& image) -> Containers::Optional<Image2D> deprecated in Git master
Convert a 2D image.
auto exportToCompressedImage(const ImageView2D& image) -> Containers::Optional<CompressedImage2D> deprecated in Git master
Convert a 2D image to compressed format.
auto convert(const ImageView3D& image) -> Containers::Optional<ImageData3D> new in Git master
Convert a 3D image.
auto convert(const CompressedImageView1D& image) -> Containers::Optional<ImageData1D> new in Git master
Convert a compressed 1D image.
auto convert(const CompressedImageView2D& image) -> Containers::Optional<ImageData2D> new in Git master
Convert a compressed 2D image.
auto convert(const CompressedImageView3D& image) -> Containers::Optional<ImageData3D> new in Git master
Convert a compressed 3D image.
auto convert(const ImageData1D& image) -> Containers::Optional<ImageData1D> new in Git master
Convert a 1D image data.
auto convert(const ImageData2D& image) -> Containers::Optional<ImageData2D> new in Git master
Convert a 2D image data.
auto convert(const ImageData3D& image) -> Containers::Optional<ImageData3D> new in Git master
Convert a 3D image data.
auto convertToData(const ImageView1D& image) -> Containers::Array<char> new in Git master
Convert a 1D image to a raw data.
auto convertToData(const ImageView2D& image) -> Containers::Array<char> new in Git master
Convert a 2D image to a raw data.
auto exportToData(const ImageView2D& image) -> Containers::Array<char> deprecated in Git master
Convert a 2D image to a raw data.
auto convertToData(const ImageView3D& image) -> Containers::Array<char> new in Git master
Convert a 3D image to a raw data.
auto convertToData(const CompressedImageView1D& image) -> Containers::Array<char> new in Git master
Convert a compressed 1D image to a raw data.
auto convertToData(const CompressedImageView2D& image) -> Containers::Array<char> new in Git master
Convert a compressed 2D image to a raw data.
auto exportToData(const CompressedImageView2D& image) -> Containers::Array<char> deprecated in Git master
Convert a compressed 2D image to a raw data.
auto convertToData(const CompressedImageView3D& image) -> Containers::Array<char> new in Git master
Convert a compressed 3D image to a raw data.
auto convertToData(const ImageData1D& image) -> Containers::Array<char> new in Git master
Convert a 1D image data to a raw data.
auto convertToData(const ImageData2D& image) -> Containers::Array<char> new in Git master
Convert a 2D image data to a raw data.
auto exportToData(const ImageData2D& image) -> Containers::Array<char> deprecated in Git master
Convert a 2D image data to a raw data.
auto convertToData(const ImageData3D& image) -> Containers::Array<char> new in Git master
Convert a 3D image data to a raw data.
auto convertToFile(const ImageView1D& image, Containers::StringView filename) -> bool new in Git master
Convert a 1D image to a file.
auto convertToFile(const ImageView2D& image, Containers::StringView filename) -> bool new in Git master
Convert a 2D image to a file.
auto exportToFile(const ImageView2D& image, const std::string& filename) -> bool deprecated in Git master
Convert a 2D image to a file.
auto convertToFile(const ImageView3D& image, Containers::StringView filename) -> bool new in Git master
Convert a 3D image to a file.
auto convertToFile(const CompressedImageView1D& image, Containers::StringView filename) -> bool new in Git master
Convert a compressed 1D image to a file.
auto convertToFile(const CompressedImageView2D& image, Containers::StringView filename) -> bool new in Git master
Convert a compressed 2D image to a file.
auto exportToFile(const CompressedImageView2D& image, const std::string& filename) -> bool deprecated in Git master
Convert a compressed 2D image to a file.
auto convertToFile(const CompressedImageView3D& image, Containers::StringView filename) -> bool new in Git master
Convert a compressed 3D image to a file.
auto convertToFile(const ImageData1D& image, Containers::StringView filename) -> bool new in Git master
Convert a 1D image data to a file.
auto convertToFile(const ImageData2D& image, Containers::StringView filename) -> bool new in Git master
Convert a 2D image data to a file.
auto exportToFile(const ImageData2D& image, const std::string& filename) -> bool deprecated in Git master
Convert a 2D image data to a file.
auto convertToFile(const ImageData3D& image, Containers::StringView filename) -> bool new in Git master
Convert a 3D image data to a file.

Private functions

auto doFeatures() const -> ImageConverterFeatures pure virtual
Implementation for features()
void doSetFlags(ImageConverterFlags flags) virtual new in 2020.06
Implementation for setFlags()
auto doConvert(const ImageView1D& image) -> Containers::Optional<ImageData1D> virtual new in Git master
Implementation for convert(const ImageView1D&)
auto doConvert(const ImageView2D& image) -> Containers::Optional<ImageData2D> virtual new in Git master
Implementation for convert(const ImageView2D&)
auto doConvert(const ImageView3D& image) -> Containers::Optional<ImageData3D> virtual new in Git master
Implementation for convert(const ImageView3D&)
auto doConvert(const CompressedImageView1D& image) -> Containers::Optional<ImageData1D> virtual new in Git master
Implementation for convert(const CompressedImageView1D&)
auto doConvert(const CompressedImageView2D& image) -> Containers::Optional<ImageData2D> virtual new in Git master
Implementation for convert(const CompressedImageView2D&)
auto doConvert(const CompressedImageView3D& image) -> Containers::Optional<ImageData3D> virtual new in Git master
Implementation for convert(const CompressedImageView3D&)
auto doConvertToData(const ImageView1D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const ImageView1D&)
auto doConvertToData(const ImageView2D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const ImageView2D&)
auto doConvertToData(const ImageView3D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const ImageView3D&)
auto doConvertToData(const CompressedImageView1D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const CompressedImageView1D&)
auto doConvertToData(const CompressedImageView2D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const CompressedImageView2D&)
auto doConvertToData(const CompressedImageView3D& image) -> Containers::Array<char> virtual new in Git master
Implementation for convertToData(const CompressedImageView3D&)
auto doConvertToFile(const ImageView1D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const ImageView1D&, Containers::StringView)
auto doConvertToFile(const ImageView2D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const ImageView2D&, Containers::StringView)
auto doConvertToFile(const ImageView3D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const ImageView3D&, Containers::StringView)
auto doConvertToFile(const CompressedImageView1D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const CompressedImageView1D&, Containers::StringView)
auto doConvertToFile(const CompressedImageView2D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const CompressedImageView2D&, Containers::StringView)
auto doConvertToFile(const CompressedImageView3D& image, Containers::StringView filename) -> bool virtual new in Git master
Implementation for convertToFile(const CompressedImageView3D&, Containers::StringView)

Typedef documentation

typedef ImageConverterFeature Magnum::Trade::AbstractImageConverter::Feature

Features supported by an image converter.

typedef ImageConverterFeatures Magnum::Trade::AbstractImageConverter::Features

Features supported by an image converter.

Function documentation

static std::string Magnum::Trade::AbstractImageConverter::pluginInterface()

Plugin interface.

"cz.mosra.magnum.Trade.AbstractImageConverter/0.3"

static std::vector<std::string> Magnum::Trade::AbstractImageConverter::pluginSearchPaths()

Plugin search paths.

Looks into magnum/imageconverters/ or magnum-d/imageconverters/ next to the dynamic Trade library, next to the executable and elsewhere according to the rules documented in Corrade::PluginManager::implicitPluginSearchPaths(). The search directory can be also hardcoded using the MAGNUM_PLUGINS_DIR CMake variables, see Downloading and building for more information.

Not defined on platforms without dynamic plugin support.

void Magnum::Trade::AbstractImageConverter::setFlags(ImageConverterFlags flags) new in 2020.06

Set converter flags.

Some flags can be set only if the converter supports particular features, see documentation of each ImageConverterFlag for more information. By default no flags are set. To avoid clearing potential future default flags by accident, prefer to use addFlags() and clearFlags() instead.

Corresponds to the -v / --verbose option in magnum-imageconverter.

void Magnum::Trade::AbstractImageConverter::addFlags(ImageConverterFlags flags) new in Git master

Add converter flags.

Calls setFlags() with the existing flags ORed with flags. Useful for preserving the defaults.

void Magnum::Trade::AbstractImageConverter::clearFlags(ImageConverterFlags flags) new in Git master

Clear converter flags.

Calls setFlags() with the existing flags ANDed with inverse of flags. Useful for removing default flags.

Containers::Optional<ImageData1D> Magnum::Trade::AbstractImageConverter::convert(const ImageView1D& image) new in Git master

Convert a 1D image.

Available only if ImageConverterFeature::Convert1D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<ImageData2D> Magnum::Trade::AbstractImageConverter::convert(const ImageView2D& image) new in Git master

Convert a 2D image.

Available only if ImageConverterFeature::Convert2D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<Image2D> Magnum::Trade::AbstractImageConverter::exportToImage(const ImageView2D& image)

Convert a 2D image.

Containers::Optional<CompressedImage2D> Magnum::Trade::AbstractImageConverter::exportToCompressedImage(const ImageView2D& image)

Convert a 2D image to compressed format.

Containers::Optional<ImageData3D> Magnum::Trade::AbstractImageConverter::convert(const ImageView3D& image) new in Git master

Convert a 3D image.

Available only if ImageConverterFeature::Convert3D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<ImageData1D> Magnum::Trade::AbstractImageConverter::convert(const CompressedImageView1D& image) new in Git master

Convert a compressed 1D image.

Available only if ImageConverterFeature::ConvertCompressed1D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<ImageData2D> Magnum::Trade::AbstractImageConverter::convert(const CompressedImageView2D& image) new in Git master

Convert a compressed 2D image.

Available only if ImageConverterFeature::ConvertCompressed2D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<ImageData3D> Magnum::Trade::AbstractImageConverter::convert(const CompressedImageView3D& image) new in Git master

Convert a compressed 3D image.

Available only if ImageConverterFeature::ConvertCompressed3D is supported. Returns converted image on success, Containers::NullOpt otherwise. The implementation is allowed to return both a compressed an an uncompressed image, see documentation of a particular converter for more information.

Containers::Optional<ImageData1D> Magnum::Trade::AbstractImageConverter::convert(const ImageData1D& image) new in Git master

Convert a 1D image data.

Based on whether the image is compressed or not, calls either convert(const ImageView1D&) or convert(const CompressedImageView1D&). See documentation of these two functions for details.

Containers::Optional<ImageData2D> Magnum::Trade::AbstractImageConverter::convert(const ImageData2D& image) new in Git master

Convert a 2D image data.

Based on whether the image is compressed or not, calls either convert(const ImageView2D&) or convert(const CompressedImageView2D&). See documentation of these two functions for details.

Containers::Optional<ImageData3D> Magnum::Trade::AbstractImageConverter::convert(const ImageData3D& image) new in Git master

Convert a 3D image data.

Based on whether the image is compressed or not, calls either convert(const ImageView3D&) or convert(const CompressedImageView3D&). See documentation of these two functions for details.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageView1D& image) new in Git master

Convert a 1D image to a raw data.

Available only if ImageConverterFeature::Convert1DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageView2D& image) new in Git master

Convert a 2D image to a raw data.

Available only if ImageConverterFeature::Convert2DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::exportToData(const ImageView2D& image)

Convert a 2D image to a raw data.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageView3D& image) new in Git master

Convert a 3D image to a raw data.

Available only if ImageConverterFeature::Convert3DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const CompressedImageView1D& image) new in Git master

Convert a compressed 1D image to a raw data.

Available only if ImageConverterFeature::ConvertCompressed1DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const CompressedImageView2D& image) new in Git master

Convert a compressed 2D image to a raw data.

Available only if ImageConverterFeature::ConvertCompressed2DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::exportToData(const CompressedImageView2D& image)

Convert a compressed 2D image to a raw data.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const CompressedImageView3D& image) new in Git master

Convert a compressed 3D image to a raw data.

Available only if ImageConverterFeature::ConvertCompressed3DToData is supported. Returns data on success, nullptr otherwise.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageData1D& image) new in Git master

Convert a 1D image data to a raw data.

Based on whether the image is compressed or not, calls either convertToData(const ImageView1D&) or convertToData(const CompressedImageView1D&). See documentation of these two functions for details.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageData2D& image) new in Git master

Convert a 2D image data to a raw data.

Based on whether the image is compressed or not, calls either convertToData(const ImageView2D&) or convertToData(const CompressedImageView2D&). See documentation of these two functions for details.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::exportToData(const ImageData2D& image)

Convert a 2D image data to a raw data.

Containers::Array<char> Magnum::Trade::AbstractImageConverter::convertToData(const ImageData3D& image) new in Git master

Convert a 3D image data to a raw data.

Based on whether the image is compressed or not, calls either convertToData(const ImageView3D&) or convertToData(const CompressedImageView3D&). See documentation of these two functions for details.

bool Magnum::Trade::AbstractImageConverter::exportToFile(const ImageView2D& image, const std::string& filename)

Convert a 2D image to a file.

bool Magnum::Trade::AbstractImageConverter::exportToFile(const CompressedImageView2D& image, const std::string& filename)

Convert a compressed 2D image to a file.

bool Magnum::Trade::AbstractImageConverter::convertToFile(const ImageData1D& image, Containers::StringView filename) new in Git master

Convert a 1D image data to a file.

Based on whether the image is compressed or not, calls either convertToFile(const ImageView1D&, Containers::StringView) or convertToFile(const CompressedImageView1D&, Containers::StringView). See documentation of these two functions for details.

bool Magnum::Trade::AbstractImageConverter::convertToFile(const ImageData2D& image, Containers::StringView filename) new in Git master

Convert a 2D image data to a file.

Based on whether the image is compressed or not, calls either convertToFile(const ImageView2D&, Containers::StringView) or convertToFile(const CompressedImageView2D&, Containers::StringView). See documentation of these two functions for details.

bool Magnum::Trade::AbstractImageConverter::exportToFile(const ImageData2D& image, const std::string& filename)

Convert a 2D image data to a file.

bool Magnum::Trade::AbstractImageConverter::convertToFile(const ImageData3D& image, Containers::StringView filename) new in Git master

Convert a 3D image data to a file.

Based on whether the image is compressed or not, calls either convertToFile(const ImageView3D&, Containers::StringView) or convertToFile(const CompressedImageView3D&, Containers::StringView). See documentation of these two functions for details.

void Magnum::Trade::AbstractImageConverter::doSetFlags(ImageConverterFlags flags) virtual private new in 2020.06

Implementation for setFlags()

Useful when the converter needs to modify some internal state on flag setup. Default implementation does nothing and this function doesn't need to be implemented — the flags are available through flags().

To reduce the amount of error checking on user side, this function isn't expected to fail — if a flag combination is invalid / unsuported, error reporting should be delayed to various conversion functions, where the user is expected to do error handling anyway.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const ImageView1D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const ImageView1D&, Containers::StringView)

If ImageConverterFeature::Convert1DToData is supported, default implementation calls doConvertToData(const ImageView1D&) and saves the result to given file.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const ImageView2D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const ImageView2D&, Containers::StringView)

If ImageConverterFeature::Convert2DToData is supported, default implementation calls doConvertToData(const ImageView2D&) and saves the result to given file.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const ImageView3D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const ImageView3D&, Containers::StringView)

If ImageConverterFeature::Convert3DToData is supported, default implementation calls doConvertToData(const ImageView3D&) and saves the result to given file.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const CompressedImageView1D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const CompressedImageView1D&, Containers::StringView)

If ImageConverterFeature::ConvertCompressed1DToData is supported, default implementation calls doConvertToData(const CompressedImageView1D&) and saves the result to given file.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const CompressedImageView2D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const CompressedImageView2D&, Containers::StringView)

If ImageConverterFeature::ConvertCompressed2DToData is supported, default implementation calls doConvertToData(const CompressedImageView2D&) and saves the result to given file.

bool Magnum::Trade::AbstractImageConverter::doConvertToFile(const CompressedImageView3D& image, Containers::StringView filename) virtual private new in Git master

Implementation for convertToFile(const CompressedImageView3D&, Containers::StringView)

If ImageConverterFeature::ConvertCompressed3DToData is supported, default implementation calls doConvertToData(const CompressedImageView3D&) and saves the result to given file.