Magnum::Trade::StbDxtImageConverter class new in Git master

#include <MagnumPlugins/StbDxtImageConverter/StbDxtImageConverter.h>

Usage

This plugin depends on the Trade library and is built if MAGNUM_WITH_STBDXTIMAGECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "StbDxtImageConverter" 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_STBDXTIMAGECONVERTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

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

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

find_package(MagnumPlugins REQUIRED StbDxtImageConverter)

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

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

Behavior and limitations

An PixelFormat::RGBA8Unorm / RGBA8Srgb input will produce a compressed ImageData2D with CompressedPixelFormat::Bc3RGBAUnorm / Bc3RGBASrgb. If the input is PixelFormat::RGB8Unorm / RGBA8Srgb, an image with CompressedPixelFormat::Bc1RGBUnorm / Bc1RGBSrgb is returned instead. You can override alpha channel presence in the output by explicitly enabling or disabling the alpha configuration option.

Image flags are passed through unchanged. 3D images are compressed slice-by-slice, independently of whether ImageFlag3D::Array and/or ImageFlag3D::CubeMap or neither is set. On the other hand, if a 2D image with ImageFlag2D::Array is passed, the conversion will fail as it's not possible to represent 1D array images without a significant loss in quality and layer cross-talk.

The input image size is expected to be divisible by four in the X and Y dimension. If your image doesn't fit this requirement, you have to pad/crop or resample it first. Since 3D images are compressed slice-by-slice, there's no restriction on the Z dimension.

Unlike image converters dealing with uncompressed pixel formats, the image isn't Y-flipped on export due to the nontrivial amount of work involved with Y-flipping block-compressed data. This is in line with importers of compressed pixel formats such as AstcImporter, DdsImporter or KtxImporter, which don't Y-flip compressed formats on import either.

Plugin-specific configuration

Various compressor options can be set through configuration(). See below for all options and their default values:

[configuration]
# Store the alpha channel. If enabled, the output format is BC3 (128 bits per
# block), if disabled the format is BC1 (64 bits per block). By default it's
# inferred from whether the input is RGB or RGBA.
alpha=

# High-quality mode, does two refinement steps instead of one. ~30–40%
# slower.
highQuality=false

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.

Constructors, destructors, conversion operators

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

Plugin manager constructor.