GifEncoder Class

KGy SOFT Drawing Libraries Help
Provides an encoder for GIF image format that supports animation. Use the static members for high-level access or create an instance to control everything manually.
See the Remarks section for details.
Inheritance Hierarchy

SystemObject
  KGySoft.Drawing.ImagingGifEncoder

Namespace:  KGySoft.Drawing.Imaging
Assembly:  KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 6.0.0
Syntax

public sealed class GifEncoder : IDisposable

The GifEncoder type exposes the following members.

Constructors

  NameDescription
Public methodGifEncoder
Initializes a new instance of the GifEncoder class.
Top
Properties

  NameDescription
Public propertyAddMetaInfo
Gets or sets whether textual meta info should be added to the result stream.
Default value: .
Public propertyBackColorIndex
Gets or sets the background color index if GlobalPalette is set. It is relevant only if the palette of the first added image has no transparent entry, in which case determines the initial background color if the first added image does not completely cover the virtual screen, and also the color of the cleared virtual screen.
Public propertyCompressionMode
Gets or sets the compression mode to be used when adding images by the AddImage method. This property can be changed at any time.
Default value: Auto.
Public propertyGlobalPalette
Gets or sets the global palette. If not set, then each added image will be stored along with their own palette. If not , then the palette of the added images are stored only when they are different from the global palette.
Default value: .
Public propertyRepeatCount
Gets or sets the number of repetitions if creating an animation. Set a non- value to add the NETSCAPE2.0 extension to the stream and to indicate that added images should be interpreted as animation frames. Use 0 to loop the animation indefinitely. If , and images are added with 0 delay, then GDI+ handles image as a multi-layer single frame image, though some application (including browsers) still may play them as individual frames.
Default value: .
Top
Methods

  NameDescription
Public methodAddComments
Writes textual comments to the output stream.
Public methodAddImage
Writes an image to the output stream.
See the Remarks section if the GifEncoder class for details and examples.
Public methodStatic memberEncodeAnimation
Encodes the frames of the specified configuration as an animated GIF image and writes it into the specified stream.
Public methodStatic memberEncodeImage
Encodes the specified imageData as a GIF image and writes it into the specified stream.
Public methodFinalizeEncoding
Finalizes the encoding. It should be called after adding the last image. It is implicitly called when this GifEncoder instance is disposed.
Top
Remarks

The simplest way to create a single-frame GIF image is calling the static EncodeImage method. It can quantize and dither any input IReadableBitmapData source.

The simplest way to create a GIF animation is calling the static EncodeAnimation method. It expects an AnimatedGifConfiguration that describes the frames and delays to be used along with numerous optional configuration such as a specific quantizer and ditherer, looping mode, handling of possible different input image sizes, encoding strategies like allowing delta images or explicitly encoding transparent borders.

Tip Tip
If you use an OptimizedPaletteQuantizer and the AllowDeltaFrames property is , then you can create really high quality animations allowing more than 256 colors per frame.

Alternatively, you can instantiate the GifEncoder class, which allows you even more control at lower levels. The RepeatCount, GlobalPalette and BackColorIndex properties should be set before adding the first frame, whereas CompressionMode can be changed before each frame. The AddImage method allows specifying a location for each frame as well as an action to be performed after the delay interval of the corresponding frame is over. You can even write comments to the serialization stream by the AddComments method.

Note Note
When using the AddImage method to add frames you should use already quantized images with indexed pixel format. Non-indexed images will be quantized using the default 8-bit "web-safe" palette without dithering.

Examples

The following example demonstrates how to use the encoder in a using block:

C#
using (var encoder = new GifEncoder(stream, new Size(48, 48)) { GlobalPalette = palette })
{
    encoder.AddComments("Here starts the 1st frame");
    encoder.AddImage(frame1, location1, delay1);
    encoder.AddComments("And here 2nd one");
    encoder.AddImage(frame2, location2, delay2);
}

Or, by using fluent syntax the example above can be re-written like this:

C#
// Note the last FinalizeEncoding step. It is called implicitly at the end of a using block.
new GifEncoder(stream, new Size(48, 48)) { GlobalPalette = palette }
    .AddComments("Here starts the 1st frame")
    .AddImage(frame1, location1, delay1)
    .AddComments("And here 2nd one")
    .AddImage(frame2, location2, delay2)
    .FinalizeEncoding();

See Also

Reference