DdsEncoder Class

Immutable settings for DDS (DirectDraw Surface) encoding: uncompressed or BC1 to BC7 textures, with their mipmaps.

public sealed class DdsEncoder : ImageEncoder

Remarks

Image.Save writes a 2D texture of one surface, and of its mipmaps with DdsEncoder.GenerateMipmaps. ImageCollection.Save writes the ImageCollectionKind.TextureSurfaces collections: cube maps, texture arrays and arrays of cube maps, whose entries say where they are (ImageCollectionEntry.TextureSurface), with the mipmap levels they hold or the ones DdsEncoder.GenerateMipmaps generates. Volume textures are not written.

Every loss beyond the block compression of the chosen DdsEncoder.Format needs a setting, checked before anything is written: a format of fewer bits than the pixels (an 8-bit format for 16-bit pixels) needs DdsEncoder.AllowBitDepthReduction, and a format that lacks a channel the pixels use needs DdsEncoder.AllowChannelReduction: alpha that is not opaque in a format without alpha, color in a one-channel format (R8, R16 and BC4 are read as gray), or blue other than 0 in a two-channel format (R8G8 and BC5 are read as red and green, with a blue of 0). Floating-point formats store linear light: the image must be labeled ColorTransferFunction.Linear (the default of floating-point images), unless ImageEncoder.MetadataHandling discards the label. Their values must be finite and, for BC6H, at most 65,504 (not negative for DdsTextureFormat.Bc6HUf16); the signed BC4 and BC5 formats store values in [-1, 1]. Other values are rejected with an UnsupportedImageFeatureException.

The _SRGB formats declare sRGB-encoded colors, and are read back labeled with the CICP description of sRGB; the other integer formats are read back untagged. An image labeled linear, or with another color description, can only be written with a metadata policy that discards the label. DDS stores no other metadata.

Inheritance
ImageEncoder DdsEncoder

Constructors

NameDescription
DdsEncoder()

DdsEncoder()

DdsEncoder.cs
public DdsEncoder()

No documentation is available.

Properties

NameDescription
AllowBitDepthReductionGets a value indicating whether pixels of more bits than DdsEncoder.TextureFormat stores (16-bit pixels in an 8-bit format, which BC1 to BC5 and BC7 are) are reduced to its precision. Defaults to false: such pixels are rejected.
AllowChannelReductionGets a value indicating whether the channels DdsEncoder.TextureFormat does not store are dropped. Defaults to false: a pixel whose alpha is not opaque in a format without alpha, whose colors are not gray in a one-channel format (which stores red), or whose blue is not 0 in a two-channel format, is rejected.
FormatGets the format produced by this encoder.
GenerateMipmapsGets a value indicating whether the full chain of mipmaps is generated, down to 1×1, from the full-size surface of each face or array element. Defaults to false: only the surfaces of the image or of the collection are written.
HeaderVersionGets the header written after DDS_HEADER. Defaults to DdsHeaderVersion.Automatic.
QualityGets how hard the block compressors search. Defaults to TextureCompressionQuality.Thorough.
TextureFormatGets the format of the surfaces, or null (the default) for the uncompressed format that stores the pixels without loss: DdsTextureFormat.R8G8B8A8Unorm for 8-bit pixels (the _SRGB form when the image has the CICP description of sRGB), DdsTextureFormat.R8Unorm or DdsTextureFormat.R16Unorm for gray pixels without alpha, DdsTextureFormat.R16G16B16A16Unorm for 16-bit pixels, and the floating-point formats of the same precision for floating-point pixels.

AllowBitDepthReduction

DdsEncoder.cs

Gets a value indicating whether pixels of more bits than DdsEncoder.TextureFormat stores (16-bit pixels in an 8-bit format, which BC1 to BC5 and BC7 are) are reduced to its precision. Defaults to false: such pixels are rejected.

public bool AllowBitDepthReduction { get; init; }

Property value

bool

AllowChannelReduction

DdsEncoder.cs

Gets a value indicating whether the channels DdsEncoder.TextureFormat does not store are dropped. Defaults to false: a pixel whose alpha is not opaque in a format without alpha, whose colors are not gray in a one-channel format (which stores red), or whose blue is not 0 in a two-channel format, is rejected.

public bool AllowChannelReduction { get; init; }

Property value

bool

Gets the format produced by this encoder.

public override ImageFormat Format { get; }

Property value

ImageFormat

GenerateMipmaps

DdsEncoder.cs

Gets a value indicating whether the full chain of mipmaps is generated, down to 1×1, from the full-size surface of each face or array element. Defaults to false: only the surfaces of the image or of the collection are written.

public bool GenerateMipmaps { get; init; }

Property value

bool

Remarks

Each level averages the texels of the previous one that it covers (a box filter, exact for odd sizes), weighted by their alpha, in linear light for sRGB-encoded colors. A collection that already holds mipmap levels cannot generate them.

HeaderVersion

DdsEncoder.cs

Gets the header written after DDS_HEADER. Defaults to DdsHeaderVersion.Automatic.

public DdsHeaderVersion HeaderVersion { get; init; }

Property value

DdsHeaderVersion

Exceptions

ArgumentOutOfRangeException
The value is not a defined DdsHeaderVersion.

Gets how hard the block compressors search. Defaults to TextureCompressionQuality.Thorough.

public TextureCompressionQuality Quality { get; init; }

Property value

TextureCompressionQuality

Exceptions

ArgumentOutOfRangeException
The value is not a defined TextureCompressionQuality.

TextureFormat

DdsEncoder.cs

Gets the format of the surfaces, or null (the default) for the uncompressed format that stores the pixels without loss: DdsTextureFormat.R8G8B8A8Unorm for 8-bit pixels (the _SRGB form when the image has the CICP description of sRGB), DdsTextureFormat.R8Unorm or DdsTextureFormat.R16Unorm for gray pixels without alpha, DdsTextureFormat.R16G16B16A16Unorm for 16-bit pixels, and the floating-point formats of the same precision for floating-point pixels.

public DdsTextureFormat? TextureFormat { get; init; }

Property value

DdsTextureFormat?

Exceptions

ArgumentOutOfRangeException
The value is not a defined DdsTextureFormat.