Magnum::Trade::DdsImporter class

DDS image importer plugin.

Imports DirectDraw Surface images (*.dds).

Usage

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::PluginManager::Manager.

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 MagnumPlugins::DdsImporter target:

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::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 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::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().

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.

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. 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:

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_FORMAT are supported for DDS files with the DXT10 header (DX10 FourCC). The mapping is documented in PixelFormat and CompressedPixelFormat (searching for the DXGI format names works as well), with the following special cases:

Additionally, nonstandard 2D ASTC DXGI_FORMAT_ASTC_4x4_TYPELESS, DXGI_FORMAT_ASTC_4x4_UNORM, DXGI_FORMAT_ASTC_4x4_UNORM_SRGB formats including other sizes up to 12x12 are supported, mapping to CompressedPixelFormat::Astc4x4RGBAUnorm, Astc4x4RGBASrgb and following variants. A subset of those is used by NVidia Texture Tools Exporter, historically the ASTC formats were meant to be included in Direct3D 11.3 but were later pulled. While there are reserved enum values for float variants of these formats as well, no tool is known to produce them. 3D ASTC formats have no known mapping.

Packed formats, (planar) YUV / YCbCr video formats, DXGI_FORMAT_R1_UNORM and R10G10B10_XR_BIAS_A2_UNORM are not supported.

Plugin-specific configuration

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. Images are then flipped on import to have Y up and Z
# backward, or a warning is printed in case it's not possible. Enable this
# option to assume the OpenGL coordinate system instead and attempt no
# flipping.
assumeYUpZBackward=false

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

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