CK_AnimatedImage

CK_Object
   |
   +----CK_Image
           |
           +----CK_AnimatedImage

A CK_AnimatedImage contains an array of static images that represent an animation. The CK_AnimatedImage is a CK_Image, therefore it can be manipulated just like a static image. If the transparent color is set, it applies to all frames in the animation. If palettes are added to the palette set, they also apply to all frames of the animation.

A CK_AnimatedImage can be serialized to a file. The .can extention is for files containing a single serialized animated image. CK_AnimatedImage objects can also be stored as single entries in image tables (CK_ImageTable).

An animated image can contain a default frame rate, which is the number of frames per second at which the animation should run. The frame rate is stored with the object when serialized. This allows the frame rate to be set outside the application, and changed without requiring a change in the application code.

Animated images can be created in one of two ways. One way is to create the animation from a static image (CK_StaticImage) containing all the frames of the animation arranged in a grid. The other way is to create a CK_ImageFrame (from a CK_StaticImage) for each individual frame, and append each frame to the animation.

See CK_Image for more information.

Factory Methods

create: Create a CK_AnimatedImage object from an opened file pointer.
createEmpty: Creates a CK_AnimatedImage with no frames.
createFromFile: Creates a CK_AnimatedImage object from a file containing a serialized CK_AnimatedImage.
createFromImage: Creates a CK_AnimatedImage from a static image that contains the frames of the animation arranged in rows and columns.

Public Methods

appendFrame: Appends an additional frame (CK_ImageFrame) to the animation.
extractFrameAt: Extracts a frame from the animation.
getDefaultFrameRate: Returns the default frame rate for the animation.
getFrameAt: Returns a const pointer to a single frame in the animation.
getNumFrames: Returns the number of frames in the animation.
insertFrameAt: Inserts a frame (CK_ImageFrame) into the animation.
setDefaultFrameRate: Sets the default frame rate for the animation.

Inherited Methods

appendPalette: Adds a palette to the image's palette set.
deletePalette: Delets a palette from the image's palette set.
extractPaletteSet: Removes the palette set from the image. The image will no longer have any palette information.
getCompression: Returns the compression object, if any, installed with this instance.
getHeight: Returns the height in pixels of the image.
getNumPalettes: Returns the number of palettes in the image's palette set, if any.
getPaletteSet: Returns a const pointer to the image's palette set.
getPixelDepth: Returns the bits per pixel of the image.
getTransparentColor: Returns the transparent color (RGBQUAD) of the image, if transparent and >8 bits per pixel.
getTransparentIndex: Returns the transparent palette index of the image, if transparent and 8 bits per pixel.
getWidth: Returns the width in pixels of the image.
isPaletteColor: Returns TRUE if the image is 8 bits per pixel.
isTransparent: Returns TRUE if the image has source transparency.
replacePalette: Replaces a palette in the image's palette set with another.
serialize: Serializes the CK_Image object to disk.
setCompression: Installs a compression object to be used during serialization.
setOpaque: Clears the transparency info for the image.
setTransparentColor: Sets the transparent color for an image having greater than 8 bits per pixel.
setTransparentIndex: Sets the transparent palette index for an image having 8 bits per pixel.
usePaletteSet(CK_PaletteSet *palSet): Associates a palette set with the image.
usePaletteSet(FILE *fp): Deserializes a palette set and associates it with the image.

static CK_AnimatedImage *create(FILE *fp, CK_Compression *com=0);

Creates a CK_AnimatedImage from a serialized CK_AnimatedImage. The file pointer should be positioned at the beginning of the serialized animated image. On return, the file pointer will be positioned at the beginning of the next serialized object (if any) in the file.

Return Value

Returns a pointer to the created object, or 0 if no object could be created because the file pointer did not point to a serialized animated image.

Parameters
fp

File pointer pointing to the beginning of a serialized image. The file pointer should be from a file opened in binary mode:
FILE *fp = fopen("test.can","rb");
com

The name of a compression object to be used for decompressing the image data. If null, no decompression will occur. The compression object must be the same as that used when serializing the image.

static CK_AnimatedImage *createEmpty(void);

Creates an empty CK_AnimatedImage. Frames can be added to the animation by calling appendFrame().

Return Value

Returns a pointer to the CK_AnimatedImage object created.

static CK_AnimatedImage *createFromFile(const char *fileName, CK_Compression *com=0);

Creates a CK_AnimatedImage object from a .can file.

Return Value

Returns a pointer to the CK_AnimatedImage object created. If the file was missing, could not be opened, or did not contain the correct image file format, a null pointer is returned.

Parameters

fileName

The name of a .can file.

com

The name of a compression object to be used with .can files for decompressing the image data. If null, no decompression will occur. The compression object must be the same as that used when serializing the image.

static CK_AnimatedImage *createFromImage(CK_StaticImage *image, int nColumns, int frameWidth, int frameHeight, int numFrames);

Creates a CK_AnimatedImage from a static image (CK_StaticImage) that contains each frame of the animation arranged in grid. The figure below shows one possible layout of frames in the static image for an animation with 10 frames.

Return Value

Returns a pointer to the CK_AnimatedImage object created.

Parameters

image

The static image containing a grid of frames.

nColumns

The number of columns in the grid.

frameWidth

The width in pixels of each frame.

frameHeight

The height in pixels of each frame.

numFrames

The total number of frames in the animation. This does not need to be evenly divisible by the number of columns, as demonstrated in the example above.

void appendFrame(CK_ImageFrame *frame);

Appends a frame to the end of the animation. The animated image has ownership of the image frame. When the animated image is deleted, each owned image frame will be deleted.

Parameters

frame

A CK_ImageFrame object representing one frame in the animation.

CK_ImageFrame *extractFrameAt(int frameIndex);

Removes a single frame from the animation. When the frame is removed, the CK_AnimatedImage no longer owns the frame.

Return Value

Returns a pointer to the extracted image frame.

Parameters

frameIndex

The index of the frame to be removed. The first frame in the animation is at index 0.

int getDefaultFrameRate(void) const;

Returns the default frame rate (frames per second) of the animation. The default frame rate is stored with the animated image when the object is serialized.

const CK_ImageFrame *getFrameAt(int frameIndex) const;

Returns a const pointer to a single frame in the animation.

Return Value

A const pointer to the image frame is returned because the CK_AnimatedImage still owns the frame, and it should not be deleted or modified.

Parameters

frameIndex

The index of the frame to get. The first frame in the animation is at index 0.

int getNumFrames(void) const;

Returns the number of frames in the animation.

void insertFrameAt(int frameIndex, CK_ImageFrame *frame);

Inserts a single frame into the animation.

Parameters

frameIndex

The index of the frame once it is inserted. Existing frames at frameIndex and above are shifted one index higher to make room for the inserted frame. Inserting a frame at index 0 will make it the first frame in the animation.

frame

The frame to be inserted.

void setDefaultFrameRate(int frameRate);

Sets the default frame rate (frames per second) of the animation.

CK_AnimatedImage object are not drawable, so what is the point to setting a frame rate? CK_AnimatedImages are serializable, and the frame rate is stored with the object when serialized. A CK_AnimatedBitmap, which is drawable, can be created from a CK_AnimatedImage. The (drawable) animated bitmap will initialize its frame rate to that of the (non-drawable) animated image. The purpose is to allow the frame rate to be controlled outside of the application code.

Parameters

frameRate

The frame rate, in frames per second, of the animation.

CK_AnimatedImage

Factory Methods

Public Methods

Inherited Methods

static CK_AnimatedImage create(FILE fp, CK_Compression *com=0);

static CK_AnimatedImage *createEmpty(void);

static CK_AnimatedImage createFromFile(const char fileName, CK_Compression *com=0);

static CK_AnimatedImage createFromImage(CK_StaticImage image, int nColumns, int frameWidth, int frameHeight, int numFrames);

void appendFrame(CK_ImageFrame *frame);

CK_ImageFrame *extractFrameAt(int frameIndex);

int getDefaultFrameRate(void) const;

const CK_ImageFrame *getFrameAt(int frameIndex) const;

int getNumFrames(void) const;

void insertFrameAt(int frameIndex, CK_ImageFrame *frame);

void setDefaultFrameRate(int frameRate);

CK_AnimatedImage

Factory Methods

Public Methods

Inherited Methods

static CK_AnimatedImage *create(FILE *fp, CK_Compression *com=0);

static CK_AnimatedImage *createEmpty(void);

static CK_AnimatedImage *createFromFile(const char *fileName, CK_Compression *com=0);

static CK_AnimatedImage *createFromImage(CK_StaticImage *image, int nColumns, int frameWidth, int frameHeight, int numFrames);

void appendFrame(CK_ImageFrame *frame);

CK_ImageFrame *extractFrameAt(int frameIndex);

int getDefaultFrameRate(void) const;

const CK_ImageFrame *getFrameAt(int frameIndex) const;

int getNumFrames(void) const;

void insertFrameAt(int frameIndex, CK_ImageFrame *frame);

void setDefaultFrameRate(int frameRate);

static CK_AnimatedImage create(FILE fp, CK_Compression *com=0);

static CK_AnimatedImage createFromFile(const char fileName, CK_Compression *com=0);

static CK_AnimatedImage createFromImage(CK_StaticImage image, int nColumns, int frameWidth, int frameHeight, int numFrames);