(68K) Bitmaps | Palm OS® Programmer's API Reference

This chapter provides information about bitmaps by discussing these topics:

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 ^TOP^

BitmapCompressionType Enum ^TOP^

Purpose

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().

Prototype

typedef enum {
  BitmapCompressionTypeScanLine = 0,
  BitmapCompressionTypeRLE,
  BitmapCompressionTypePackBits,
  BitmapCompressionTypeEnd,
  BitmapCompressionTypeBest = 0x64,
  BitmapCompressionTypeNone = 0xFF
} BitmapCompressionType;

Constants

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 and higher. See http://partners.adobe.com/asn/developer/pdfs/tn/TIFF6.pdf for a description of the PackBits format. (Although the TIFF spec is byte-oriented, the 16-bit algorithm is identical: just substitute "word" for "byte.")
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.

BitmapDirectInfoType Struct ^TOP^

Purpose

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! This structure is documented so that you can directly access the internals of your own bitmap resources. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast a direct color bitmap data pointer from a bitmap created by the Palm OS to this structure and expect to be able to correctly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapDirectInfoType {
  UInt8 redBits;
  UInt8 greenBits;
  UInt8 blueBits;
  UInt8 reserved;
  RGBColorType transparentColor;
} BitmapDirectInfoType;

Fields

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 Struct ^TOP^

Purpose

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

WARNING! This structure is documented so that you can directly access the internals of your own bitmap resources. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast the flags field of a bitmap created by the Palm OS to this structure and expect to be able to correctly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapFlagsType {
  UInt16 compressed:1;
  UInt16 hasColorTable:1;
  UInt16 hasTransparency:1;
  UInt16 indirect:1;
  UInt16 forScreen:1;
  UInt16 directColor:1;
  UInt16 indirectColorTable:1;
  UInt16 noDither:1;
  UInt16 reserved:8;
} BitmapFlagsType;

Fields

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, or you can specify it programmatically with BmpSetTransparentValue(). To obtain the value of this field, call BmpGetTransparentValue().
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.; Note that this flag is supported for bitmaps created by Palm OS only; this flag is not used in user-created bitmap resources.
forScreen: If true, bitmap intended for the display (screen) window. Never set this flag.; Note that this flag is supported for bitmaps created by Palm OS only; this flag is not used in user-created bitmap resources.
directColor: If true, bitmap is a direct color (RGB) bitmap.
indirectColorTable: If true, and if hasColorTable is true, a pointer to the bitmap's color table immediately follows the BitmapType structure. If false, and hasColorTable is true, the color table immediately follows the BitmapType structure. If hasColorTable is false, indirectColorTable is ignored. The indirect bit uses similar logic: if both the color table and the bitmap data are indirect, the color table pointer precedes the bitmap data pointer.; Note that this flag is supported for bitmaps created by Palm OS only; this flag is not used in user-created bitmap resources.
noDither: If true, the blitter does not dither the bitmap. If false, the source bitmap is dithered if it has a bit depth greater than the destination bitmap.
reserved: Reserved for future use.

Compatibility

The hasTransparency, indirect, and forScreen flags 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. The indirectColorTable and noDither flags are only defined if the High-Density Display Feature Set is present.

BitmapPtr Typedef ^TOP^

Purpose

The BitmapPtr type defines a pointer to a BitmapType structure.

Prototype

typedef BitmapType *BitmapPtr;

BitmapType Struct ^TOP^

Purpose

The BitmapType structure represents that which is common to all BitmapTypeVx structures (BitmapTypeV0, BitmapTypeV1, BitmapTypeV2, and BitmapTypeV3). The BitmapType structures define 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.

Because BitmapType is merely a portion of the BitmapTypeVx structures, you should never do sizeof(BitmapType).

WARNING! This structure is documented so that you can directly access the internals of your own bitmap resources. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast a bitmap created by the Palm OS to this structure and expect to be able to correctly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapType {
  Int16 width;
  Int16 height;
  UInt16 rowBytes;
  BitmapFlagsType flags;
  UInt8 pixelSize;
  UInt8 version;
} BitmapType;

typedef BitmapType *BitmapPtr;

Fields

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 obtain the contents of 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. Use BmpGetBitDepth() to access the contents of this field.
version: The version of bitmap encoding used. See "Bitmap Constants". The value in this field determines the data structure to use when interpreting the fields following version: a value of BitmapVersionZero (0) corresponds to BitmapTypeV0, BitmapVersionOne (1) corresponds to BitmapTypeV1, BitmapVersionTwo (2) corresponds to BitmapTypeV2, and BitmapVersionThree (3) corresponds to BitmapTypeV3. Use BmpGetVersion() to obtain the contents of this field.

Comments

Note the following about the BitmapType structures:

None of these fields contains the actual bitmap data. Instead, the bitmap data is stored immediately following the BitmapTypeVx (which one depends on the value of the version field) 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, and the bitmap is BitmapTypeV2, 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 "Bitmaps" of the Palm OS Programmer's Companion, vol. I). When requested to draw a bitmap family, the operating system chooses a member of the bitmap family based upon the bitmap density and pixel depth; see "Bitmap Families" for the algorithm that the High-Density Display Feature Set uses to determine which one to choose.

BitmapTypeV0 Struct ^TOP^

Purpose

Structure corresponding to the version 0 encoding of a bitmap. Version 0 encoding is supported in Palm OS 1.0 and later.

Generally you work with pointers to BitmapType structures; if the structure's version is BitmapVersionZero, the structure is of type BitmapTypeV0.

WARNING! This structure is documented so that you can directly access the internals of your own bitmap resources. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast a bitmap created by the Palm OS to this structure and expect to be able to directly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapTypeV0 {
  Int16 width;
  Int16 height;
  UInt16 rowBytes;
  BitmapFlagsType flags;
  UInt16 reserved[4];
} BitmapTypeV0;

typedef BitmapTypeV0 *BitmapPtrV0;

Fields

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. Only the compressed flag is defined for BitmapTypeV0 structures.
reserved: Reserved. These values are set to zero. Note that in the BitmapTypeV0 structure, the pixelSize and version fields, defined in BitmapType, do not exist. They coincide with the reserved array, however, and this array was initialized to zero when the bitmap was created. The operating system recognizes that a pixelSize of zero means that the bitmap's depth is 1.

Compatibility

BitmapTypeV0 is defined only if High-Density Display Feature Set is present.

BitmapTypeV1 Struct ^TOP^

Purpose

Structure corresponding to the version 1 encoding of a bitmap. Version 1 encoding is supported in Palm OS 3.0 and later.

Generally you work with pointers to BitmapType structures; if the structure's version is BitmapVersionOne, the structure is of type BitmapTypeV1.

WARNING! This structure is documented so that you can directly access the internals of your own bitmap resources. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast a bitmap created by the Palm OS to this structure and expect to be able to directly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapTypeV1 {
  Int16 width;
  Int16 height;
  UInt16 rowBytes;
  BitmapFlagsType flags;
  UInt8 pixelSize;
  UInt8 version;
  UInt16 nextDepthOffset;
  UInt16 reserved[2];
} BitmapTypeV1;

typedef BitmapTypeV1 *BitmapPtrV1;

Fields

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. Only the compressed and hasColorTable flags are defined for BitmapTypeV1 structures.
pixelSize: The pixel depth. Currently supported pixel depths are 1, 2, and 4-bit. You specify this value when you create the bitmap. Use BmpGetBitDepth to obtain the contents of this field.
version: The version of bitmap encoding used. This field has a value of BitmapVersionOne (1) for BitmapTypeV1 structures. Use BmpGetVersion() to obtain the contents of this field.
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.
reserved: Reserved.

Compatibility

BitmapTypeV1 is defined only if High-Density Display Feature Set is present.

BitmapTypeV2 Struct ^TOP^

Purpose

Structure corresponding to the version 2 encoding of a bitmap. Version 2 encoding is supported in Palm OS 3.5 and later.

Generally you work with pointers to BitmapType structures; if the structure's version is BitmapVersionTwo (2), the structure is of type BitmapTypeV2.

WARNING! This structure is documented so that you can directly access the internals of bitmaps that you create. Bitmaps created by Palm OS are not guaranteed to adhere to this structure; you cannot cast a bitmap created by the Palm OS to this structure and expect to be able to directly access the structure's fields. Always use accessor functions to access the contents of user interface structures created by Palm OS.

Prototype

typedef struct BitmapTypeV2 {
  Int16 width;
  Int16 height;
  UInt16 rowBytes;
  BitmapFlagsType flags;
  UInt8 pixelSize;
  UInt8 version;
  UInt16 nextDepthOffset;
  UInt8 transparentIndex;
  UInt8 compressionType;
  UInt16 reserved;
} BitmapTypeV2;

typedef BitmapTypeV2 *BitmapPtrV2;

Fields

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. Only the compressed, hasColorTable, hasTransparency, indirect, forScreen, and directColor flags are defined for BitmapTypeV2 structures. Note that the indirect and forScreen flags are system-only flags that are not used in user-created bitmap resources.
pixelSize: The pixel depth. Currently supported pixel depths are 1, 2, 4, 8, and 16-bit. You specify this value when you create the bitmap. Use BmpGetBitDepth() to obtain the contents of this field.
version: The version of bitmap encoding used. This field has a value of BitmapVersionTwo (2) for BitmapTypeV2 structures. Use BmpGetVersion() to obtain the contents of this field.
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, or programmatically with BmpSetTransparentValue(). To obtain the value of this field, call BmpGetTransparentValue().
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, and the BmpGetCompressionType() function obtains its value.
reserved: Reserved.

Compatibility

BitmapTypeV2 is defined only if High-Density Display Feature Set is present.

BitmapTypeV3 Struct ^TOP^

Purpose

Structure corresponding to the version 3 encoding of a bitmap. Version 3 encoding is supported if the High-Density Display Feature Set is present.

Generally you work with pointers to BitmapType structures; if the structure's version is BitmapVersionThree (3), the structure is of type BitmapTypeV3.

BmpCreate allocates and initializes a BitmapTypeV2 structure. To create a BitmapTypeV3 structure, use BmpCreateBitmapV3() and supply the data pointer and optional color table pointer.

In earlier versions of the BitmapTypeVx structure, the size of compressed bitmap data is stored in a 16-bit field preceding the bitmap data. With the version 3 structure, the size is stored in a 32-bit field.

The BitmapTypeV3 structure has fields that identify how each pixel is stored (pixelFormat) and which color, if any, is "transparent" (transparentValue). Because of this, you don't use a BitmapDirectInfoType structure in conjunction with a BitmapTypeV3 structure.

Prototype

typedef struct BitmapTypeV3 {
  Int16 width;
  Int16 height;
  UInt16 rowBytes;
  BitmapFlagsType flags;
  UInt8 pixelSize;
  UInt8 version;
  UInt8 size;
  UInt8 pixelFormat;
  UInt8 unused;
  UInt8 compressionType;
  UInt16 density;
  UInt32 transparentValue;
  UInt32 nextBitmapOffset;
} BitmapTypeV3;

typedef BitmapTypeV3 *BitmapPtrV3;

Fields

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. Note that the indirect, forScreen, and indirectColorTable flags are system-only fields that are not used in user-created bitmap resources.
pixelSize: The pixel depth. Currently supported pixel depths are 1, 2, 4, and 8-bit. You specify this value when you create the bitmap. Use BmpGetBitDepth() to obtain the value of this field.
version: The version of bitmap encoding used. This field has a value of BitmapVersionThree (3) for BitmapTypeV3 structures. The high bit of the version field is set if the bitmap data structure uses the native ARM format, with little-endian fields. Bitmap.h contains a bit mask, BitmapVersionMaskLE, that can be used to detect this. Use BmpGetVersion() to obtain the value of this field.
size: The size of this structure, in bytes. This field does not include the size of the color table or the size of the bitmap data. Use BmpGetSizes() to obtain the value of this field.
pixelFormat: An enumerated constant representing the format of the pixel data. See PixelFormatType for the supported values.
unused: Not used.
compressionType: The compression type used; 0 if the bitmap is not compressed. Only used when the compressed flag is set (see BitmapFlagsType). See BitmapCompressionType for possible values. The BmpCompress() function sets this field, and the BmpGetCompressionType() function obtains its value.
density: Value used by the blitter to determine how to stretch or shrink the bitmap data. For the screen bitmap, this field represents the screen density. For handhelds with low-density displays, this field is initialized to kDensityLow. For handhelds with double-density displays, this field is initialized to kDensityDouble. See DensityType for the full set of values that this field can assume. Set this field with BmpSetDensity(), and obtain its value with BmpGetDensity().
transparentValue: If this structure represents a bitmap with a bit depth of 8 or less, this field contains the bitmap's transparent index. If the bitmap has a bit depth of 16, the 16-bit transparent RGB color is stored in this field. You specify this value when you create the bitmap using Constructor, or programmatically with BmpSetTransparentValue() To obtain the value of this field, call BmpGetTransparentValue().
nextBitmapOffset: A 32-bit value that indicates the number of bytes to the next bitmap in the family. If the bitmap is not part of a bitmap family or it is the last bitmap in the family, the nextBitmapOffset is 0.

Compatibility

BitmapTypeV3 is defined only if High-Density Display Feature Set is present.

ColorTableType Struct ^TOP^

Purpose

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! PalmSource, 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.

Prototype

typedef struct ColorTableType {
  UInt16 numEntries;
  // RGBColorType entry[];
} ColorTableType;

Fields

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.

DensityType Enum ^TOP^

Purpose

The density of the bitmap (see "Display Density" of the Palm OS Programmer's Companion, vol. I for a definition of display density). Density is only supported in BitmapType structures with a version greater than 2; if a given BitmapType structure is version 2 or lower, it is assumed to contain low-density data.

The blitter uses the density field in the source and destination bitmaps to determine an appropriate scaling factor. When scaling down from a density of kDensityDouble to kDensityLow, the blitter must shrink the bitmap data. This will almost always result in a poorer-quality image when compared with a bitmap that was created with a density of kDensityLow.

The various DensityType values should not be interpreted as representing pixels per inch.

Prototype

typedef enum {
  kDensityLow = 72,
  kDensityOneAndAHalf = 108,
  kDensityDouble = 144,
  kDensityTriple = 216,
  kDensityQuadruple = 288
} DensityType

Constants

kDensityLow: Low (single) density. A low-density screen is 160x160 pixels.
kDensityOneAndAHalf: "One and a half" density. A one-and-a-half-density display is 240x240 pixels; this would most likely be used on a handheld with a 240x320 screen where the bottom portion is used as a dynamic input area.
kDensityDouble: Double density when compared with kDensityLow. A double-density screen is 320x320 pixels.
kDensityTriple: Triple density when compared with kDensityLow. A triple-density screen is 480x480 pixels.
kDensityQuadruple: Quadruple density when compared with kDensityLow. A quadruple-density screen is 640x640 pixels.

IMPORTANT: Not all densities listed in the DensityType enum are supported by a given version of the High-Density Display feature set. For Palm OS Garnet, only kDensityLow, kDensityOneAndAHalf, and kDensityDouble are supported.

Compatibility

DensityType is defined only if High-Density Display Feature Set is present.

PixelFormatType Enum ^TOP^

Purpose

Pixel formats defined for use with BitmapTypeV3 structures.

Prototype

typedef enum {
  pixelFormatIndexed,
  pixelFormat565
  pixelFormat565LE,
  pixelFormatIndexedLE
} PixelFormatType;

Constants

pixelFormatIndexed: Each pixel is represented by a palette index.
pixelFormat565: Each pixel is represented by an RGB triplet stored in 16-bits: 5 red bits, 6 green bits, and 5 blue bits.
pixelFormat565LE: Similar to pixelFormat565, except that the 16 bits of the RGB triplet are stored as little-endian. This pixel format is not supported in user-created bitmaps.
pixelFormatIndexedLE: Similar to pixelFormatIndexed, except that the pixels within a byte are stored as little-endian. This pixel format is not supported in user-created bitmaps.

Compatibility

PixelFormatType is defined only if High-Density Display Feature Set is present.

RGBColorType Struct ^TOP^

Purpose

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.

Prototype

typedef struct RGBColorType {
  UInt8 index;
  UInt8 r;
  UInt8 g;
  UInt8 b;
} RGBColorType;

Fields

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 ^TOP^

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.
BitmapVersionThree = 3: Uses the version 3 encoding of a bitmap. Version 3 bitmaps are supported only if the High-Density Display Feature Set is present.

Bitmap Resources ^TOP^

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 ^TOP^

BmpBitsSize Function ^TOP^

Purpose

Return the size of the bitmap's data.

Declared In

Bitmap.h

Prototype

UInt16 BmpBitsSize (
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to the bitmap. (See BitmapType.)

Returns

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.

BmpColortableSize Function ^TOP^

Purpose

Return the size of the bitmap's color table.

Declared In

Bitmap.h

Prototype

UInt16 BmpColortableSize(
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to the bitmap. (See BitmapType.)

Returns

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.

BmpCompress Function ^TOP^

Purpose

Compress or uncompress a bitmap.

Declared In

Bitmap.h

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.

Returns

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.
sysErrNoFreeResource: 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. From Palm OS Garnet version 5.0 onwards this function does nothing; errNone is always returned.

BmpCreate Function ^TOP^

Purpose

Create a bitmap.

Declared In

Bitmap.h

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, 8, or 16. 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). 16-bit bitmaps do not use a color table.
← error: Contains the error code if an error occurs.

Returns

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.
sysErrNoFreeResource: 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. To create aBitmapVersionThree bitmap use BmpCreate and pass the results to BmpCreateBitmapV3().

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.

BmpCreateBitmapV3 Function ^TOP^

Purpose

Create a version 3 bitmap from an existing bitmap, an existing set of data bits, and, optionally, a color table.

Declared In

Bitmap.h

Prototype

BitmapTypeV3 *BmpCreateBitmapV3(
   const BitmapType *bitmapP,
   UInt16 density,
   const void *bitsP,
   const ColorTableType *colorTableP
)

Parameters

→ bitmapP: Pointer to a valid bitmap from which the version 3 bitmap is to be created. See BitmapType.
→ density: Density of the returned bitmap. If 0, the returned bitmap's density is set to the default value of kDensityLow.
→ bitsP: Pointer to the bitmap image data. Note that the bitmap data can be located in the storage heap, but then the bitmap should be treated as read-only. You must use DmWrite to write to the storage heap; blitting to it causes a system error.
→ colorTableP: Pointer to a color table, or NULL to use bitmapP's color table, if one exists.

Returns

Returns a version 3 bitmap, or NULL if the bitmap could not be created from the specified bitmap, bitmap data, and optional color table.

Comments

You can use this function when the bitmap data is stored in the storage heap as bands of raster data. Rather than allocating several bitmap structures, one for each band, use this function to allocate a single bitmap, and have the structure point to each band successively. This is typically used with high-density bitmaps that cannot be stored entirely within 64k.

WARNING! Due to a limitation in the way that this function is implemented, BitmapCreateBitmapV3 doesn't work with compressed bitmaps. Don't pass bitmaps to this function that have the compressed flag set.

The returned bitmap structure is allocated from the system heap. After your application is done with it, dispose of it by calling BmpDelete().

Compatibility

Implemented only if the High-Density Display Feature Set is present.

BmpDelete Function ^TOP^

Purpose

Delete a bitmap structure.

Declared In

Bitmap.h

Prototype

Err BmpDelete (
   BitmapType *bitmapP
)

Parameters

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

Returns

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 Function ^TOP^

Purpose

Retrieve the bitmap's data.

Declared In

Bitmap.h

Prototype

void *BmpGetBits (
   BitmapType *bitmapP
)

Parameters

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

Returns

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.

BmpGetBitDepth Function ^TOP^

Purpose

Retrieve the depth of a bitmap.

Declared In

Bitmap.h

Prototype

UInt8 BmpGetBitDepth (
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a bitmap. See BitmapType.

Returns

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 80, "PalmOSGlue Library."

BmpGetColortable Function ^TOP^

Purpose

Retrieve the bitmap's color table.

Declared In

Bitmap.h

Prototype

ColorTableType *BmpGetColortable(
   BitmapType *bitmapP
)

Parameters

→ bitmapP: A pointer to the bitmap. See BitmapType.

Returns

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.

BmpGetCompressionType Function ^TOP^

Purpose

Get the compression type of a bitmap.

Declared In

Bitmap.h

Prototype

BitmapCompressionType BmpGetCompressionType(
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.

Returns

Returns the type of compression used by bitmapP. See "BitmapCompressionType" for the values that can be returned from this function. For debug ROMs, this function reports an error and returns BitmapCompressionTypeNone if bitmapP is NULL.

Comments

If the bitmap is not compressed, this function returns BitmapCompressionTypeNone. If the bitmap version is 0 or 1 (corresponding to BitmapTypeV0 and BitmapTypeV1, respectively), it returns BitmapCompressionTypeScanLine.

Compatibility

Implemented only if either the if 5.0 New Feature Set or the High-Density Display Feature Set is present.

BmpGetDensity Function ^TOP^

Purpose

Get the density of a bitmap.

Declared In

Bitmap.h

Prototype

UInt16 BmpGetDensity (
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.

Returns

Returns the density of bitmapP; see the DensityType enum for the defined set of density values. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL.

Comments

Note that bitmaps with a version of 0, 1, or 2 (corresponding to BitmapTypeV0, BitmapTypeV1, and BitmapTypeV2, respectively) are assumed to be low density (kDensityLow).

Compatibility

Implemented only if the High-Density Display Feature Set is present.

BmpGetDimensions Function ^TOP^

Purpose

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

Declared In

Bitmap.h

Prototype

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

Parameters

→ bitmapP: Pointer to the bitmap. See BitmapType.
← widthP: Pointer to bitmap's width in pixels. Use NULL if this information is not wanted.
← heightP: Pointer to bitmap's height in pixels. Use NULL if this information is not wanted. Use NULL if this information is not wanted.
← rowBytesP: Pointer to number of bytes per row of bitmap. Use NULL if this information is not wanted.

Returns

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 80, "PalmOSGlue Library."

BmpGetNextBitmap Function ^TOP^

Purpose

Retrieve the next low-density bitmap in a bitmap family.

Declared In

Bitmap.h

Prototype

BitmapType *BmpGetNextBitmap(
   BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a bitmap. See BitmapType.

Returns

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

Comments

This function is only supported for low-density bitmap families. For families with both low and high-density bitmaps (BitmapTypeV3), use BmpGetNextBitmapAnyDensity().

In a BitmapTypeV3, a dummy low-density BitmapType precedes any high-density bitmaps. If you pass a pointer to the last valid low-density bitmap within a BitmapTypeV3 structure, BmpGetNextBitmap returns a pointer to the dummy bitmap. If you then pass that pointer to BmpGetDimensions(), it returns the dimensions for the first high-density bitmap rather than the dummy bitmap. To avoid confusion, it is best to use BmpGetNextBitmapAnyDensity when iterating through a family and gathering information about each bitmap.

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 80, "PalmOSGlue Library."

BmpGetNextBitmapAnyDensity Function ^TOP^

Purpose

Get the next bitmap in the bitmap family, irrespective of density.

Declared In

Bitmap.h

Prototype

BitmapType *BmpGetNextBitmapAnyDensity(
   BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.

Returns

Returns the next bitmap in a bitmap family, or NULL if bitmapP is the last bitmap. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL.

Comments

This function is an extended version of BmpGetNextBitmap(). For backward compatibility, BmpGetNextBitmap only returns low-density bitmaps. If the bitmap family contains high-density bitmaps, however, BitmapGetNextBitmapAnyDensity skips over the dummy bitmap that separates the low and high-density bitmaps in the linked list and returns a high-density bitmap.

Compatibility

Implemented only if the High-Density Display Feature Set is present.

BmpGetSizes Function ^TOP^

Purpose

Retrieve the size of a bitmap and its header structure.

Declared In

Bitmap.h

Prototype

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

Parameters

→ bitmapP: Pointer to the bitmap. See BitmapType.
← dataSizeP: Pointer to size of bitmap data, not including structures. Use NULL if this information is not wanted.
← headerSizeP: Pointer to size of bitmap's structures, not including data. Use NULL if this information is not wanted.

Returns

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.

BmpGetTransparentValue Function ^TOP^

Purpose

Get a bitmap's transparent color.

Declared In

Bitmap.h

Prototype

Boolean BmpGetTransparentValue(
   const BitmapType *bitmapP,
   UInt32 *transparentValueP
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.
← transparentValueP: Pointer to a variable that receives the transparent color, either as a palette index or as a direct color value (an RGB565 value), depending on the bitmap's depth.

Returns

Returns true if bitmapP has a transparent color defined, false otherwise.

Compatibility

Implemented only if either the if 5.0 New Feature Set or the High-Density Display Feature Set is present.

BmpGetVersion Function ^TOP^

Purpose

Get the version of a bitmap.

Declared In

Bitmap.h

Prototype

UInt8 BmpGetVersion (
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.

Returns

Returns the version of bitmapP. See"Bitmap Constants" for the defined bitmap version numbers. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL.

Compatibility

Implemented only if the High-Density Display Feature Set is present.

BmpSetDensity Function ^TOP^

Purpose

Set the density of a version 3 bitmap.

Declared In

Bitmap.h

Prototype

Err BmpSetDensity (
   BitmapType *bitmapP,
   UInt16 density
)

Parameters

→ bitmapP: Pointer to a valid version 3 bitmap. See BitmapTypeV3.
→ density: The bitmap's density. This value should be one of the values defined by the DensityType enum.

Returns

Returns errNone if the operation completed successfully, or SysErrParamErr either if bitmapP is NULL, if density is not supported by the blitter, or if *bitmapP is not a version 3 bitmap.

Comments

To allocate a high-density bitmap, first call BmpCreateBitmapV3(). Then call BmpSetDensity to specify the bitmap's density.

Compatibility

Implemented only if the High-Density Display Feature Set is present.

BmpSetTransparentValue Function ^TOP^

Purpose

Set a bitmap's transparent color.

Declared In

Bitmap.h

Prototype

void BmpSetTransparentValue (
   BitmapType *bitmapP,
   UInt32 transparentValue
)

Parameters

→ bitmapP: Pointer to a valid bitmap. See BitmapType.
→ transparentValue: Transparent color. This should either be a palette index or a direct color value (an RGB565 value), depending on the bitmap's depth.

Returns

Returns nothing.

Comments

If bitmapP points to a version 2 bitmap, BmpSetTransparentValue sets the BitmapTypeV2 structure's hasTransparency flag to true and initializes the structure's transparentIndex field according to transparentValue. For 16-bit bitmaps, this function sets the transparentColor field in the BitmapDirectInfoType auxiliary structure and sets the transparentIndex field to 0.

If bitmapP points to a version 3 bitmap, BmpSetTransparentValue sets the BitmapTypeV3 structure's hasTransparency flag to true and sets the transparentValue field to the transparent color.

Regardless of the bitmap version, if this function is passed a transparentValue set to kTransparencyNone, this function sets the bitmap structure's hasTransparency flag to false and sets the transparent color field(s) to 0.

This function does nothing if transparentValue contains a value that is not valid for the depth of bitmapP.

Compatibility

Implemented only if either the if 5.0 New Feature Set or the High-Density Display Feature Set is present.

BmpSize Function ^TOP^

Purpose

Return the size of the bitmap.

Declared In

Bitmap.h

Prototype

UInt16 BmpSize (
   const BitmapType *bitmapP
)

Parameters

→ bitmapP: A pointer to the bitmap. See BitmapType.

Returns

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.

ColorTableEntries Macro ^TOP^

Purpose

Returns the color table.

Declared In

Bitmap.h

Prototype

#define ColorTableEntries (
   ctP
)

Parameters

→ ctP: A pointer to a ColorTableType structure.

Returns

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.

26 Bitmaps

Bitmap Data Structures ^TOP^

BitmapCompressionType Enum ^TOP^

Purpose

Prototype

Constants

Compatibility

BitmapDirectInfoType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

BitmapFlagsType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

BitmapPtr Typedef ^TOP^

Purpose

Prototype

BitmapType Struct ^TOP^

Purpose

Prototype

Fields

Comments

BitmapTypeV0 Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

BitmapTypeV1 Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

BitmapTypeV2 Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

BitmapTypeV3 Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

ColorTableType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

DensityType Enum ^TOP^

Purpose

Prototype

Constants

Compatibility

PixelFormatType Enum ^TOP^

Purpose

Prototype

Constants

Compatibility

RGBColorType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

Bitmap Constants ^TOP^

Bitmap Resources ^TOP^

Bitmap Functions ^TOP^

BmpBitsSize Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

BmpColortableSize Function ^TOP^

Purpose

Declared In