Bitmaps
 

 < Home   < Developers   < Development Support   < Documentation

26 Bitmaps


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

26 Bitmaps

Bitmap Data Structures

BitmapCompressionType

BitmapDirectInfoType

BitmapFlagsType

BitmapPtr

BitmapType

ColorTableType

RGBColorType

Bitmap Constants

Bitmap Resources

Bitmap Functions

BmpBitsSize

BmpColortableSize

BmpCompress

BmpCreate

BmpDelete

BmpGetBits

BmpGetBitDepth

BmpGetColortable

BmpGetDimensions

BmpGetNextBitmap

BmpGetSizes

BmpSize

ColorTableEntries

       

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 bitmaps, see the section "Bitmaps" in the Palm OS Programmer's Companion, vol. I.

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, 
  BitmapCompressionTypePackBits, 
  BitmapCompressionTypeEnd, 
  BitmapCompressionTypeBest = 0x64, 
  BitmapCompressionTypeNone = 0xFF 
} BitmapCompressionType; 

Value Descriptions

BitmapCompressionTypeScanLine
Use scan line compression. Scan line compression is compatible with Palm OS® 2.0 and higher.
BitmapCompressionTypeRLE
Use RLE compression. RLE compression is supported in Palm OS 3.5 and higher.
BitmapCompressionTypePackBits
Use PackBits compression. PackBits compression is supported in Palm OS 4.0 only.
BitmapCompressionTypeEnd
For internal use only.
BitmapCompressionTypeBest
For internal use only.
BitmapCompressionTypeNone
No compression is used.

This value should only be used as an argument to BmpCompress.

Compatibility

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

New BitmapDirectInfoType

For direct color bitmaps-each pixel is represented by an RGB triplet rather than a palette index-the BitmapDirectInfoType structure follows the color table if one is present, or immediately follows the BitmapType if a color table is not present. For direct color bitmaps, only 16 bits per pixel is supported, 5 bits for red, 6 bits for green, and 5 bits for blue.


WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapDirectInfoType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct BitmapDirectInfoType { 
  UInt8 redBits; 
  UInt8 greenBits; 
  UInt8 blueBits; 
  UInt8 reserved; 
  RGBColorType transparentColor; 
} BitmapDirectInfoType; 

Field Descriptions

redBits
Number of bits used by the red component in each pixel.
greenBits
Number of bits used by the green component in each pixel.
blueBits
Number of bits used by the blue component in each pixel.
reserved
Must be zero. Reserved for future use.
transparentcolor
Contains the red, green, and blue components of the transparent color.

Compatibility

BitmapDirectInfoType is only defined if 4.0 New Feature Set is present.

BitmapFlagsType

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


WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapFlagsType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct BitmapFlagsType { 
  UInt16 compressed:1; 
  UInt16 hasColorTable:1; 
  UInt16 hasTransparency:1; 
  UInt16 indirect:1; 
  UInt16 forScreen:1; 
  UInt16 directColor:1; 
  UInt16 reserved:10; 
} BitmapFlagsType; 

Field Descriptions

compressed
If true, the bitmap is compressed and the compressionType field specifies the compression used. If false, the bitmap is uncompressed. The BmpCompress function sets this field.
hasColorTable
If true, the bitmap has its own color table. If false, the bitmap uses the system color table. You specify whether the bitmap has its own color table when you create the bitmap.
hasTransparency
If true, the OS will not draw pixels that have a value equal to the transparentIndex. If false, the bitmap has no transparency value. You specify the transparent color when you create the bitmap using Constructor.
indirect
If true, the address to the bitmap's data is stored where the bitmap itself would normally be stored. The actual bitmap data is stored elsewhere. If false, the bitmap data is stored directly following the bitmap header or directly following the bitmap's color table if it has one.

Never set this flag. Only the display (screen) bitmap has the indirect bit set.
forScreen
If true, bitmap intended for the display (screen) window. Never set this flag.
directColor
If true, bitmap is a direct color (RGB) bitmap.
reserved
Reserved for future use.

Compatibility

Flags hasTransparency, indirect, and forScreen are only defined if 3.5 New Feature Set is present. The directColor flag is only defined if 4.0 New Feature Set is present.

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.


WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
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

width
The width of the bitmap in pixels. You specify this value when you create the bitmap. Use BmpGetDimensions to access this field.
height
The height of the bitmap in pixels. You specify this value when you create the bitmap. Use BmpGetDimensions to access this field.
rowBytes
The number of bytes stored for each row of the bitmap where height is the number of rows. Use BmpGetDimensions to access this field.
flags
The bitmap's attributes. See BitmapFlagsType.
pixelSize
The pixel depth. Currently supported pixel depths are 1, 2, 4, and 8-bit. You specify this value when you create the bitmap.
version
The version of bitmap encoding used. See Bitmap Constants.
nextDepthOffset
For bitmap families, this field specifies the start of the next bitmap in the family. The value it contains is the number of 4-byte words to the next BitmapType from the beginning of this one. If the bitmap is not part of a bitmap family or it is the last bitmap in the family, the nextDepthOffset is 0.
transparentIndex
The color index for the transparent color. Only used for version 2 bitmaps and only when the hasTransparency flag is set (see BitmapFlagsType). You specify this value when you create the bitmap using Constructor.
compressionType
The compression type used. Only used for version 2 bitmaps and only when the compressed flag is set (see BitmapFlagsType). See BitmapCompressionType for possible values. The BmpCompress function sets this field.
reserved
Reserved for future use. Must be set to 0.

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. If the bitmap has a pixel size of 16, the BitmapDirectInfoType structure is stored 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 5.14 in the User Interface chapter of the Palm OS Programmer's Companion, vol. I). When requested to draw a bitmap family, the operating system chooses the version of the bitmap with the pixel depth closest to, but not greater than, the current pixel depth of 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.

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.


WARNING! Palm, Inc. does not support or provide backward compatibility for the ColorTableType structure. Never access its structure members directly, or your code may break in future versions. Use BmpGetColortable to access this structure. Use the information below for debugging purposes only.
typedef struct ColorTableType { 
  UInt16            numEntries; 
  // RGBColorType   entry[]; 
} ColorTableType; 

Field Descriptions

numEntries
The number of entries in table. High bits (numEntries > 256) reserved.

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

ColorTableType 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

index
The index of this color in the color table. Not all functions that use RGBColorType use the index field.

Direct bitmaps support no more than 256 colors. The number of possible RGB colors greatly exceeds this amount. For this reason, some drawing functions use a color look up table (CLUT). If the CLUT is used, the index field contains the index of an available color that is the closest match to the color specified by the r, g, and b fields.

r
Amount of red (0 to 255).
g
Amount of green (0 to 255).
b
Amount of blue (0 to 255).

Compatibility

RGBColorType is defined only if 3.5 New Feature Set is present.

Bitmap Constants

Constant
Value
Description
BitmapVersionZero
0
Uses the version 0 encoding of a bitmap. Version 0 encoding is supported in Palm OS 1.0 and later.
BitmapVersionOne
1
Uses the version 1 encoding of a bitmap. Version 1 encoding is supported in Palm OS 3.0 and later.

PalmRez automatically creates version 1 bitmaps unless you have specified a transparency index or a compressed type when creating the bitmap in Constructor.
BitmapVersionTwo
2
Uses the version 2 encoding of a bitmap. Palm OS 3.5 and later supports version 2 bitmaps. Version 2 bitmaps either use the transparency index or are compressed. If you programmatically create a bitmap using BmpCreate, a version 2 bitmap is created.

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 and 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. 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 (const BitmapType *bitmapP)

Parameters

-> bitmapPPointer 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 (const BitmapType *bitmapP)

Parameters

-> bitmapPPointer 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

-> bitmapPPointer to the bitmap to compress. (See BitmapType.)
-> compTypeThe 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:

errNoneSuccess.
sysErrParamErrEither the compType parameter does not specify a compression type or the bitmap is already compressed, is in the storage heap, or represents the screen.
sysErrNoFreeResourceThere 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

-> widthThe width of the bitmap in pixels. Must not be 0.
-> heightThe height of the bitmap in pixels. Must not be 0.
-> depthThe pixel depth of the bitmap. Must be 1, 2, 4, 8, or 16. This value is used as the pixelSize field of BitmapType.
-> colortablePA 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). 16-bit bitmaps do not use a color table.
<- errorContains 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:

errNoneSuccess.
sysErrParamErrThe width, height, depth, or colorTableP parameter is invalid. See the descriptions above for acceptable values.
sysErrNoFreeResourceThere 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.

BmpCreate allocates sufficient memory on the dynamic heap to hold the bitmap and initializes all of its pixels to white. To change the bitmap's contents, use the window drawing functions. First, you must use WinCreateBitmapWindow to create an off screen window wrapper around the bitmap, then draw to that window. For example:

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 is 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); 

Bitmaps 64 Kb and greater are now supported with Palm OS 4.0.

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

-> bitmapPPointer 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 pointer fails.

Comments

Only delete bitmaps that have been 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

-> bitmapPPointer 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

New BmpGetBitDepth

Purpose

Retrieve the depth of a bitmap.

Prototype

UInt8 BmpGetBitDepth (const BitmapType* bitmapP)

Parameters

-> bitmapPPointer to a bitmap. See BitmapType.

Result

This function returns the bit depth of the bitmap, as represented by the pixelSize field in BitmapType. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetBitDepth. For more information, see Chapter 76, "PalmOSGlue Library."

See Also

BmpGetDimensions, BmpGetNextBitmap, BmpGetSizes

BmpGetColortable

Purpose

Retrieve the bitmap's color table.

Prototype

ColorTableType *BmpGetColortable (BitmapType *bitmapP)

Parameters

-> bitmapPA 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

New BmpGetDimensions

Purpose

Retrieve the width, height and number of data bytes per row of a bitmap.

Prototype

void BmpGetDimensions (const BitmapType *bitmapP, Coord *widthP, Coord *heightP, UInt16 *rowBytesP)

Parameters

-> bitmapPPointer to the bitmap. See BitmapType.
<- widthPPointer to bitmap's width in pixels. Use NULL if this information is not wanted.
<- heightPPointer to bitmap's height in pixels. Use NULL if this information is not wanted. Use NULL if this information is not wanted.
<- rowBytesPPointer to number of bytes per row of bitmap. Use NULL if this information is not wanted.

Result

This function returns the width in pixels of the bitmap in widthP, the height in pixels of the bitmap in heightP, and the number of bytes of data per row of the bitmap in rowBytesP. This function reports an error on debug ROMs if bitmapP is NULL.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetDimensions. For more information, see Chapter 76, "PalmOSGlue Library."

See Also

BmpGetBitDepth, BmpGetNextBitmap, BmpGetSizes

New BmpGetNextBitmap

Purpose

Retrieve the next bitmap type in a bitmap family.

Prototype

BitmapType *BmpGetNextBitmap(BitmapType *bitmapP)

Parameters

-> bitmapPPointer to a bitmap. See BitmapType.

Result

This function returns a pointer to the next BitmapType in a bitmap family. It returns NULL if bitmapP is the last bitmap. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetNextBitmap. For more information, see Chapter 76, "PalmOSGlue Library."

See Also

BmpGetBitDepth, BmpGetDimensions, BmpGetSizes

New BmpGetSizes

Purpose

Retrieve the size of a bitmap and its header structure.

Prototype

void BmpGetSizes (const BitmapType *bitmapP, UInt32 *dataSizeP, UInt32 *headerSizeP)

Parameters

->bitmapPPointer to the bitmap. See BitmapType.
<-dataSizePPointer to size of bitmap data, not including structures. Use NULL if this information is not wanted.
<-headerSizePPointer to size of bitmap's structures, not including data. Use NULL if this information is not wanted.

Result

Returns the size of the bitmap and the size of the bitmap's structures. This function will report an error on debug ROMs if bitmapP is NULL.

Comments

This function returns the size in bytes of the bitmap data in dataSizeP. The size does not include the data structures (BitmapType, BitmapDirectInfoType, or color table) that are associated with a bitmap. The size of the structures (in bytes) are returned in headerSizeP, which includes the size of the BitmapType, BitmapDirectInfoType (if any), the color table (if any), and the size of the pointer for indirect bitmaps (described in BitmapFlagsType).

This function should be used when working with bitmaps that may be 64 Kb or greater. Do not use BmpSize or BmpBitsSize when working with bitmaps that may be greater than or equal to 64Kb.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

BmpGetBitDepth, BmpGetDimensions, BmpGetNextBitmap

BmpSize

Purpose

Return the size of the bitmap.

Prototype

UInt16 BmpSize (const BitmapType *bitmapP)

Parameters

-> bitmapPA pointer to the bitmap. See BitmapType.

Result

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

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

-> ctPA 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[256]; 
Err e; 
  
/* allocate space for table */ 
e = WinPalette(winPaletteGet, 0, 256, tableP); 

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

BmpGetColortable