DDS image importer plugin.
Supports DirectDraw Surface images (
This plugin depends on the Trade library and is built if
MAGNUM_WITH_DDSIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load
"DdsImporter" via Corrade::
Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following:
set(MAGNUM_WITH_DDSIMPORTER ON CACHE BOOL "" FORCE) add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL) # So the dynamically loaded plugin gets built implicitly add_dependencies(your-app MagnumPlugins::DdsImporter)
To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake into your
modules/ directory, request the
DdsImporter component of the
MagnumPlugins package in CMake and link to the
find_package(MagnumPlugins REQUIRED DdsImporter) # ... target_link_libraries(your-app PRIVATE MagnumPlugins::DdsImporter)
See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.
Behavior and limitations
The importer recognizes ImporterFlag::
All image types supported by DDS are imported, including 1D, 1D array, 2D, 2D array, cube maps, cube map arrays and 3D images. They can, in turn, all have multiple mip levels. The images are annotated with ImageFlag2D::
The importer exposes always exactly one image. 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.
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. 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, which are possible in legacy DDS files without the DXT10 header, are imported as a 2D array image, but information about which faces it contains isn't preserved.
Legacy DDS format support
The following formats are supported for legacy DDS files without the DXT10 header:
- Uncompressed RGB, RGBA / RGBX, BGR, BGRA / BGRX, R are imported as PixelFormat::
RGB8Unorm, PixelFormat:: RGBA8Unorm or PixelFormat:: R8Unorm, with component swizzling as necessary. The
Xvariant is not treated in any special way — alpha channel gets whatever data is there.
- Compressed FourCC
BC5Sformats are imported as CompressedPixelFormat::
Bc1RGBAUnorm, Bc2RGBAUnorm, Bc3RGBAUnorm, Bc4RUnorm, Bc5RGUnorm, Bc4RSnorm and Bc5RGSnorm respectively
While the legacy header support arbitrary other swizzles, anything except BGR and BGRA will fail to import. Other FourCC codes except the ones listed above are not supported.
DXT10 format support
Formats that correspond to the DXGI_
DX10 FourCC). The mapping is documented in PixelFormat and CompressedPixelFormat (searching for the DXGI format names works as well), with the following special cases:
FORMAT_ A8_ UNORM is imported as PixelFormat:: R8Unorm
FORMAT_ B8G8R8A8_ UNORM / DXGI_ FORMAT_ B8G8R8X8_ UNORM and DXGI_ FORMAT_ B8G8R8A8_ UNORM_ SRGB / DXGI_ FORMAT_ B8G8R8X8_ UNORM_ SRGB is imported as PixelFormat:: RGBA8Unorm and PixelFormat:: RGBA8Srgb with component swizlling, the
Xvariant not being treated in any special way — alpha channel gets whatever data is there
FORMAT_ R32G8X24_ TYPELESS, DXGI_ FORMAT_ R32_ FLOAT_ X8X24_ TYPELESS and DXGI_ FORMAT_ R32_ FLOAT_ X8X24_ TYPELESS are all treated the same way as DXGI_ FORMAT_ D32_ FLOAT_ S8X24_ UINT, thus PixelFormat:: Depth32FStencil8UI
FORMAT_ R24G8_ TYPELESS, DXGI_ FORMAT_ R24_ UNORM_ X8_ TYPELESS and DXGI_ FORMAT_ X24_ TYPELESS_ G8_ UINT are all treated the same way as DXGI_ FORMAT_ D24_ UNORM_ S8_ UINT, thus PixelFormat:: Depth24UnormStencil8UI
- BC1 – BC5 and BC7
*_TYPELESSformats are treated the same way as their
FORMAT_ BC6H_ TYPELESS is treated the same way as DXGI_ FORMAT_ BC6H_ UF16, thus CompressedPixelFormat:: Bc6hRGBUfloat
- All other uncompressed
*_TYPELESSformats are treated the same way as the
Additionally, nonstandard 2D ASTC
DXGI_FORMAT_ASTC_4x4_UNORM_SRGB formats including other sizes up to 12x12 are supported, mapping to CompressedPixelFormat::
Packed formats, (planar) YUV / YCbCr video formats, DXGI_
It's possible to tune various import options through configuration(). See below for all options and their default values:
[configuration] # As the DDS file format doesn't contain any orientation metadata, it's # assumed to follow the D3D/Vulkan coordinate system, with Y down and (for 3D # textures) Z forward. Uncompressed files are then flipped on import to have # Y up and Z backward, a warning is printed for compressed pixel formats. # Enable this option to assume the OpenGL coordinate system instead, perform # no flipping of uncompressed data and silence the warning for compressed # data. assumeYUpZBackward=false
See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.
- class AbstractImporter
- Base for importer plugins.
Constructors, destructors, conversion operators
AbstractManager& manager, const Containers:: StringView& plugin) explicit
- Plugin manager constructor.