Product Home • Class Index • Download

CK_ImageTable

CK_Object
   |
   +----CK_ImageTable

An image table stores an array of CK_Image objects. Image tables can be serialized to disk, and deserialized from disk. When a CK_ImageTable object is created from a serialized table, the image data for each image is not loaded into memory. Instead, only an image table header (or directory) is loaded into memory. Images are loaded into memory as needed, or as requested. There are member functions to load (i.e. cache) specific images into memory, as well as to load all images. There are also functions to flush images out of memory. These functions allow an application to manage the memory occupied by image data. An interactive game program, for example, will typically contain far more image data than could ever fit in memory at one time. Relying on virtual memory to manage which images are memory resident may cause paging at undesired times in a game program. As an example, consider a game that has mutliple levels. When advancing to the next level, it would be wise to flush out image data that is no longer necessary, and cache data that will be needed. This allows game action to proceed without image data being paged in from disk.

Examples: 24, 25

Constructors

(A CK_ImageTable must be created using one of the factory methods.)

Factory Methods

create

Creates an image table from a serialized object.

createEmpty

Creates an empty image table.

Public Methods

appendImage

Appends an image onto the end of the table.

cacheAll

Reads all images into memory.

cacheImage

Reads one image into memory.

flushAll

Flushes all images out of memory. (Does not write to disk)

flushImage

Flushes one image out of memory. (Does not write to disk)

getImage

Gets the image at a specific index. The image will be cached into memory if necessary.

getNumImages

Returns the number of slots in the image table. Each slot may or may not be occupied by an image.

serialize

Serializes the image table to disk.

setFilePtr

Gives the image table a file pointer so it can serialize to disk.

setImage

Replaces an image at a given index in the table.

• static CK_ImageTable *create(FILE *fp);

This factory method creates an image table from a serialized table. When the table is create, only the table's header is read from disk. The image data is not loaded.

Return Value

Returns a pointer to the deserialized image table, or 0 if the file pointer did not point to a serialized image table.

Parameters

fp

A file pointer that points to the beginning of a serialized image table.

• static CK_ImageTable *createEmpty(int numSlots);

This factory method creates an empty image table.

Return Value

Returns a pointer to an empty image table.

Parameters

numSlots

Number of image slots the table will initially contain. If an image is appended by calling appendImage(), the number of slots will be increased by one, and the image is contained in the last slot.

• void appendImage(CK_Image *image);

Increases the number of slots by one in the image table, and stores the image in the last slot.

Parameters

image

The image to be stored in the table. The table owns the image once it is inserted. This means that the table will delete the image when the table is destructed, or if the image is flushed from memory.

• void cacheAll(void);

Loads all images into memory. If some images are resident in memory, only the remaining non-resident images will be loaded.

• void cacheImage(int index);

Loads one image into memory.

Parameters

index

The image occupying this slot is loaded into memory from disk. If the image is already in memory, then nothing occurs.

• void flushAll(void);

Flushes all images out of memory. Any images in memory will be deleted.

• void flushImage(int index);

Flushes one image out of memory. The image, if it is in memory, will be deleted.

Parameters

index

The image occupying this slot is destructed.

• const CK_Image *getImage(int index);

Returns a pointer to the image occupying a specific slot in the image table. The image will be loaded into memory if it isn't already cached.

Return Value

Returns a pointer to the image. If no image occupies the slot, 0 will be returned.

Parameters

index

The index of the slot whose image is to be returned.

• int getNumImages(void);

Returns the number of slots in the image table. Each slot can be occupied by an image.

• void serialize(void);

Serializes the image table to the current file pointer. The current file pointer is set by calling setFilePtr().

• void setFilePtr(FILE *fp);

Gives the image table a file pointer that can be used to serialize the table. This is typically done when the table is created via createEmpty(), images are added, and then the table is serialized.

Parameters

fp

An open file pointer positioned at the place where the image table should be serialized. The file pointer should have been opened for writing and in binary mode.

• void setImage(int index, CK_Image *image);

Places an image into a slot. If an image already occupied the slot, that image is deleted and replaced by the new image. The image table takes ownership of the image. This means that the application is not responsible for deleting the image.

Parameters

index

The index of the slot to hold the image.

image

The image to be stored in the image table.