Magnum::Trade::KtxImageConverter class new in Git master
#include <MagnumPlugins/KtxImageConverter/KtxImageConverter.h>

KTX2 image converter plugin.

Creates Khronos Texture 2.0 (*.ktx2) files from 1D, 2D and 3D images with optional mip levels. You can use KtxImporter to import images in this format.

Usage

This plugin depends on the Trade library and is built if WITH_KTXIMAGECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "KtxImageConverter" via Corrade::PluginManager::Manager.

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

set(WITH_KTXIMAGECONVERTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

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

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

find_package(MagnumPlugins REQUIRED KtxImageConverter)

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

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

Behavior and limitations

Supported formats

The following formats can be written:

Image types

Cube map images can be written but there is currently no way to mark them properly in the metadata. Exported files will be 3D images with faces exposed as depth slices.

Array images will be written as images with one extra dimension for the array layers. For example, a 2x3 2D array image with 4 layers will result in a 3D image with size 2x3x4.

Multilevel images

All image types can be saved with multiple levels by using the list variants of convertToFile() / convertToData(). Largest level is expected to be first, with each following level having width, height and depth divided by two, rounded down. Incomplete mip chains are supported.

Due to the way non-trivial image types are handled, the level sizes are always expected to match the resulting image type. This means that array images with multiple levels can currently not be exported and produce a level size mismatch error.

Supercompression

Saving files with supercompression is not supported. You can however use BasisImageConverter to create Basis-supercompressed KTX2 files.

Plugin-specific configuration

It's possible to tune various metadata options through configuration(). See below for all options and their default values:

[configuration]
# Orientation string to save in the file header. This doesn't flip the input
# pixels, it only tells readers the orientation during import. Must be empty or
# a string of the form [rl][du][oi]:
#   r/l: right/left
#   d/u: down/up
#   # o/i: out of/into the screen
# Only subsets of rdi and ruo are recommended, other values may not be
# supported by all readers.
orientation=ruo

# Format swizzle string to save in the file header. This doesn't save swizzled
# data, it only tells readers the desired channel mapping during import. Must
# be empty or 4 characters long, valid characters are r,g,b,a,0,1.
swizzle=

# Name of the tool writing the image file, saved in the file header
writerName=Magnum KtxImageConverter

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

KtxImageConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.