CK_Image

CK_Object
   |
   +----CK_Image

CK_Image is a base class. The CK_StaticImage class, and the CK_AnimatedImage class both derive from CK_Image. The CK_Image class specifies a common set of member functions shared by both static and animated images.

The CK_Image class represents a graphics image loaded from disk. A factory method can be used to create a CK_Image object from a PCX file. It is also possible to create images from BMP files, or previously serialized CK_Image objects.

Once created, additional information can be stored in the CK_Image object. This includes transparency information and multiple palette sets. For animated images, each frame of the animation is stored within the CK_Image, as well as a default frame rate. When a CK_Image is serialized to disk, this additional information is saved. As an example, a CK_Image can be created from a PCX file. Transparency information can then be added. If the image is 8 bits/pixel, additional palettes can also be added. When the CK_Image is serialized, the additional information is stored along with the original image. The additional information is restored when the CK_Image is deserialized.

CK_Image objects cannot be drawn to the display. This is because the pixel data might not be stored in the same format (i.e. bits/pixel) as the display surface. The CK_Bitmap class represents a bitmap stored in the correct pixel format. It is possible to create a CK_Bitmap object using a CK_Image. Creating the CK_Bitmap object effectively converts from any pixel format to any other. This architecture allows any program to run at any pixel depth, using the same graphics. In practice, the CK_Image objects are deleted from memory once CK_Bitmaps are created.

Factory Methods

createFromFile: Creates a CK_Image object from a file.
createImage: Create a CK_Image object from an opened file pointer.

Public 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.

void appendPalette(const CK_Palette *pal);

Appends a palette to the image's palette set.

Parameters

pal

The palette to be inserted into the image's palette set. This function creates a copy of pal, which is inserted into the palette set.

Remarks

If the image is not 8 bits per pixel, then this function will do nothing.

This is essentially a convenience function because the same thing can be achieved by extracting the image's palette set, appending the palette to it, and then using the palette set by calling usePaletteSet().

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

Creates either a CK_StaticImage, or CK_AnimatedImage object, based on the fileName passed. Files ending in .pcx or .bmp are created as static images with no transparency. If the graphics file is 8 bits per pixel, then the CK_Image will contain a palette set with one palette. Files ending in .cim are serialized static images, and files ending in .can are serialized animated images.

Return Value

Returns a pointer to the CK_Image 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 .pcx, .bmp, .cim, or .can file.

com

The name of a compression object to be used with .cim or .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.

Remarks

This is a good factory method to use when you don't care whether the image is static or animated, and you just want to manipulate it as a CK_Image.

static CK_Image *createImage(FILE *fp, CK_Compression *com=0);

This factory method is used to create either a CK_StaticImage or a CK_AnimatedImage from an already opened file. This function will automatically detect which type of image (static or animated) exists and create the appropriate type of object. It can only be used with serialized objects, and not with pre-opened .pcx or .bmp files. The file pointer will be left at the beginning of the next object in the file.

Return Value

Returns a pointer to the image, or 0 if a serialized CK_Image was not found at the file pointer.

Parameters

fp

File pointer pointing to the beginning of a serialized image. The file pointer should be from a file opened in binary mode - such as 'fopen("x.cim","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.

Remarks

This function makes it possible to store multiple objects in a single file. As an example, the CK_ImageTable class uses this function to read images from .ckt files containing multiple serialized images.

void deletePalette(int palIdx);

Deletes a palette from the image's palette set. The function does nothing if the image is not 8-bit color, or if the image has no palette set.

Parameters

palIdx

The index of the palette in the palette set to delete. The first palette in the set is at index 0. If palIdx is not a valid index, this function will do nothing.

Remarks

When the palette is deleted from the set, the palettes at higher indexes are shifted down one. For example, if an image has 3 palettes, and the middle one is deleted, the palette set would then contain 2 palettes, one at index 0, the other at index 1.

The image's palette set is re-created internally. This means that if the application previously obtained a const pointer to the palette set using getPaletteSet(), the pointer should not be used and the palette set should be gotten again.

CK_PaletteSet *extractPaletteSet(void);

Extracts the palette set from the image. The image will no longer contain a palette set.

Return Value

Returns a pointer to the extracted palette set. Returns 0 if the image did not have a palette set.

Remarks

A typical use for this function is to load a CK_Image, extract the palette set, and then use that palette set in another CK_Image. It is an easy way to transfer the palette set from one image to another.

CK_Compression *getCompression(void) const;

Obtains a pointer to the compression object used by this image.

Return Value

A pointer to the image's compression object, or 0 if the image has no compression assigned.

Remarks

Compression objects are never 'owned' by any other object. Usually, one compression object is created and is referenced by many images created by an application.

int getHeight(void) const;

Returns the height in pixels of the image. For animated images, the height of a single frame is returned. All frames in an animated image must be the same height and width.

int getNumPalettes(void) const;

Returns the number of palettes in the image's palette set. If the image has no palette set, then 0 is returned. Images with more than 8 bits per pixel do not have palette sets.

const CK_PaletteSet *getPaletteSet(void) const;

Returns a const pointer to the image's palette set. If the image has no palette set, then a null pointer is returned.

A const pointer is returned because the image owns the CK_PaletteSet object, and the application should not try to delete it.

int getPixelDepth(void) const;

Returns the pixel depth of the image, which can be 8, 16, 24, or 32.

void getTransparentColor(RGBQUAD &color) const;

Returns the transparent color for 16, 24, and 32 bit images.

Parameters

color

Deposits the transparent color into this RGBQUAD structure.

int getTransparentIndex(void) const;

Returns the transparent palette index for 8 bit images.

Return Value

Returns the transparent palette index (0-255).

int getWidth(void) const;

Returns the width in pixels of the image. For animated images, the width of a single frame is returned. All frames in an animated image must be the same height and width.

int isPaletteColor(void) const;

Returns TRUE if the image is 8 bits per pixel, otherwise returns FALSE.

int isTransparent(void) const;

Returns TRUE if the image is transparent, otherwise returns FALSE.

void replacePalette(int palIdx, const CK_Palette *pal);

Replaces a palette in the image's palette set.

Parameters

palIdx

The index of the palette in the set to be replaced.

pal

The replacement palette. A copy of this palette is created and stored in the palette set.

void serialize(FILE *fp) const;

Serializes the image to a file. Everything about the image is serialized, including the pixel data, palette set, transparency information, and for animations, the default frame rate. The pixel data is compressed if a compression object was installed using setCompression().

Parameters

fp

File pointer into a file opened for writing in binary mode.

void setCompression(CK_Compression *com);

Sets the compression object for the image. This compression object will be used to compress the pixel data when serializing to disk.

Parameters

com

The compression object to be used in serialization.

See Also

Compression

void setOpaque(void);

Makes the image non-transparent.

void setTransparentColor(const RGBQUAD &color);

Makes the image transparent, and sets the transparent color. This function is used for images with pixel depths greater than 8 bits per pixel.

Parameters

color

The color to be treated as transparent.

void setTransparentIndex(int index);

Makes the image transparent, and sets the transparent color index. This function is only used with 8-bit palette images.

Parameters

index

The palette index to be treated as transparent.

void usePaletteSet(CK_PaletteSet *palSet);

Installs a new palette set for the image. The old palette set, if it exists, is deleted. The CK_Image takes ownership of the palette set. This means that when the CK_Image is deleted, it will delete the palette set.

Parameters

palSet

The palette set to be stored within the CK_Image object.

void usePaletteSet(FILE *fp);

Deserializes a CK_PaletteSet object and installs it as the CK_Image object's palette set. The image's old palette set is deleted, if it exists.

Parameters

fp

An open file pointer positioned at the beginning of a serialized CK_PaletteSet object.

CK_Image

Factory Methods

Public Methods

void appendPalette(const CK_Palette *pal);

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

static CK_Image createImage(FILE fp, CK_Compression *com=0);

Remarks

void deletePalette(int palIdx);

Remarks

CK_PaletteSet *extractPaletteSet(void);

Remarks

CK_Compression *getCompression(void) const;

Remarks

int getHeight(void) const;

int getNumPalettes(void) const;

const CK_PaletteSet *getPaletteSet(void) const;

int getPixelDepth(void) const;

void getTransparentColor(RGBQUAD &color) const;

int getTransparentIndex(void) const;

int getWidth(void) const;

int isPaletteColor(void) const;

int isTransparent(void) const;

void replacePalette(int palIdx, const CK_Palette *pal);

void serialize(FILE *fp) const;

void setCompression(CK_Compression *com);

void setOpaque(void);

void setTransparentColor(const RGBQUAD &color);

void setTransparentIndex(int index);

void usePaletteSet(CK_PaletteSet *palSet);

void usePaletteSet(FILE *fp);

CK_Image

Factory Methods

Public Methods

void appendPalette(const CK_Palette *pal);

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

static CK_Image *createImage(FILE *fp, CK_Compression *com=0);

Remarks

void deletePalette(int palIdx);

Remarks

CK_PaletteSet *extractPaletteSet(void);

Remarks

CK_Compression *getCompression(void) const;

Remarks

int getHeight(void) const;

int getNumPalettes(void) const;

const CK_PaletteSet *getPaletteSet(void) const;

int getPixelDepth(void) const;

void getTransparentColor(RGBQUAD &color) const;

int getTransparentIndex(void) const;

int getWidth(void) const;

int isPaletteColor(void) const;

int isTransparent(void) const;

void replacePalette(int palIdx, const CK_Palette *pal);

void serialize(FILE *fp) const;

void setCompression(CK_Compression *com);

void setOpaque(void);

void setTransparentColor(const RGBQUAD &color);

void setTransparentIndex(int index);

void usePaletteSet(CK_PaletteSet *palSet);

void usePaletteSet(FILE *fp);

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

static CK_Image createImage(FILE fp, CK_Compression *com=0);