GifEncoder Class

Immutable settings for GIF encoding.

public sealed class GifEncoder : ImageEncoder

Remarks

GIF output is inherently lossy: colors are reduced to at most 256 entries per frame (local palettes, including the transparent entry) with a deterministic quantizer, alpha is reduced to fully transparent or fully opaque, and 16-bit precision is reduced to 8 bits. Selecting the GIF encoder is the explicit opt-in to these losses. A frame whose colors fit its palette is reproduced exactly; other frames use a deterministic variance-based median-cut palette, or a fixed palette, optionally dithered (GifEncoder.Quantization). Comment text entries (Latin-1), an RGB ICC profile and an XMP packet (application extensions) are the metadata it stores.

Frames are encoded from full displayed frames with freshly computed disposal/transparency control data, so pixels that become transparent are correctly cleared: full-canvas frames by default, or the regions that change with GifEncoder.OptimizeFrames. Unknown frame counts are supported by the streaming writer without buffering.

Inheritance
ImageEncoder GifEncoder

Constructors

NameDescription
GifEncoder()

GifEncoder()

GifEncoder.cs
public GifEncoder()

No documentation is available.

Properties

NameDescription
AlphaModeGets how alpha is reduced. Defaults to GifAlphaMode.Threshold.
AlphaThresholdGets the alpha threshold used by GifAlphaMode.Threshold, on the 8-bit scale: pixels with a lower alpha become transparent. 16-bit alpha is compared after reduction to 8 bits. Defaults to 128.
BackgroundColorGets the opaque background color used by GifAlphaMode.Flatten, interpreted in the encoded color space of the image. Required when GifEncoder.AlphaMode is GifAlphaMode.Flatten; saving fails with an ArgumentException otherwise.
DitheringGets the dithering mode: GifEncoder.Quantization.QuantizeOptions.Dithering, which it sets.
DurationRoundingGets how frame durations are converted to GIF hundredths of a second. Defaults to FrameDurationRounding.RoundToNearest.
FormatGets the format produced by this encoder.
InterlacedGets a value indicating whether frames are written interlaced. Defaults to false.
LossyToleranceGets how much error the compression may add to the pixels of a frame whose colors are reduced, to make the file smaller. Defaults to 0: each pixel keeps the palette entry the color reduction gives it.
MaxColorsGets the maximum number of palette entries per frame, including the transparent entry: GifEncoder.Quantization.QuantizeOptions.MaxColors, which it sets.
OptimizeFramesGets a value indicating whether the frames of an animation after the first one are written as the region of the canvas that changes. Defaults to false: every frame covers the canvas and is disposed with "restore to background".
QuantizationGets how colors are reduced to the palette of each frame. Defaults to QuantizeOptions.Default: at most 256 entries per frame, the transparent entry included, without dithering.

AlphaMode

GifEncoder.cs

Gets how alpha is reduced. Defaults to GifAlphaMode.Threshold.

public GifAlphaMode AlphaMode { get; init; }

Property value

GifAlphaMode

Exceptions

ArgumentOutOfRangeException
The value is not a defined GifAlphaMode.

AlphaThreshold

GifEncoder.cs

Gets the alpha threshold used by GifAlphaMode.Threshold, on the 8-bit scale: pixels with a lower alpha become transparent. 16-bit alpha is compared after reduction to 8 bits. Defaults to 128.

public byte AlphaThreshold { get; init; }

Property value

byte

BackgroundColor

GifEncoder.cs

Gets the opaque background color used by GifAlphaMode.Flatten, interpreted in the encoded color space of the image. Required when GifEncoder.AlphaMode is GifAlphaMode.Flatten; saving fails with an ArgumentException otherwise.

public Rgba64? BackgroundColor { get; init; }

Property value

Rgba64?

Exceptions

ArgumentException
The color is not fully opaque.

Dithering

GifEncoder.cs
  • Obsolete: Use Quantization.Dithering, which also selects other dithering modes.

Gets the dithering mode: GifEncoder.Quantization.QuantizeOptions.Dithering, which it sets.

[Obsolete("Use Quantization.Dithering, which also selects other dithering modes.")]
public GifDithering Dithering { get; init; }

Property value

GifDithering

Exceptions

ArgumentOutOfRangeException
The value is not a defined GifDithering.

DurationRounding

GifEncoder.cs

Gets how frame durations are converted to GIF hundredths of a second. Defaults to FrameDurationRounding.RoundToNearest.

public FrameDurationRounding DurationRounding { get; init; }

Property value

FrameDurationRounding

Exceptions

ArgumentOutOfRangeException
The value is not a defined FrameDurationRounding.

Gets the format produced by this encoder.

public override ImageFormat Format { get; }

Property value

ImageFormat

Interlaced

GifEncoder.cs

Gets a value indicating whether frames are written interlaced. Defaults to false.

public bool Interlaced { get; init; }

Property value

bool

LossyTolerance

GifEncoder.cs

Gets how much error the compression may add to the pixels of a frame whose colors are reduced, to make the file smaller. Defaults to 0: each pixel keeps the palette entry the color reduction gives it.

public int LossyTolerance { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is negative or greater than GifEncoder.MaxLossyTolerance.

Remarks

The value is the largest increase of the squared error of a pixel: the sum of the squares of the differences of its red, green and blue samples (8-bit scale) to the color of its source pixel, after the alpha reduction. While it compresses a frame, the encoder may give a pixel another palette entry that continues the sequence of indices it is writing, when that entry is at most this much farther from the color of the pixel than the entry the color reduction (and the dithering) chose. Longer sequences make the file smaller. Values from 30 to 300 are typical: larger values make smaller files and lose more quality. The loss shows as horizontal smearing of fine detail.

A frame whose colors fit its palette is still reproduced exactly, and transparent pixels stay transparent. The output is deterministic.

MaxColors

GifEncoder.cs
  • Obsolete: Use Quantization.MaxColors.

Gets the maximum number of palette entries per frame, including the transparent entry: GifEncoder.Quantization.QuantizeOptions.MaxColors, which it sets.

[Obsolete("Use Quantization.MaxColors.")]
public int MaxColors { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not between 2 and 256.

OptimizeFrames

GifEncoder.cs

Gets a value indicating whether the frames of an animation after the first one are written as the region of the canvas that changes. Defaults to false: every frame covers the canvas and is disposed with "restore to background".

public bool OptimizeFrames { get; init; }

Property value

bool

Remarks

Each frame stores the bounding box of the pixels that differ from the canvas it is drawn on, with the disposal of the previous frame ("do not dispose", "restore to background" or "restore to previous") that gives the smallest box; its unchanged pixels take the transparent entry, and its palette is built from the pixels of the box. A GIF frame cannot make a pixel transparent: the box of the previous frame grows to cover the pixels that become transparent, and its disposal clears them. A frame equal to the previous one is a 1x1 image. The first frame covers the canvas, and the durations, the play count and the number of frames are the same as without the setting.

The pixels are compared after the alpha reduction, before the colors are reduced: when every frame fits its palette, the displayed frames are exactly those of the full-frame output. Otherwise a pixel that does not change keeps the color the frame that drew it was given, where a full frame would map it to its own palette again.

The encoder keeps two copies of the canvas (4 bytes per pixel each), and writes each frame when the next one is given (or when the output completes): the control data of a frame holds the disposal chosen for the next one.

Quantization

GifEncoder.cs

Gets how colors are reduced to the palette of each frame. Defaults to QuantizeOptions.Default: at most 256 entries per frame, the transparent entry included, without dithering.

public QuantizeOptions Quantization { get; init; }

Property value

QuantizeOptions

Exceptions

ArgumentNullException
The value is null.

Remarks

A frame whose colors fit its palette is reproduced exactly; other frames use a deterministic variance-based median cut of their colors (see PaletteBuilder), with the dithering of QuantizeOptions.Dithering.

With QuantizeOptions.Palette, every frame maps to that palette (each frame still has its own local color table, which holds the colors of the palette). The entries get the alpha reduction of the pixels first: GifAlphaMode.Threshold drops the entries whose alpha is below GifEncoder.AlphaThreshold (transparent pixels take the transparent entry) and keeps the color of the others, GifAlphaMode.Flatten composites them over GifEncoder.BackgroundColor. Saving fails with an ArgumentException when no entry is left, or when 256 colors are left for a pixel format with alpha and GifAlphaMode.Threshold (no room for the transparent entry).

Constants

NameDescription
MaxLossyToleranceThe largest GifEncoder.LossyTolerance: the squared distance between black and white (3 x 255²), which allows any entry.

MaxLossyTolerance

The largest GifEncoder.LossyTolerance: the squared distance between black and white (3 x 255²), which allows any entry.

public const int MaxLossyTolerance = 195075