Meziantou.FrameworkGifEncoder Class
Immutable settings for GIF encoding.
public sealed class GifEncoder : ImageEncoderRemarks
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). Only Comment text entries (Latin-1) are stored as metadata.
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
ImageEncoderGifEncoder
Constructors
| Name | Description |
|---|---|
| GifEncoder() |
GifEncoder()
GifEncoder.cspublic GifEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AlphaMode | Gets how alpha is reduced. Defaults to GifAlphaMode.Threshold. |
| AlphaThreshold | 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. |
| BackgroundColor | 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. |
| Dithering | Gets the dithering mode: GifEncoder.Quantization.QuantizeOptions.Dithering, which it sets. |
| DurationRounding | Gets how frame durations are converted to GIF hundredths of a second. Defaults to FrameDurationRounding.RoundToNearest. |
| Format | Gets the format produced by this encoder. |
| Interlaced | Gets a value indicating whether frames are written interlaced. Defaults to false. |
| MaxColors | Gets the maximum number of palette entries per frame, including the transparent entry: GifEncoder.Quantization.QuantizeOptions.MaxColors, which it sets. |
| OptimizeFrames | 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". |
| Quantization | 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. |
AlphaMode
GifEncoder.csGets how alpha is reduced. Defaults to GifAlphaMode.Threshold.
public GifAlphaMode AlphaMode { get; init; }AlphaThreshold
GifEncoder.csGets 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
BackgroundColor
GifEncoder.csGets 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; }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; }DurationRounding
GifEncoder.csGets how frame durations are converted to GIF hundredths of a second. Defaults to FrameDurationRounding.RoundToNearest.
public FrameDurationRounding DurationRounding { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
FrameDurationRounding.
Format
GifEncoder.csInterlaced
GifEncoder.csMaxColors
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.
OptimizeFrames
GifEncoder.csGets 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
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.csGets 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
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).