GifEncoder Class

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.

Definition

Namespace: KGySoft.Drawing.Imaging
Assembly: KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 7.2.0
C#
public sealed class GifEncoder : IDisposable
Inheritance
Object    GifEncoder
Implements
IDisposable

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.

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

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.

Example

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("My GIF animation");
    encoder.AddImage(frame1, location1, delay1);
    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. In the above example it is called implicitly at the end of the using block.
new GifEncoder(stream, new Size(48, 48)) { GlobalPalette = palette }
    .AddComments("My GIF animation")
    .AddImage(frame1, location1, delay1)
    .AddImage(frame2, location2, delay2)
    .FinalizeEncoding();

Constructors

GifEncoder Initializes a new instance of the GifEncoder class.

Properties

AddMetaInfo Gets or sets whether textual meta info should be added to the result stream.
Default value: .
BackColorIndex 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.
CompressionMode 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.
GlobalPalette 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: .
RepeatCount 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: .

Methods

AddComments Writes textual comments to the output stream.
AddImage Writes an image to the output stream.
See the Remarks section of the GifEncoder class for details and examples.
BeginEncodeAnimation Begins to encode the frames of the specified configuration as an animated GIF image and to write it into the specified stream.
BeginEncodeHighColorImage Begins to encode the specified imageData as a multi-layered, single frame GIF image, writing it into the specified stream and preserving its original color depth.
BeginEncodeImage Begins to encode the specified imageData as a GIF image and to write it into the specified stream.
EncodeAnimation Encodes the frames of the specified configuration as an animated GIF image and writes it into the specified stream.
EncodeAnimationAsync Encodes the frames of the specified configuration as an animated GIF image asynchronously, and writes it into the specified stream.
EncodeHighColorImage Encodes the specified imageData as a multi-layered, single frame GIF image and writes it into the specified stream, preserving its original color depth.
EncodeHighColorImageAsync Encodes the specified imageData as a multi-layered, single frame GIF image asynchronously, ans writes it into the specified stream, preserving its original color depth.
EncodeImage Encodes the specified imageData as a GIF image and writes it into the specified stream.
EncodeImageAsync Encodes the specified imageData as a GIF image asynchronously, and writes it into the specified stream.
EndEncodeAnimation Waits for the pending asynchronous operation started by the BeginEncodeAnimation method to complete. In .NET Framework 4.0 and above you can use the EncodeAnimationAsync method instead.
EndEncodeHighColorImage Waits for the pending asynchronous operation started by the BeginEncodeHighColorImage method to complete. In .NET Framework 4.0 and above you can use the EncodeHighColorImageAsync method instead.
EndEncodeImage Waits for the pending asynchronous operation started by the BeginEncodeImage method to complete. In .NET Framework 4.0 and above you can use the EncodeImageAsync method instead.
FinalizeEncoding Finalizes the encoding. It should be called after adding the last image. It is implicitly called when this GifEncoder instance is disposed.

See Also