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

KTX2 image importer plugin.

Supports 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 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(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 most compressed Vulkan formats that have an equivalent in CompressedPixelFormat. None of the 3D ASTC formats are supported.

With compressed pixel formats, the image will not be flipped if the Y- or Z-axis orientation doesn't match the output orientation. The nontrivial amount of work involved with flipping block-compressed data makes this unfeasible. The import will succeed but a warning will be emitted.

The importer recognizes ImporterFlag::Verbose, printing additional info when the flag is enabled.

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 image type can 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, (layered) 2D textures and cube maps import ImageData3D with 6*n z-slices. 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 can't be imported.

Supercompression

Importing files with supercompression is not supported.

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.

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

KtxImporter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.