Magnum::Trade::DdsImporter class
#include <MagnumPlugins/DdsImporter/DdsImporter.h>

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

Imported image orientation

Unlike KTX or Basis, the file format doesn't contain any orientation metadata, and so it's assumed to follow the Vulkan/D3D coordinate system with Y down and (for 3D textures) Z forward. Uncompressed images will be flipped on import to Y up and (for 3D textures) Z backward.

Y-flipping block-compressed data is nontrivial and so far is implemented only for BC1, BC2, BC3, BC4 and BC5 formats with APIs from Magnum/Math/ColorBatch.h. Other compressed formats will print a message to Warning and the data will not be flipped. A warning also gets printed in case the flip is performed on an image whose height isn't whole blocks, as that causes the data to be shifted.

Set the assumeYUpZBackward configuration option to assume the OpenGL coordinate system and perform no flipping.

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:

Uncompressed RGB, RGBA / RGBX, BGR, BGRA / BGRX, R are imported as PixelFormat::RGB8Unorm, RGBA8Unorm or R8Unorm, with component swizzling as necessary. The X variant is not treated in any special way — alpha channel gets whatever data is there.
Compressed FourCC DXT1, DXT3, DXT5, ATI1 / BC4U, ATI2 / BC5U, BC4S and BC5S formats are imported as CompressedPixelFormat::Bc1RGBAUnorm, Bc2RGBAUnorm, Bc3RGBAUnorm, Bc4RUnorm, Bc5RGUnorm, Bc4RSnorm and Bc5RGSnorm respectively
Legacy FourCC formats 36, 110, 111, 112, 113, 114, 115 and 116 formats are imported as PixelFormat::RGBA16Unorm, RGBA16Snorm, R16F, RG16F, RGBA16F, R32F, RG32F and RGBA32F 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_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:

DXGI_FORMAT_A8_UNORM is imported as PixelFormat::R8Unorm
DXGI_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 X variant not being treated in any special way — alpha channel gets whatever data is there
DXGI_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
DXGI_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 *_TYPELESS formats are treated the same way as their *_UNORM alternatives
DXGI_FORMAT_BC6H_TYPELESS is treated the same way as DXGI_FORMAT_BC6H_UF16, thus CompressedPixelFormat::Bc6hRGBUfloat
All other uncompressed *_TYPELESS formats are treated the same way as the *_UI alternatives

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.

Magnum::Trade::DdsImporter class #include <MagnumPlugins/DdsImporter/DdsImporter.h>

Magnum::Trade::DdsImporter class
#include <MagnumPlugins/DdsImporter/DdsImporter.h>