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.
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
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.
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::
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::
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. 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 can't be imported.
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.