24 Bitmaps

This chapter provides information about bitmaps by discussing these topics:

• Bitmap Data Structures
  
  
• Bitmap Constants
  
  
• Bitmap Resources
  
  
• Bitmap Functions
  

The header file Bitmap.h declares the API that this chapter describes. For more information on windows, see the section "Bitmaps" in the Palm OS Programmer's Companion.

Bitmap Data Structures

BitmapCompressionType

The BitmapCompressionType enum specifies possible bitmap compression types. These are the possible values for the compressionType field of BitmapType. You can compress or uncompress a bitmap using a call to BmpCompress.

typedef enum {

    BitmapCompressionTypeScanLine = 0,
    BitmapCompressionTypeRLE,
    BitmapCompressionTypeNone = 0xFF
} BitmapCompressionType;

Value Descriptions

Compatibility

This type is only defined if 3.5 New Feature Set is present. Earlier releases do support compressed bitmaps, but in scan line format only.

BitmapFlagsType

The BitmapFlagsType bit field defines the flags field of BitmapType. It specifies the bitmap's attributes.

typedef struct BitmapFlagsType {

    UInt16 compressed:1;
    UInt16 hasColorTable:1;
    UInt16 hasTransparency:1;
    UInt16 indirect:1;
    UInt16 forScreen:1;
    UInt16 reserved:11;
} BitmapFlagsType;

Field Descriptions

Compatibility

All flags other than compressed and hasColorTable are only defined if 3.5 New Feature Set is present. Note that the size of this structure did not change.

BitmapPtr

The BitmapPtr type defines a pointer to a BitmapType structure.

typedef BitmapType *BitmapPtr;

BitmapType

The BitmapType structure represents a bitmap. This structure defines both the bitmaps representing the window display and bitmap resources ('Tbmp' and 'tAIB') that you create using Constructor or some other application and load into your program.

typedef struct BitmapType {

    Int16 width;
    Int16 height;
    UInt16 rowBytes;
    BitmapFlagsType flags;
    UInt8 pixelSize;
    UInt8 version;
    UInt16 nextDepthOffset;
    UInt8 transparentIndex;
    UInt8 compressionType;
    UInt16 reserved;
} BitmapType;

Field Descriptions

Note the following about the BitmapType structure:

• None of these fields contains the actual bitmap data. Instead, the bitmap data is stored immediately following this BitmapType header structure. If the bitmap has its own color table, the color table is stored in between the header and the data. You can retrieve a bitmap's data by passing its BitmapType structure to BmpGetBits, and you can retrieve its color table with BmpGetColortable.
  
  
• Unlike most other user interface structures, the BitmapType does not store the bitmap's location on the screen. The WindowType or the FormBitmapType with which this bitmap is associated contains that information.
  
  
• A bitmap may be part of a bitmap family. A bitmap family is a group of bitmaps, each containing the same drawing but at a different pixel depth (see Figure 24.1). When requested to draw a bitmap family, the operating system chooses the version of the bitmap with the pixel depth closest to the display. When BitmapType represents a bitmap family, the nextDepthOffset field contains the offset from the start of this bitmap to the next bitmap in the family.
  

Figure 24.1 Bitmap Family

Compatibility

The transparentIndex and compressionType flags are defined only if 3.5 New Feature Set is present.

ColorTableType

The ColorTableType structure defines a color table. Bitmaps can have color tables attached to them; however, doing so is not recommended for performance reasons.

typedef struct ColorTableType {

    UInt16 numEntries;
    // RGBColorType entry[];
} ColorTableType;

Field Descriptions

The color table entries themselves are of type RGBColorType, and there is one per numEntries. Use the macro ColorTableEntries to retrieve these entries.

Care should be taken not to confuse a full color table (which includes the count) with an array of RGB color values. Some routines operate on entire color tables; others operate on lists of color entries.

Compatibility

This type is defined only if 3.5 New Feature Set is present.

RGBColorType

The RGBColorType structure defines a color. It is used as an entry in the color table. RGBColorTypes can also be created manually and passed to several user interface functions.

typedef struct RGBColorType {

    UInt8 index;
    UInt8 r;
    UInt8 g;
    UInt8 b;
} RGBColorType;

Field Descriptions

Compatibility

This type is defined only if 3.5 New Feature Set is present.

Bitmap Constants

Bitmap Resources

You can create a bitmap resource and include it as part of your application's PRC file. Use the resource type 'Tbmp' for most images and the resource type 'tAIB' for application icons. Symbolically, these two resource types are bitmapRsc an iconType, respectively.

Note that if you are creating a bitmap or a bitmap family in Constructor, you create a 'tbmf' resource (or 'taif' resource for icons) and one or more 'PICT' images, and the PalmRez post linker converts them into a single 'Tbmp' or 'tAIB' resource. Note that the PalmRez post linker takes PICT images even on the Microsoft Windows operating system.

Bitmap Functions

BmpBitsSize

Purpose

Return the size of the bitmap's data.

Prototype

UInt16 BmpBitsSize (BitmapType *bitmapP)

Parameters

-> bitmapP

Pointer to the bitmap. (See BitmapType.)

Result

Returns the size in bytes of the bitmap's data, excluding the header and the color table.

Comments

This function returns the bitmap's data size even if the bitmap's indirect flag is set. (See BitmapFlagsType.)

If the bitmap is compressed, this function returns the compressed size of the bitmap.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpSize, BmpColortableSize, BmpGetBits

BmpColortableSize

Purpose

Return the size of the bitmap's color table.

Prototype

UInt16 BmpColortableSize (BitmapType *bitmapP)

Parameters

-> bitmapP

Pointer to the bitmap. (See BitmapType.)

Result

Returns the size in bytes of the bitmap's color table or 0 if the bitmap does not use its own color table.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpBitsSize, BmpSize, BmpGetColortable

BmpCompress

Purpose

Compress or uncompress a bitmap.

Prototype

Err BmpCompress (BitmapType *bitmapP, BitmapCompressionType compType)

Parameters

-> bitmapP

Pointer to the bitmap to compress. (See BitmapType.)

-> compType

The type of compression to use. (See BitmapCompressionType.) If set to BitmapCompressionTypeNone and bitmapP is compressed, this function uncompresses the bitmap.

Result

Returns one of the following values:

errNone

Success.

sysErrParamErr

Either the compType parameter does not specify a compression type or the bitmap is already compressed, is in the storage heap, or represents the screen.

memErrNotEnoughSpace

There is not enough memory available to complete the operation.

Comments

This function performs the specified compression and resizes the bitmap's allocated memory. The bitmap must be in the dynamic heap.

Compatibility

Implemented only if 3.5 New Feature Set is present.

BmpCreate

Purpose

Create a bitmap.

Prototype

BitmapType *BmpCreate (Coord width, Coord height, UInt8 depth, ColorTableType *colortableP, UInt16 *error)

Parameters

-> width

The width of the bitmap in pixels. Must not be 0.

-> height

The height of the bitmap in pixels. Must not be 0.

-> depth

The pixel depth of the bitmap. Must be 1, 2, 4 or 8. This value is used as the pixelSize field of BitmapType.

-> colortableP

A pointer to the color table associated with the bitmap, or NULL if the bitmap should not include a color table. If specified, the number of colors in the color table must match the depth parameter. (2 for 1-bit, 4 for 2-bit, 16 for 4-bit, and 256 for 8-bit).

<- error

Contains the error code if an error occurs.

Result

Returns a pointer to the new bitmap structure (see BitmapType) or NULL if an error occurs. The parameter error contains one of the following:

errNone

Success.

sysErrParamErr

The width, height, depth, or colorTableP parameter is invalid. See the descriptions above for acceptable values.

memErrNotEnoughSpace

There is not enough memory available to allocate the structure.

Comments

This function creates an uncompressed, non-transparent BitmapVersionTwo bitmap with the width, height, and depth that you specify.

If you pass a color table, the bitmap's hasColorTable flag is set. For performance reasons, attaching a custom color table to a bitmap is strongly discouraged. An alternative is to use the WinPalette command to change the color table as needed, draw the bitmap, and then undo your changes after you have finished displaying the bitmap.

The newly created bitmap contains no data. To create data for this bitmap, use the window drawing functions. First, you must use WinCreateBitmapWindow to create a offscreen window wrapper around the bitmap, then draw to that window:

BitmapType *bmpP;

WinHandle win;
Err error;
RectangleType onScreenRect;

bmpP = BmpCreate(10, 10, 8, NULL, &error);
if (bmpP) {
    win = WinCreateBitmapWindow(bmpP, &error);
    if (win) {
    WinSetDrawWindow(win);
    WinDrawLines(win, ...);
    /* etc */
    WinSetWindowBounds(win, onScreenRect);
    }
}

You cannot use this function to create a bitmap written directly to a database; that is, you must create the bitmap on the dynamic heap first, then write it to the storage heap.

It's not necessary to use BmpCreate to load a bitmap stored in a resource. Instead, you simply load the resource and lock its handle. The returned pointer is a pointer to a BitmapType. For example:

MemHandle resH =

    DmGetResource (bitmapRsc, rscID);
BitmapType *bitmap = MemHandleLock (resH);

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpDelete

BmpDelete

Purpose

Delete a bitmap structure.

Prototype

Err BmpDelete (BitmapType *bitmapP)

Parameters

-> bitmapP

Pointer to the structure of the bitmap to be deleted. (See BitmapType.)

Result

Returns errNone upon success, sysErrParamErr if the bitmap's forScreen flag is set or the bitmap resides in the storage heap. Returns one of the memory errors if the freeing the pointer fails.

Comments

Only delete bitmaps that you've created using BmpCreate.

You cannot use this function on a bitmap located in a database. To delete a bitmap from a database, use the standard data manager calls.

Compatibility

Implemented only if 3.5 New Feature Set is present.

BmpGetBits

Purpose

Retrieve the bitmap's data.

Prototype

void *BmpGetBits (BitmapType *bitmapP)

Parameters

-> bitmapP

Pointer to the bitmap's structure. (See BitmapType.)

Result

Returns a pointer to the bitmap's data.

Comments

This function returns the bitmap's data even if the bitmap's indirect flag is set. (See BitmapFlagsType.)

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpBitsSize

BmpGetColortable

Purpose

Retrieve the bitmap's color table.

Prototype

ColorTableType *BmpGetColortable (BitmapType *bitmapP)

Parameters

-> bitmapP

A pointer to the bitmap. See BitmapType.

Result

Returns a pointer to the color table or NULL if the bitmap uses the system color table.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpColortableSize

BmpSize

Purpose

Return the size of the bitmap.

Prototype

UInt16 BmpSize (BitmapType *bitmapP)

Parameters

-> bitmapP

A pointer to the bitmap. See BitmapType.

Result

Returns the size in bytes of the bitmap, including its header and color table (if any).

Comments

If the bitmap has its indirect flag set (see BitmapFlagsType), the bitmap data is not included in the size returned by this function.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpBitsSize, BmpColortableSize

ColorTableEntries

Purpose

Macro that returns the color table.

Prototype

ColorTableEntries (ctP)

Parameters

-> ctP

A pointer to a ColorTableType structure.

Result

Returns an array of RGBColorType structures, one for each entry in the color table.

Comments

You can use this macro to retrieve the RGB values in use by a bitmap. For example:

BitmapType *bmpP;

RGBColorType *tableP =
    ColorTableEntries(BmpGetColorTable(bmpP));

If you want to retrieve the RGB values in use by the system color table, you can simply use the WinPalette function instead of this macro:

RGBColorType table;

Err e;

/* allocate space for table */
e = WinPalette(winPaletteGet, 0, 256, &table);

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpGetColortable