Ktx2Encoder Class

Immutable settings for KTX 2.0 encoding: uncompressed, BCn, ETC2, EAC or ASTC textures, with their mip levels, optionally supercompressed with ZLIB.

public sealed class Ktx2Encoder : ImageEncoder

Remarks

Image.Save writes a 2D texture of one level, and its mip levels with Ktx2Encoder.GenerateMipmaps. ImageCollection.Save writes the ImageCollectionKind.TextureSurfaces collections: cube maps, array textures and arrays of cube maps, whose entries say where they are (ImageCollectionEntry.TextureSurface), with the mip levels they hold or the ones Ktx2Encoder.GenerateMipmaps generates. 3D textures and Basis Universal (ETC1S, UASTC) are not written.

Every loss beyond the block compression of the chosen Ktx2Encoder.TextureFormat needs a setting, checked before anything is written: a format of fewer bits than the pixels needs Ktx2Encoder.AllowBitDepthReduction (16-bit pixels in an 8-bit format, which BC1 to BC5, BC7, ETC2 and ASTC are, or in the 11 bits of EAC), and a format that lacks a channel the pixels use needs Ktx2Encoder.AllowChannelReduction: alpha that is not opaque in a format without alpha, color in a one-channel format (written with the swizzle rrr1, so that it is read as gray), or blue other than 0 in a two-channel format. Floating-point formats store linear light and finite values (at most 65,504 for the halves and BC6H, not negative for Ktx2TextureFormat.Bc6HUfloat); the signed formats store values in [-1, 1].

The data format descriptor carries the color label of the image: the sRGB or the linear transfer function, and the primaries of its CICP description when they are among those of KTX (BT.709, BT.2020, Display P3, ...). The orientation is written as KTXorientation (the four orientations without a transposition), and the writer as KTXwriter. ICC profiles, EXIF, XMP and text entries follow ImageEncoder.MetadataHandling.

Inheritance
ImageEncoder Ktx2Encoder

Constructors

NameDescription
Ktx2Encoder()

Ktx2Encoder()

Ktx2Encoder.cs
public Ktx2Encoder()

No documentation is available.

Properties

NameDescription
AllowBitDepthReductionGets a value indicating whether pixels of more bits than Ktx2Encoder.TextureFormat stores are reduced to its precision. Defaults to false: such pixels are rejected.
AllowChannelReductionGets a value indicating whether the channels Ktx2Encoder.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 mip levels is generated, down to 1×1, from the base level of each face or layer. Defaults to false: only the levels of the image or of the collection are written.
QualityGets how hard the block compressors search. Defaults to TextureCompressionQuality.Thorough.
SupercompressionGets the supercompression of the mip levels. Defaults to Ktx2Supercompression.None.
TextureFormatGets the format of the texels, or null (the default) for the uncompressed format that stores the pixels without loss: Ktx2TextureFormat.R8G8B8A8 for 8-bit pixels, Ktx2TextureFormat.R8 or Ktx2TextureFormat.R16 for gray pixels without alpha, Ktx2TextureFormat.R16G16B16A16 for 16-bit pixels, and the floating-point formats of the same precision for floating-point pixels.

AllowBitDepthReduction

Ktx2Encoder.cs

Gets a value indicating whether pixels of more bits than Ktx2Encoder.TextureFormat stores are reduced to its precision. Defaults to false: such pixels are rejected.

public bool AllowBitDepthReduction { get; init; }

Property value

bool

AllowChannelReduction

Ktx2Encoder.cs

Gets a value indicating whether the channels Ktx2Encoder.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

Ktx2Encoder.cs

Gets a value indicating whether the full chain of mip levels is generated, down to 1×1, from the base level of each face or layer. Defaults to false: only the levels 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 mip levels cannot generate them.

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.

Supercompression

Ktx2Encoder.cs

Gets the supercompression of the mip levels. Defaults to Ktx2Supercompression.None.

public Ktx2Supercompression Supercompression { get; init; }

Property value

Ktx2Supercompression

Exceptions

ArgumentOutOfRangeException
The value is not a defined Ktx2Supercompression.

TextureFormat

Ktx2Encoder.cs

Gets the format of the texels, or null (the default) for the uncompressed format that stores the pixels without loss: Ktx2TextureFormat.R8G8B8A8 for 8-bit pixels, Ktx2TextureFormat.R8 or Ktx2TextureFormat.R16 for gray pixels without alpha, Ktx2TextureFormat.R16G16B16A16 for 16-bit pixels, and the floating-point formats of the same precision for floating-point pixels.

public Ktx2TextureFormat? TextureFormat { get; init; }

Property value

Ktx2TextureFormat?

Exceptions

ArgumentOutOfRangeException
The value is not a defined Ktx2TextureFormat.