Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

12    Bitmap Reference

User Interface

Exploring Palm OS®

This chapter provides information about bitmaps by discussing these topics:

Bitmap Structures and Types
Bitmap Constants
Bitmap Functions and Macros

The header files Bitmap.h and CmnBitmapTypes.h declare the API that this chapter describes. For more information on bitmaps, see Chapter 9, "Working with Bitmaps."

Bitmap Structures and Types ^TOP^

BitmapDirectInfoType Struct ^TOP^

Purpose

Specifies how colors are stored in a BitmapTypeV2 direct color bitmap.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapDirectInfoType {
   uint8_t redBits;
   uint8_t greenBits;
   uint8_t blueBits;
   uint8_t 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.

Comments

For direct color bitmaps, where 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.

BitmapType Struct ^TOP^

Purpose

Represents the portions of a bitmap that are common to all versions of the bitmap resource supported by Palm OS. The BitmapPtr type defines a pointer to a BitmapType structure.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapType {
   int16_t widthBE16;
   int16_t heightBE16;
   uint16_t rowBytesBE16;
   uint16_t flagsBE16;
   uint8_t pixelSize;
   uint8_t version;
} BitmapType;
typedef BitmapType *BitmapPtr

Fields

widthBE16
The width of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
heightBE16
The height of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
rowBytesBE16
The number of bytes stored for each row of the bitmap where heightBE16 is the number of rows, given in big-endian format. Use BmpGetDimensions() to obtain the contents of this field.
flagsBE16
The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants.
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 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

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 that you create using a resource editor 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.

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 FormBitmapType or the internal window structure 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 "Bitmap Families"). 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 "Displaying Bitmaps from a Bitmap Family" for the algorithm that Palm OS 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.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapTypeV0 {
   int16_t widthBE16;
   int16_t heightBE16;
   uint16_t rowBytesBE16;
   uint16_t flagsBE16;
   uint16_t reservedBE16[4];
} BitmapTypeV0;
typedef BitmapTypeV0 *BitmapPtrV0

Fields

widthBE16
The width of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
heightBE16
The height of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
rowBytesBE16
The number of bytes, given in big-endian format, stored for each row of the bitmap where heightBE16 is the number of rows. Use BmpGetDimensions() to access this field.
flagsBE16
The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Only the bmpFlagsCompressed flag is defined for BitmapTypeV0 structures.
reservedBE16
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.

Comments

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.

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.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapTypeV1 {
   int16_t widthBE16;
   int16_t heightBE16;
   uint16_t rowBytesBE16;
   uint16_t flagsBE16;
   uint8_t pixelSize;
   uint8_t version;
   uint16_t nextDepthOffsetBE16;
   uint16_t reservedBE16[2];
} BitmapTypeV1;
typedef BitmapTypeV1 *BitmapPtrV1

Fields

widthBE16
The width of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
heightBE16
The height of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
rowBytesBE16
The number of bytes, given in big-endian format, stored for each row of the bitmap where heightBE16 is the number of rows. Use BmpGetDimensions() to access this field.
flagsBE16
The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Only the bmpFlagsCompressed and bmpFlagsHasColorTable flags are defined for BitmapTypeV1 structures.
pixelSize
The pixel depth. 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.
nextDepthOffsetBE16
For bitmap families, this field specifies the start of the next bitmap in the family and is given in big-endian format. 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 nextDepthOffsetBE16 is 0.
reservedBE16
Reserved.

Comments

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.

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.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapTypeV2 {
   int16_t widthBE16;
   int16_t heightBE16;
   uint16_t rowBytesBE16;
   uint16_t flagsBE16;
   uint8_t pixelSize;
   uint8_t version;
   uint16_t nextDepthOffsetBE16;
   uint8_t transparentIndex;
   uint8_t compressionType;
   uint16_t reservedBE16;
} BitmapTypeV2;
typedef BitmapTypeV2 *BitmapPtrV2

Fields

widthBE16
The width of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
heightBE16
The height of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
rowBytesBE16
The number of bytes, given in big-endian format, stored for each row of the bitmap where heightBE16 is the number of rows. Use BmpGetDimensions() to access this field.
flagsBE16
The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Only the bmpFlagsCompressed, bmpFlagsHasColorTable, bmpFlagsHasTransparency, bmpFlagsIndirect, bmpFlagsForScreen, and bmpFlagsDirectColor flags are defined for BitmapTypeV2 structures. Note that the bmpFlagsIndirect and bmpFlagsForScreen flags are system-only flags that are not used in user-created bitmap resources.
pixelSize
The pixel depth. 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.
nextDepthOffsetBE16
For bitmap families, this field specifies the start of the next bitmap in the family and is given in big-endian format. 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 nextDepthOffsetBE16 is 0.
transparentIndex
The color index for the transparent color. Only used for version 2 bitmaps and only when the bmpFlagsHasTransparency flag is set (see Bitmap Flag Constants). You specify this value when you create the bitmap using a resource editor, or you can set it programmatically with BmpSetTransparentValue(). To obtain the value of this field, call BmpGetTransparentValue().
compressionType
The compression type used. Only used when the bmpFlagsCompressed flag is set. See BitmapCompressionType for possible values. The BmpCompress() function sets this field, and the BmpGetCompressionType() function obtains its value.
reservedBE16
Reserved.

Comments

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.

BitmapTypeV3 Struct ^TOP^

Purpose

Structure corresponding to the version 3 encoding of a bitmap. Version 3 encoding is supported on high-density devices.

Declared In

CmnBitmapTypes.h

Prototype

typedef struct BitmapTypeV3 {
   int16_t widthBE16;
   int16_t heightBE16;
   uint16_t rowBytesBE16;
   uint16_t flagsBE16;
   uint8_t pixelSize;
   uint8_t version;
   uint8_t size;
   uint8_t pixelFormat;
   uint8_t unused;
   uint8_t compressionType;
   uint16_t densityBE16;
   uint32_t transparentValueBE32;
   uint32_t nextBitmapOffsetBE32;
} BitmapTypeV3;
typedef BitmapTypeV3 *BitmapPtrV3

Fields

widthBE16
The width of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
heightBE16
The height of the bitmap in pixels, given in big-endian format. You specify this value when you create the bitmap. Use BmpGetDimensions() to access this field.
rowBytesBE16
The number of bytes, given in big-endian format, stored for each row of the bitmap where heightBE16 is the number of rows. Use BmpGetDimensions() to access this field.
flagsBE16
The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Note that the bmpFlagsIndirect, bmpFlagsForScreen, and bmpFlagsIndirectColorTable 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, 8, and 16-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. 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.
unused
Not used.
compressionType
The compression type used; 0 if the bitmap is not compressed. Only used when the bmpFlagsCompressed flag is set. See BitmapCompressionType for possible values. The BmpCompress() function sets this field, and the BmpGetCompressionType() function obtains its value.
densityBE16
Value that determines how to stretch or shrink the bitmap data, given in big-endian format. For devices with low-density displays, this field is initialized to kDensityLow. For devices 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().
transparentValueBE32
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 in big-endian format. You specify this value when you create the bitmap using a resource editor, or you can set it programmatically with BmpSetTransparentValue() To obtain the value of this field, call BmpGetTransparentValue().
nextBitmapOffsetBE32
A 32-bit big-endian 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 nextBitmapOffsetBE32 is 0.

Comments

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 BitmapTypeV3 bitmap use BmpCreate and pass the results to BmpCreateBitmapV3().

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" (transparentValueBE32). Because of this, you don't use a BitmapDirectInfoType structure in conjunction with a BitmapTypeV3 structure.


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.

ColorTableType Struct ^TOP^

Purpose

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

Declared In

CmnBitmapTypes.h

Prototype

typedef struct ColorTableType {
   uint16_t entryCount;
} ColorTableType

Fields

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

Comments

The color table entries themselves are of type RGBColorType, and there is one per entryCount. 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.


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 above for debugging purposes only.

RGBColorType Struct ^TOP^

Purpose

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

Declared In

CmnBitmapTypes.h

Prototype

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

Fields

index
The index of this color in the color table. Not all functions that use RGBColorType use the index field.
Indexed color 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).

See Also

GcColorType

Bitmap Constants ^TOP^

Bitmap Version Constants ^TOP^

Purpose

Specifies the version of encoding used for BitmapType.

Declared In

CmnBitmapTypes.h

Constants

#define BitmapVersionZero 0
Uses the version 0 encoding of a bitmap.
#define BitmapVersionOne 1
Uses the version 1 encoding of a bitmap.
#define BitmapVersionTwo 2
Uses the version 2 encoding of a bitmap. 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.
#define BitmapVersionThree 3
Uses the version 3 encoding of a bitmap. Version 3 bitmaps are supported only on high-density displays. You can programmatically create a version 3 bitmap using BmpCreateBitmapV3().

Bitmap Flag Constants ^TOP^

Purpose

Flags used in the flagsBE16 field of the BitmapType structure.

Declared In

CmnBitmapTypes.h

Constants

#define bmpFlagsCompressed 0x8000
If set, the bitmap is compressed and the compressionType field specifies the compression used. If not set, the bitmap is uncompressed. The BmpCompress() function sets this flag.
#define bmpFlagsDirectColor 0x0400
If set, the bitmap is a direct color (RGB) bitmap.
#define bmpFlagsForScreen 0x0800
If set, the bitmap is intended for the display (screen) window. This flag is never set.
Note that this flag is supported for bitmaps created by Palm OS only; this flag is not used in user-created bitmap resources.
#define bmpFlagsHasColorTable 0x4000
If set, the bitmap has its own color table. You specify whether the bitmap has its own color table when you create the bitmap.
#define bmpFlagsHasTransparency 0x2000
If set, the OS does not draw pixels that have a value equal to the transparency color. If not set, the bitmap has no transparency value. You specify the transparent color when you create the bitmap.
#define bmpFlagsIndirect 0x1000
If set, 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 not set, the bitmap data is stored directly following the bitmap header or directly following the bitmap's color table if it has one.
Note that this flag is supported for bitmaps created by Palm OS only; this flag is not used in user-created bitmap resources.
#define bmpFlagsIndirectColorTable 0x0200
If set and if bmpFlagsHasColorTable is set, a pointer to the bitmap's color table immediately follows the BitmapType structure. If not set, and bmpFlagsHasColorTable is true, the color table immediately follows the BitmapType structure. If bmpFlagsHasColorTable is not set, this flag is ignored. The bmpFlagsIndirect 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.
#define bmpFlagsNoDither 0x0100
If set, the rendering system does not dither the bitmap. If not set, the source bitmap is dithered if it has a bit depth greater than the destination bitmap.

BitmapCompressionType Typedef ^TOP^

Purpose

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

Declared In

CmnBitmapTypes.h

Prototype

typedef Enum8 BitmapCompressionType

Constants

BitmapCompressionTypeScanLine = 0
Use scan line compression.
BitmapCompressionTypeRLE
Use RLE compression.
BitmapCompressionTypePackBits
Use PackBits compression.
BitmapCompressionTypeEnd
For internal use only.
BitmapCompressionTypeBest = 0x64
For internal use only.
BitmapCompressionTypeNone = 0xFF
No compression is used.
This value should only be used as an argument to BmpCompress().

DensityType Typedef ^TOP^

Purpose

The density of the bitmap (see Chapter 1, "The Display," for a definition of display density).

Declared In

CmnBitmapTypes.h

Prototype

typedef Enum16 DensityType

Constants

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

Comments


IMPORTANT: Not all densities listed in the DensityType enum are supported by a given version of Palm OS. For Palm OS Cobalt version 6.0, only kDensityLow and kDensityDouble are currently supported.

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.

Palm OS 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, Palm OS 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 kDensityLow value of 72 is arbitrary. Although this value doesn't necessarily represent pixels per inch, it is useful to think of it that way.

PixelFormatType Typedef ^TOP^

Purpose

Pixel formats defined for use with BitmapTypeV3 structures.

Declared In

CmnBitmapTypes.h

Prototype

typedef Enum8 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.
pixelFormat5551
Each pixel is represented by an RGB plus alpha quadruplet stored in 16 bits: 5 red bits, 5 green bits, 5 blue bits, and one bit specifying if the color is opaque or not.
pixelFormat4444
Each pixel is represented by an RGB plus alpha quadruplet stored in 16 bits: 4 red bits, 4 green bits, 4 blue bits, and 4 bits of alpha, which specifies how transparent the color is.

Miscellaneous Bitmap Constants ^TOP^

Purpose

Other constants defined in CmnBitmapTypes.h.

Declared In

CmnBitmapTypes.h

Constants

#define colorTableHeaderSize 2
The size in bytes of the color table header. This is used when determining a bitmap's data size.
#define kTransparencyNone ((uint32_t)0xFFFFFFFF)
A value that specifies that the bitmap does not define a transparency color.

Bitmap Functions and Macros ^TOP^

BmpColortableSize Function ^TOP^

Purpose

Returns the size of the bitmap's color table.

Declared In

Bitmap.h

Prototype

uint16_t BmpColortableSize (
   const BitmapType *bitmapP
)

Parameters

bitmapP
Pointer to the bitmap. (See BitmapType.)

Returns

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

See Also

BmpSize(), BmpGetColortable()

BmpCompress Function ^TOP^

Purpose

Does nothing. Previously called to compress or uncompress a bitmap.

Declared In

Bitmap.h

Prototype

status_t 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

Always returns errNone.

BmpCreate Function ^TOP^

Purpose

Creates a bitmap.

Declared In

Bitmap.h

Prototype

BitmapType *BmpCreate (
   Coord width,
   Coord height,
   uint8_t depth,
   ColorTableType *colortableP,
   status_t *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 does 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 any color table.
error
Contains the error code if an error occurs.

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 a BitmapVersionThree bitmap, use BmpCreate and pass the results to BmpCreateBitmapV3().

If you pass a color table, the bitmap's bmpFlagsHasColorTable flag is set. For performance reasons, attaching a custom color table to a bitmap is strongly discouraged. An alternative is to use the WinPalette() function 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 to hold the bitmap and initializes all of its pixels to white. To change the bitmap's contents, use the drawing functions. See "Creating a Bitmap Programmatically."

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

See Also

BmpDelete()

BmpCreateBitmapV3 Function ^TOP^

Purpose

Creates 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_t 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 a database, 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

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 64 KB.


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 bmpFlagsCompressed flag set.

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

See Also

BmpCreate()

BmpDelete Function ^TOP^

Purpose

Deletes a bitmap structure.

Declared In

Bitmap.h

Prototype

status_t BmpDelete (
   BitmapType *bitmapP
)

Parameters

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

Returns

errNone upon success, or one of the following values:

sysErrParamErr
If the bitmap's bmpFlagsForScreen 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.

BmpGetBitDepth Function ^TOP^

Purpose

Retrieves the depth of a bitmap.

Declared In

Bitmap.h

Prototype

uint8_t BmpGetBitDepth (
   const BitmapType *bitmapP
)

Parameters

bitmapP
Pointer to a bitmap. See BitmapType.

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.

See Also

BmpGetDimensions(), BmpGetNextBitmap(), BmpGetSizes()

BmpGetBits Function ^TOP^

Purpose

Retrieves the bitmap's data.

Declared In

Bitmap.h

Prototype

void *BmpGetBits (
   BitmapType *bitmapP
)

Parameters

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

Returns

A pointer to the bitmap's data.

Comments

This function returns the bitmap's data even if the bitmap's bmpFlagsIndirect flag is set. (See Bitmap Flag Constants.)

See Also

BmpGetBits()

BmpGetColortable Function ^TOP^

Purpose

Retrieves the bitmap's color table.

Declared In

Bitmap.h

Prototype

ColorTableType *BmpGetColortable (
   BitmapType *bitmapP
)

Parameters

bitmapP
A pointer to the bitmap. See BitmapType.

Returns

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

See Also

BmpColortableSize(), ColorTableEntries()

BmpGetCompressionType Function ^TOP^

Purpose

Gets 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

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.

See Also

BmpCompress()

BmpGetDensity Function ^TOP^

Purpose

Gets the density of a bitmap.

Declared In

Bitmap.h

Prototype

uint16_t BmpGetDensity (
   const BitmapType *bitmapP
)

Parameters

bitmapP
Pointer to a valid bitmap. See BitmapType.

Returns

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

Comments

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

See Also

BmpCreateBitmapV3(), BmpSetDensity()

BmpGetDimensions Function ^TOP^

Purpose

Retrieves 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_t *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.
rowBytesP
Pointer to number of bytes per row of bitmap. Use NULL if this information is not wanted.

Returns

Nothing. This function reports an error on debug ROMs if bitmapP is NULL.

See Also

BmpGetBitDepth(), BmpGetNextBitmap(), BmpGetSizes()

BmpGetNextBitmap Function ^TOP^

Purpose

Retrieves 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

A pointer to the next low-density 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.

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.

See Also

BmpGetBitDepth(), BmpGetDimensions(), BmpGetSizes()

BmpGetNextBitmapAnyDensity Function ^TOP^

Purpose

Gets 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

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, BmpGetNextBitmapAnyDensity() skips over the dummy bitmap that separates the low and high-density bitmaps in the linked list and returns a high-density bitmap.

See Also

BmpGetDensity(), BmpGetNextBitmap()

BmpGetPixelFormat Function ^TOP^

Purpose

Returns the pixel format used by the bitmap.

Declared In

Bitmap.h

Prototype

PixelFormatType BmpGetPixelFormat (
   const BitmapType *bitmapP
)

Parameters

bitmapP
Pointer to the bitmap. See BitmapType.

Returns

One of the PixelFormatType constants.

BmpGetSizes Function ^TOP^

Purpose

Retrieves the size of a bitmap and its header structure.

Declared In

Bitmap.h

Prototype

void BmpGetSizes (
   const BitmapType *bitmapP,
   uint32_t *dataSizeP,
   uint32_t *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

Nothing.

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 Bitmap Flag Constants).

This function displays an error on debug ROMs if bitmapP is NULL.

See Also

BmpGetBitDepth(), BmpGetDimensions(), BmpGetNextBitmap()

BmpGetTransparentValue Function ^TOP^

Purpose

Gets a bitmap's transparent color.

Declared In

Bitmap.h

Prototype

Boolean BmpGetTransparentValue (
   const BitmapType *bitmapP,
   uint32_t *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

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

See Also

BmpSetTransparentValue()

BmpGetVersion Function ^TOP^

Purpose

Gets the version of a bitmap.

Declared In

Bitmap.h

Prototype

uint8_t BmpGetVersion (
   const BitmapType *bitmapP
)

Parameters

bitmapP
Pointer to a valid bitmap. See BitmapType.

Returns

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

BmpSetDensity Function ^TOP^

Purpose

Sets the density of a version 3 bitmap.

Declared In

Bitmap.h

Prototype

status_t BmpSetDensity (
   BitmapType *bitmapP,
   uint16_t 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

errNone upon success, or sysErrParamErr either if bitmapP is NULL, if density is not supported, or if bitmapP is not a version 3 bitmap.

Comments

To allocate a high-density bitmap, first call BmpCreateBitmapV3().

See Also

BmpGetDensity()

BmpSetTransparentValue Function ^TOP^

Purpose

Sets a bitmap's transparent color.

Declared In

Bitmap.h

Prototype

void BmpSetTransparentValue (
   BitmapType *bitmapP,
   uint32_t 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

Nothing.

Comments

If bitmapP points to a version 2 bitmap, BmpSetTransparentValue() sets the BitmapTypeV2 structure's bmpFlagsHasTransparency 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 bmpFlagsHasTransparency 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 bmpFlagsHasTransparency 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.

See Also

BmpGetTransparentValue()

BmpSize Function ^TOP^

Purpose

Returns the size of the bitmap.

Declared In

Bitmap.h

Prototype

uint32_t BmpSize (
   const BitmapType *bitmapP
)

Parameters

bitmapP
A pointer to the bitmap. See BitmapType.

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 bmpFlagsIndirect flag set (see Bitmap Flag Constants), the bitmap data is not included in the size returned by this function.

See Also

BmpColortableSize(), BmpGetSizes()

ColorTableEntries Macro ^TOP^

Purpose

Returns the color table.

Declared In

CmnBitmapTypes.h

Prototype

#define ColorTableEntries (
   ctP
)

Parameters

ctP
A pointer to a ColorTableType structure.

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

See Also

BmpGetColortable()