Product Home • Class Index • Download

CK_Bitmap

CK_Bitmap is a base class. The CK_StaticBitmap class, and the CK_Animation class both derive from CK_Bitmap. The CK_Bitmap class specifies a common set of member functions shared by both static and animated bitmaps.

A CK_Bitmap is drawable to the application's display, typically as a property of a CK_Component. CK_Bitmaps are created from CK_Image objects, which are not drawable. The CK_Bitmap stores its pixel data in a way that optimizes drawing to the pixel format of the application's display and render surfaces. If the application's display surface is 16 bits-per-pixel or greater, the CK_Bitmap's pixel data is stored in the identical format. When creating a CK_Bitmap from a CK_Image, the pixel data is converted to the display's pixel format, regardless of the native pixel format of the CK_Image.

For 8 bit-per-pixel CK_Images, the CK_Bitmap does not convert the pixel data to the display surface format. The CK_Bitmap does, however, store the pixel data in a way that optimizes rendering, which will require an on-the-fly lookup of RGB values from the palette. The reason for not converting 8-bit images is because it is possible for a CK_Images to have multiple palettes. CK_Bitmaps that are created from CK_Images with multiple palettes will also contain those palettes. This allows each bitmap to be rendered using any palette, without the need to duplicate the image data for each palette. The following paragraph describes why this design decision was made.

Many game applications have sprites, such as monsters, spaceships, etc. that can be displayed in multiple palettes. Each palette might correspond to a different level of 'toughness' for a particular monster or spaceship. For example, in a popular game called Diablo, each monster can be displayed in a handful of different palettes. When you consider the amount of pixel data a given monster requires, it is very large. Each monster has a number of different actions: walking, attacking, standing, dying, etc. For each of these actions, there must exist an animation for each possible facing direction. For each facing direction, there are 8 or more frames of looping animation. If this pixel data needed to be duplicated for each palette shift, the memory requirments, and CD real-estate requirements would be many times larger. Thankfully, there are never that many monsters on the screen at any one time (as opposed to floor tiles). Because of this, it is acceptable that the rendering performance of a sprite is less than that of a floor or wall tile, since there are few to render in each frame. Essentially, we've optimized space for performance. The space savings are huge, while the performance requirements were much smaller.

Remark:

The library optimizes the storage of palettes. There will be only one copy of each unique palette stored in memory. In other words, if there are 1000 CK_Bitmaps with identical palettes, internally they will all share the same palette in memory and there will not be 1000 copies of the palette in memory.

Factory Methods

createFromImage
Creates a CK_Bitmap from a CK_Image.

Public Methods

draw
Draws the bitmap to the Chilkat engine's render surface.
drawScaled
Draws a stretched or shrunken bitmap to the render surface.
drawTiled
Fills the render surface, or a portion of the render surface, by tiling the bitmap.
getHeight
Returns the height in pixels of the bitmap.
getNumPalettes
Returns the number of palettes contained in the bitmap.Only 8 bit-per-pixel bitmaps have palettes.
getWidth
Returns the width in pixels of the bitmap.
isPaletteBitmap
Returns TRUE if the bitmap is 8 bits-per-pixel.
isTransparent
Returns TRUE if the bitmap has transparency.

Creates a CK_Bitmap from a CK_Image. Returns a pointer to the CK_Bitmap created.

Parameters

image
The image used to create the CK_Bitmap. If the image has transparency, the CK_Bitmap will have the same transparency. If the image is 8 bits-per-pixels, the palettes in the image will be present in the CK_Bitmap.

Draws the bitmap to the Chilkat engine's render surface. All or just a portion of the bitmap can be drawn.

Parameters

destX, destY
The location on the render surface where the bitmap will be drawn. This corresponds to the top-left corner of the rectangle drawn.
srcX, srcY
The top-left corner of the rectangular portion of the bitmap to be drawn.
w, h
The width and height of the portion of the bitmap to be drawn. Passing a 0 in these parameters will cause the entire bitmap to be drawn.
paletteIdx
If the bitmap is 8 bits-per-pixel, this is the index of the palette to be used. For 16 bpp and higher bitmaps, this parameter is ignored.
destX, destY
The location on the render surface where the bitmap will be drawn. This corresponds to the top-left corner of the rectangle drawn.
destWidth, destHeight
The width and height, in pixels, of the drawn rectangle on the destination surface. The bitmap is scaled from srcWidth, srcHeight to destWidth, destHeight.
srcX, srcY
The top-left corner of the rectangular portion of the bitmap to be drawn.
srcWidth, srcHeight
The width and height of the portion of the bitmap to be drawn. Passing a 0 in these parameters will cause the entire bitmap to be drawn and scaled into destWidth, destHeight.
paletteIdx
If the bitmap is 8 bits-per-pixel, this is the index of the palette to be used. For 16 bpp and higher bitmaps, this parameter is ignored.

Tiles a bitmap into the Chilkat engine's render surface. The entire render surface, or a rectangular portion of it can be tiled with the bitmap. The bitmap is not scaled when drawn.

Parameters

destX, destY
The location on the render surface where the bitmap will be tiled. This corresponds to the top-left corner of the rectangle drawn.
destWidth, destHeight
The width and height, in pixels, of the drawn rectangle on the destination surface. The bitmap is tiled to fill this rectangle.
srcX, srcY
The top-left corner of the rectangular portion of the bitmap to be drawn.
srcWidth, srcHeight
The width and height of the portion of the bitmap to be tiled. Passing a 0 in these parameters will cause the entire bitmap to be tiled.
paletteIdx
If the bitmap is 8 bits-per-pixel, this is the index of the palette to be used. For 16 bpp and higher bitmaps, this parameter is ignored.

Returns the height in pixels of the bitmap.

Returns the number of palettes held by the bitmap. Only bitmaps created from 8 bits-per-pixel CK_Images will have palettes. The bitmap can be drawn using any of the palettes.

Returns the width in pixels of the bitmap.

Returns TRUE if the bitmap is 8 bits-per-pixel.

Returns true if the bitmap has transparency.