Bitmap +Animation Overview

Purpose

This document shows you how to create an +animation using the Bitmap Animation framework.

Architectural relationships

The Bitmap Animation +framework (bmpanim.dll) uses the font and bitmap server +(fbscli.dll) to provide the bitmap images (CFbsBitmap s).

An +animation DLL (bmpansrv.dll), loaded by the Window Server, +is used to perform the animation.

The animation DLL uses the bitgdi +component (bitgdi.dll) to draw the bitmaps.

Description

To use a bitmap animation in your application +you need to:

define one or more animation +frames, each of which owns a bitmap,
assign the frames to +an animation container,
create an animation +player object and pass the animation container to it. This communicates with +the window server to start and stop playing the animation inside a window.

Collectively, these steps make up the Bitmap Animation framework. +The key client side classes that are involved in these steps are:

CBitmapFrameData,
CBitmapAnimClientData,
RBitmapAnim.

The rest of this document describes each of these steps, starting +with the animation frame.

Defining an animation frame

The CBitmapFrameData class +represents a single frame in an animation. The following properties of a frame +can be set:

the bitmap image,
the mask, which is used +for making parts of the image transparent,
the time the frame is +displayed, in milliseconds,
the position in the +window where the frame is displayed.

These properties can either be set in CBitmapFrameData::NewL() or +by calling various setter functions, described below.

Setting the +image and mask bitmaps

The following code loads the bitmap and +mask from a multi bitmap file, and constructs the frame, setting its bitmap +and mask, which it takes ownership of:

CFbsBitmap* bitmap=new (ELeave) CFbsBitmap; // load the image bitmap from an mbm file +CleanupStack::PushL(bitmap); +User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1)); +CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file +CleanupStack::PushL(mask); +User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1)); +CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask); +CleanupStack::Pop(2); // bitmap, mask

CBitmapFrameData::SetBitmap() and CBitmapFrameData::SetMask() could alternatively be used.

An animation can have multiple frames, +each of which has an image and mask bitmap. Each frame stores a flag to indicate +whether or not it owns the bitmaps. If the frame owns the bitmaps, they are +deleted in the frame’s destructor. This flag can be set or unset by calling CBitmapFrameData::SetBitmapsOwnedExternally(). +By default, bitmaps are owned by the frame.

The mask is used in the +standard way for a bitmap mask, so pixels in the bitmap image that map to +black pixels in the mask are drawn, while pixels that map to white pixels +in the mask are not, so appear transparent.

Setting the time interval

The +time period for the frame to be displayed on the screen is set in milliseconds:

frame1->SetInterval(125);

Note +that a default time interval can be set in the frame container (described +in the next section) by calling CBitmapAnimClientData::SetFrameInterval(). +Any value set in the container will apply to frames that have not set an interval +themselves.

Setting the frame’s position

The position +of the frame relative to the animation window is set using CBitmapFrameData::SetPosition():

TPoint framePos(3,6); +frame1->SetPosition(framePos);

Note that the position can also +be specified in RBitmapAnim; if so, this value applies +to all frames.

When you have finished defining the animation frame(s), +use the frame container class, CBitmapAnimClientData, to +create the animation.

Defining an animation

Frames are grouped into an +animation frame container (CBitmapAnimClientData), which +allows the following behaviour to be set:

append frames to the +container,
set a default display +interval for all frames, (note that the time interval set by an individual +frame takes precedence, for that frame, over the default interval),
set one of the following +play modes for the animation: play once, loop or bounce (plays forwards and +backwards),
set the animation to +flash,
provide an additional +bitmap frame to use for the background to the animation (explained below).

Appending frames

First, create the frame container, +and append the frame(s) to it in the correct sequence:

CBitmapAnimClientData* animFrames=CBitmapAnimClientData::NewL(); +CleanupStack::PushL(animFrames); +animFrames->AppendFrameL(*frame1); +animFrames->AppendFrameL(*frame2); // etc.

Setting the default +display interval

A default display interval can be set for the +animation:

animFrames->SetFrameInterval(100);

This +applies only to frames which have not specified their own interval (using CBitmapFrameData::SetInterval()). +In this example, the default interval for frames without their own interval +is 100 milliseconds (0.1 second). It can be used to ensure that all frames +are displayed for the same length of time.

Setting the play mode

There +are three play modes: play once, play repeatedly in the same direction ('loop') +and play forwards and backwards repeatedly ('bounce'). This code sets the +animation to play once:

animFrames->SetPlayMode(CBitmapAnimClientData::EPlay);

Other properties

CBitmapAnimClientData::SetFlash() and CBitmapAnimClientData::SetBackgroundFrame() are used to set/unset the flash flag and the background frame, respectively. +The flash flag determines whether the animation should flash or not.

The +background frame, which is optional, is used to clear the current frame before +drawing the next one. If no background frame is provided by the client, the +window server creates its own background frame using the original screen contents, +and updates it when the animation window is redrawn.

If the client-provided +background frame contains an image bitmap and a mask, the background image +used is a combination of the screen contents and the supplied background bitmap. +If the client-provided background frame has a bitmap but no mask, the bitmap +is used as the background.

Playing the animation

When the animation is ready +to play, it must be packaged and sent to the window server’s animation DLL. +This is done through an animation player (RBitmapAnim) +object.

RBitmapAnim allows you to do the following:

specify the window in +which the animation is displayed,
associate the animation +with an RAnimDll object, which provides a connection to +the window server,
pass the animation object +to the window server’s animation DLL,
specify the number of +times the animation should play,
start and stop playing +the animation. Optionally the animation can start playing from a particular +frame.

Note that after the animation object has been set up and passed to +the window server, the general attributes of the animation, namely the flash +property, the default display time for each frame and the play mode can still +be changed, using the following RBitmapAnim functions:

SetFlashL(),
SetFrameIntervalL(),
SetPlayModeL().

Any changes to these properties made using RBitmapAnim will +override the values previously set in CBitmapAnimClientData.

Constructing +the animation player

RAnimDll is a handle +to the server-side animation DLL. It is used to load the window server animation +DLL, bmpansrv.dll, which provides the functions that +perform the frames animation. The RAnimDll instance is passed +to the RBitmapAnim constructor.

RAnimDll animDLL(iEikonEnv->WsSession()); // session is used to interact with the window server +_LIT(KDllName, "BMPANSRV.DLL"); +User::LeaveIfError(animDll.Load(KDllName)); +RBitmapAnim animPlayer(animDLL); +animPlayer.ConstructL(Window());

Passing the animation object +to the window server

The animation frame container (CBitmapAnimClientData) +should be passed via the RBitmapAnim object to the window +server. This is done using the function SetBitmapAnimDataL(). +Note that calling this function does not cause the animation to start playing:

animPlayer.SetBitmapAnimDataL(*animFrames);

Setting +the number of cycles

If the animation should play more than once, +the number of cycles should be set:

animPlayer.SetNumberOfCyclesL(10);

Note that if the animation's play mode is 'bounce', the number of cycles +must be set to at least two to ensure a complete animation routine.

Setting +the position

To set the animation’s position, use SetPositionL(). +This value is an offset from the origin of the animation window.

TPoint animPos(20,40); +animPlayer.SetPositionL(animPos);

Starting/stopping the +animation

The RBitmapAnim::StartL() and RBitmapAnim::StopL() functions +send commands to the animation DLL to start/stop the animation routine.

Calling RBitmapAnim::DisplayFrameL() before +the animation has started sets the frame from which the animation should start +playing.

Freeing resources

After they have been finished +with, Close() should be called on the RAnimDll and RBitmapAnim objects.

animPlayer.Close(); +animDLL.Close();