Implementing Animation

The RasterPictureBox namespace provides a simple "PictureBox" Windows.Forms control with which to display images. Unlike the RasterImageViewer, it does not support scrolling or zooming. However, it does support animation using the Leadtools.RasterImageAnimator class.

Using a RasterPictureBox object is similar to using a RasterImage object. Follow the same steps as those listed in the following section, except instead of using a RasterImage constructor use a RasterPictureBox constructor.

To load and play an animated file, such as GIF or WEBP, you can load the frames into a RasterImage object from the file, then play the list to a target image in a loop that displays each change in the target image. You can also create an animation sequence from scratch and save the images to create an animated GIF/WEBP file.

The following is an outline of possible steps:

1. Load a multi-frame image using Leadtools.Codecs.RasterCodecs.Load
2. Use the Leadtools.RasterImage constructor to create a target image that is the size of the images in the multi-frame image
3. Use the RasterImageAnimator class to create an animation playback that references multi-frame image and the target image

4. In a loop that processes each frame in the multi-frame image, do the following:

   1. Use the RasterImageAnimator.Process method to process the current state and get the next state of the animation
   2. Use the RasterImageAnimator.GetUpdateRectangle method to get the update rectangle (the portion of the target image that has changed)
   3. Use the RasterImagePainter.Paint method to paint the changed portion of the image. To paint only the changed portion, use the update rectangle as the source clipping rectangle.

The animation loop can have a number of states, and you should only paint the changes in an appropriate state (for example, when the next state is RasterImageAnimatorState.PostRender. For a list of possible states, refer to the RasterImageAnimatorState enumeration.

The RasterImage.AnimationDisposalMethod property in the target RasterImage object determines what happens to the image in the playback loop after rendering and after any wait state, when the following state is RasterImageAnimatorState.PostDispose. The options are as follows: keep the image as it is, restore the background, or restore the previous image. (Restoring the background is a common option for animation.)

The animation loop runs continuously through the list of frames. To stop at the end of the list, exit the loop when the following state is RasterImageAnimatorState.End.

Animated Files

Before you load an animated GIF file, you can use the RasterCodecs.GetInformation method to get the file's global animation information, which is updated in the CodecsImageInfo.Gif property. You can use these values in the animation playback

When you load an animated GIF file, using RasterCodecs.Load, the following animation fields in each RasterImage are updated with information from the file: RasterImage.AnimationOffset, RasterImage.AnimationDelay, RasterImage.AnimationBackground, RasterImage.Transparent, RasterImage.TransparentColor and RasterImage.AnimationDisposalMethod. These properties could be unique for each frame in the image. Also, the global animation information are loaded into the following properties: RasterImage.AnimationGlobalLoop, RasterImage.AnimationGlobalSize and RasterImage.AnimationGlobalBackground. These properties are used in the animation playback

When you save an animated GIF file using the RasterCodecs.Save method, these same RasterImage properties are saved in the file. In addition, the global animation information will be used from the RasterImage automatically. For GIF files, the global palette needs to be set manually using the CodecsGifSaveOptions.SetAnimationPalette method and the CodecsGifSaveOptions.UseAnimationPalette property. WebP files are 24/32 bit and do not use palettes.

Animated Files

Before you load an animated GIF/WebP file, you can use the RasterCodecs.GetInformation method to get the file's global animation information, which is updated in the CodecsImageInfo.Gif property. You can use these values in the animation playback

When you load an animated GIF/WebP file, using RasterCodecs.Load, the following animation fields in each RasterImage are updated with information from the file: RasterImage.AnimationOffset, RasterImage.AnimationDelay, RasterImage.AnimationBackground, RasterImage.Transparent, RasterImage.TransparentColor and RasterImage.AnimationDisposalMethod. These properties could be unique for each frame in the image. Also, the global animation information are loaded into the following properties: RasterImage.AnimationGlobalLoop, RasterImage.AnimationGlobalSize and RasterImage.AnimationGlobalBackground. These properties are used in the animation playback

When you save an animated GIF/WebP file using the RasterCodecs.Save method, these same RasterImage properties are saved in the file. In addition, the global animation information will be used from the RasterImage automatically. For GIF files, the global palette needs to be set manually using the CodecsGifSaveOptions.SetAnimationPalette method and the CodecsGifSaveOptions.UseAnimationPalette property. WebP files are 24/32 bit and do not use palettes.

Animated WEBP Files

The steps loading and saving animated WEBP file are almost the same as for animated GIF files. The only difference is animated WEBP files are 32 or 24-bit files and the transparency is implemented using an alpha channel. Therefore, they do not use transparent color or palettes. Instead, animation images can specify that they should be painted using an AlphaBlend operation. That is signaled using the RasterImage.AlphaBlend property.

The WEBP encoder can automatically generate the alpha channel information and whether to do alpha blending or not based on similarities with the previous frame.

Code Examples

WebP animation code examples

Example 1: This examples saves an animated webp file. All the animation frames are stored in a single RasterImage object. See CodecsWebpSaveOptions.

Example 2: This examples saves an animated webp file. The animation frames are appended one by one to the output file.

static void SaveFrameByFrameWebpAni() 
{ 
  string srcFile = @"src.gif"; 
  string dstFile = @"out.webp"; 
 
  using (RasterCodecs codecs = new RasterCodecs()) 
  { 
    int pageCount = 0; 
    using (CodecsImageInfo info = codecs.GetInformation(srcFile, true)) 
    { 
      codecs.Options.Webp.Save.AnimationWidth = info.Gif.AnimationWidth; 
      codecs.Options.Webp.Save.AnimationHeight = info.Gif.AnimationHeight; 
      codecs.Options.Webp.Save.UseAnimationBackground = info.Gif.HasAnimationBackground; 
      codecs.Options.Webp.Save.AnimationBackground = info.Gif.AnimationBackground; 
      codecs.Options.Webp.Save.UseAnimationLoop = info.Gif.HasAnimationLoop; 
      codecs.Options.Webp.Save.AnimationLoop = info.Gif.AnimationLoop; 
      pageCount = info.TotalPages; 
    } 
    codecs.Options.Webp.Save.QualityFactor = 20; // use lossy compression 
 
    // delete the output file so I can keep the code simple and append all pages 
    File.Delete(dstFile); 
 
    for (int i = 1; i <= pageCount; i++) 
    { 
      using (RasterImage image = codecs.Load(srcFile, 0, CodecsLoadByteOrder.BgrOrGray, i, i)) 
      { 
        // save all the pages, appending each new page 
        codecs.Save(image, dstFile, RasterImageFormat.WebpAni, 0, 1, 1, -1, CodecsSavePageMode.Append); 
      } 
    } 
  } 
} 

See also

Introduction Animation