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

KTX2 image importer plugin.

Imports Khronos Texture 2.0 images (*.ktx2). You can use KtxImageConverter to encode images into this format.

Usage

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

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

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

find_package(MagnumPlugins REQUIRED KtxImporter)

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

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

Behavior and limitations

Imports images in the following formats:

  • KTX2 with all uncompressed Vulkan formats that have an equivalent in PixelFormat, with component swizzling as necessary
  • KTX2 with all compressed Vulkan formats that have an equivalent in CompressedPixelFormat. 3D ASTC formats are supported as well, even though they have no Vulkan equivalent yet.

The importer recognizes ImporterFlag::Verbose, printing additional info when the flag is enabled. ImporterFlag::Quiet is recognized as well and causes all import warnings to be suppressed.

Image types

All image types supported by KTX2 are imported, including 1D, 2D, cube maps, and 3D images. They can, in turn, all have multiple array layers as well as multiple mip levels. The images are annotated with ImageFlag2D::Array, ImageFlag3D::Array and ImageFlag3D::CubeMap as appropriate. Furthermore, for backward compatibility, if MAGNUM_BUILD_DEPRECATED is enabled, the image type can also be determined from texture() and TextureData::type().

For layered images and (layered) cube maps, the array layers and faces are exposed as an additional image dimension. 1D array textures import ImageData2D with n y-slices, 2D array textures import ImageData3D with n z-slices and (layered) cube maps import ImageData3D with 6*n z-slices. While for 1D, 1D array, 2D, 2D array, cube map and cube map array images the importer exposes always exactly one image, 3D array textures behave differently — because there is no ImageData4D, each layer is imported as a separate ImageData3D, with image3DCount() determining the number of layers.

Multilevel images

Files with multiple mip levels are imported with the largest level first, with the size of each following level divided by 2, rounded down. Mip chains can be incomplete, ie. they don't have to extend all the way down to a level of size 1x1.

Cube maps

Cube map faces are imported in the order +X, -X, +Y, -Y, +Z, -Z as seen from a left-handed coordinate system (+X is right, +Y is up, +Z is forward). Layered cube maps are stored as multiple sets of faces, ie. all faces +X through -Z for the first layer, then all faces of the second layer, etc.

Incomplete cube maps (determined by the KTXcubemapIncomplete metadata entry) are imported as a 2D array image, but information about which faces it contains isn't preserved.

Swizzle support

Explicit swizzling via the KTXswizzle header entry supports BGR and BGRA. Any other non-identity channel remapping is unsupported and results in an error.

For reasons similar to the restriction on axis-flips, compressed formats don't support any swizzling, and the import fails if an image with a compressed format contains a swizzle that isn't RGBA.

Basis Universal compression

When the importer detects a Basis Universal compressed file, it will forward the file to the BasisImporter plugin, if available. Flags set via setFlags() and options in the [basis] section of the plugin configuration are propagated to BasisImporter.

Calls to the image1DCount() / image2DCount() / image3DCount(), image1DLevelCount() / image2DLevelCount() / image3DLevelCount(), image1D() / image2D() / image3D() and textureCount() / texture() functions are then proxied to BasisImporter. The close() function closes and discards the internally instantiated plugin; isOpened() works as usual.

Supercompression

Importing files with supercompression is not supported. When forwarding Basis Universal compressed files, some supercompression schemes like BasisLZ and Zstandard can be handled by BasisImporter.

Plugin-specific configuration

For some formats, it's possible to tune various options through configuration(). See below for all options and their default values; a subset of the option is the same as in BasisImporter:

[configuration]
# Assume file orientation. Must be a string of the form [rl][du][oi]:
#   r/l: right/left
#   d/u: down/up
#   o/i: out of/into the screen
# If empty, orientation metadata from the file header (or the default rdi, if
# not present) is used. The orientation is then used to flip pixels to match
# the ruo orientation used by Magnum.
assumeOrientation=

# Options for Basis-encoded KTX files. Passed verbatim to BasisImporter, see
# its documentation for more information.
[configuration/basis]
format=

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

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

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