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
BitmapDirectInfoType Struct
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
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. UseBmpGetDimensions()
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 ofBitmapVersionZero
(0) corresponds toBitmapTypeV0
,BitmapVersionOne
(1) corresponds toBitmapTypeV1
,BitmapVersionTwo
(2) corresponds toBitmapTypeV2
, andBitmapVersionThree
(3) corresponds toBitmapTypeV3
. UseBmpGetVersion()
to obtain the contents of this field.
Comments
The BitmapType
structure represents that which is common to all BitmapTypeV
x 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 BitmapTypeV
x 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
BitmapTypeV
x (which one depends on the value of theversion
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 isBitmapTypeV2
, theBitmapDirectInfoType
structure is stored between the header and the data. You can retrieve a bitmap's data by passing itsBitmapType
structure toBmpGetBits()
, and you can retrieve its color table withBmpGetColortable()
. - Unlike most other user interface structures, the
BitmapType
does not store the bitmap's location on the screen. TheFormBitmapType
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
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. UseBmpGetDimensions()
to access this field. -
flagsBE16
- The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Only the
bmpFlagsCompressed
flag is defined forBitmapTypeV0
structures. -
reservedBE16
- Reserved. These values are set to zero. Note that in the
BitmapTypeV0
structure, thepixelSize
andversion
fields, defined inBitmapType
, do not exist. They coincide with thereserved
array, however, and this array was initialized to zero when the bitmap was created. The operating system recognizes that apixelSize
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
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. UseBmpGetDimensions()
to access this field. -
flagsBE16
- The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Only the
bmpFlagsCompressed
andbmpFlagsHasColorTable
flags are defined forBitmapTypeV1
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) forBitmapTypeV1
structures. UseBmpGetVersion()
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, thenextDepthOffsetBE16
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
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. UseBmpGetDimensions()
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
, andbmpFlagsDirectColor
flags are defined forBitmapTypeV2
structures. Note that thebmpFlagsIndirect 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) forBitmapTypeV2
structures. UseBmpGetVersion()
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, thenextDepthOffsetBE16
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 withBmpSetTransparentValue()
. To obtain the value of this field, callBmpGetTransparentValue()
. -
compressionType
- The compression type used. Only used when the
bmpFlagsCompressed
flag is set. SeeBitmapCompressionType
for possible values. TheBmpCompress()
function sets this field, and theBmpGetCompressionType()
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
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. UseBmpGetDimensions()
to access this field. -
flagsBE16
- The bitmap's attributes, given in big-endian format. See Bitmap Flag Constants. Note that the
bmpFlagsIndirect
,bmpFlagsForScreen
, andbmpFlagsIndirectColorTable
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) forBitmapTypeV3
structures. UseBmpGetVersion()
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. SeeBitmapCompressionType
for possible values. TheBmpCompress()
function sets this field, and theBmpGetCompressionType()
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 tokDensityDouble
. SeeDensityType
for the full set of values that this field can assume. Set this field withBmpSetDensity()
, and obtain its value withBmpGetDensity()
. -
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, callBmpGetTransparentValue()
. -
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 BitmapTypeV
x 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
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
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
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 theindex
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 ther
,g
, andb
fields. -
r
- Amount of red (0 to 255).
-
g
- Amount of green (0 to 255).
-
b
- Amount of blue (0 to 255).
See Also
Bitmap Constants
Bitmap Version Constants
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
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. TheBmpCompress()
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 istrue
, the color table immediately follows theBitmapType
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
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
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
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
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
BmpColortableSize Function
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
BmpCompress Function
Purpose
Does nothing. Previously called to compress or uncompress a bitmap.
Declared In
Bitmap.h
Prototype
status_t BmpCompress ( BitmapType*bitmapP
, BitmapCompressionTypecompType
)
Parameters
-
→
bitmapP
- Pointer to the bitmap to compress. (See
BitmapType
.) -
→ compType
- The type of compression to use. (See
BitmapCompressionType
.) If set toBitmapCompressionTypeNone
andbitmapP
is compressed, this function uncompresses the bitmap.
Returns
BmpCreate Function
Purpose
Declared In
Bitmap.h
Prototype
BitmapType *BmpCreate ( Coordwidth
, Coordheight
, uint8_tdepth
, 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 ofBitmapType
. -
→ 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 thedepth
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
, orcolortableP
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
BmpCreateBitmapV3 Function
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_tdensity
, 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 usebitmapP
'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
BmpDelete Function
Purpose
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
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
Purpose
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
BmpGetColortable Function
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
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
BmpGetDensity Function
Purpose
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
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
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
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
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
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
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
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
BmpGetVersion Function
Purpose
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
Purpose
Sets the density of a version 3 bitmap.
Declared In
Bitmap.h
Prototype
status_t BmpSetDensity ( BitmapType*bitmapP
, uint16_tdensity
)
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
BmpSetTransparentValue Function
Purpose
Sets a bitmap's transparent color.
Declared In
Bitmap.h
Prototype
void BmpSetTransparentValue ( BitmapType*bitmapP
, uint32_ttransparentValue
)
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
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
BmpSize Function
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
Purpose
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));