class new in Git masterKtxImporter
KTX2 image importer plugin.
Supports Khronos Texture 2.0 images (
*.ktx2). You can use KtxImageConverter to encode images into this format.
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::
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
find_package(MagnumPlugins REQUIRED KtxImporter) # ... target_link_libraries(your-app PRIVATE MagnumPlugins::KtxImporter)
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.
The importer recognizes ImporterFlag::
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::
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.
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 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.
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.
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.
[configuration] # 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.
- class AbstractImporter
- Base for importer plugins.