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
BitmapCompressionType Enum
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
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
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 thecompressionType
field specifies the compression used. Iffalse
, the bitmap is uncompressed. TheBmpCompress()
function sets this field. -
hasColorTable
- If
true
, the bitmap has its own color table. Iffalse
, 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 thetransparentIndex
. Iffalse
, the bitmap has no transparency value. You specify the transparent color when you create the bitmap using Constructor, or you can specify it programmatically withBmpSetTransparentValue()
. To obtain the value of this field, callBmpGetTransparentValue()
. -
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. Iffalse
, 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 ifhasColorTable
istrue
, a pointer to the bitmap's color table immediately follows theBitmapType
structure. Iffalse
, andhasColorTable
istrue
, the color table immediately follows theBitmapType
structure. IfhasColorTable
isfalse
,indirectColorTable
is ignored. Theindirect
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. Iffalse
, 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
Purpose
The BitmapPtr
type defines a pointer to a BitmapType
structure.
Prototype
typedef BitmapType *BitmapPtr;
BitmapType Struct
Purpose
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 ('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 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.
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 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
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. TheWindowType
or theFormBitmapType
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
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 thecompressed
flag is defined forBitmapTypeV0
structures. -
reserved
- 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.
Compatibility
BitmapTypeV0
is defined only if High-Density Display Feature Set is present.
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.
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 thecompressed
andhasColorTable
flags are defined forBitmapTypeV1
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) forBitmapTypeV1
structures. UseBmpGetVersion()
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, thenextDepthOffset
is 0. -
reserved
- Reserved.
Compatibility
BitmapTypeV1
is defined only if High-Density Display Feature Set is present.
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.
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 thecompressed
,hasColorTable
,hasTransparency
,indirect
,forScreen
, anddirectColor
flags are defined forBitmapTypeV2
structures. Note that theindirect 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) forBitmapTypeV2
structures. UseBmpGetVersion()
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, thenextDepthOffset
is 0. -
transparentIndex
- The color index for the transparent color. Only used for version 2 bitmaps and only when the
hasTransparency
flag is set (seeBitmapFlagsType
). You specify this value when you create the bitmap using Constructor, or programmatically withBmpSetTransparentValue()
. To obtain the value of this field, callBmpGetTransparentValue()
. -
compressionType
- The compression type used. Only used for version 2 bitmaps and only when the
compressed
flag is set (seeBitmapFlagsType
). SeeBitmapCompressionType
for possible values. TheBmpCompress()
function sets this field, and theBmpGetCompressionType()
function obtains its value. -
reserved
- Reserved.
Compatibility
BitmapTypeV2
is defined only if High-Density Display Feature Set is present.
BitmapTypeV3 Struct
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 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" (transparentValue
). 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.
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 theindirect
,forScreen
, andindirectColorTable
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) forBitmapTypeV3
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. 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
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 (seeBitmapFlagsType
). SeeBitmapCompressionType
for possible values. TheBmpCompress()
function sets this field, and theBmpGetCompressionType()
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 tokDensityDouble
. SeeDensityType
for the full set of values that this field can assume. Set this field withBmpSetDensity()
, and obtain its value withBmpGetDensity()
. -
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, callBmpGetTransparentValue()
. -
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
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
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
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
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
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 theindex
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 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).
Compatibility
RGBColorType
is defined only if 3.5 New Feature Set is present.
Bitmap Constants
-
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
You can create a bitmap resource and include it as part of your application's PRC file. Use the resource type 'Tbmp'
for most images and the resource type 'tAIB'
for application icons. Symbolically, these two resource types are bitmapRsc
and iconType
, respectively.
Note that if you are creating a bitmap or a bitmap family in Constructor, you create a 'tbmf'
resource (or 'taif'
resource for icons) and one or more 'PICT' images. The PalmRez post linker converts them into a single 'Tbmp'
or 'tAIB'
resource. Note that the PalmRez post linker takes PICT images even on the Microsoft Windows operating system.
Bitmap Functions
BmpBitsSize Function
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.
See Also
BmpSize()
, BmpColortableSize()
, BmpGetBits()
, BmpGetSizes()
BmpColortableSize Function
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.
See Also
BmpBitsSize()
, BmpSize()
, BmpGetColortable()
BmpCompress Function
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 toBitmapCompressionTypeNone
andbitmapP
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.
See Also
BmpCreate Function
Purpose
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 ofBitmapType
. -
→
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 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 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
, 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 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.
See Also
BmpCreateBitmapV3()
, BmpDelete()
BmpCreateBitmapV3 Function
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 usebitmapP
'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.
See Also
BmpDelete Function
Purpose
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
Purpose
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.
See Also
BmpBitsSize()
, BmpGlueGetBits()
BmpGetBitDepth Function
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."
See Also
BmpGetDimensions()
, BmpGetNextBitmap()
, BmpGetSizes()
BmpGetColortable Function
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.
See Also
BmpGetCompressionType Function
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.
See Also
BmpGetDensity Function
Purpose
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.
See Also
BmpCreateBitmapV3()
, BmpSetDensity()
BmpGetDimensions Function
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. UseNULL
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."
See Also
BmpGetBitDepth()
, BmpGetNextBitmap()
, BmpGetSizes()
BmpGetNextBitmap Function
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."
See Also
BmpGetBitDepth()
, BmpGetDimensions()
, BmpGetSizes()
BmpGetNextBitmapAnyDensity Function
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.
See Also
BmpGetDensity()
, BmpGetNextBitmap()
BmpGetSizes Function
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.
See Also
BmpGetBitDepth()
, BmpGetDimensions()
, BmpGetNextBitmap()
BmpGetTransparentValue Function
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.
See Also
BmpGetVersion Function
Purpose
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
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.
See Also
BmpSetTransparentValue Function
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
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.
See Also
BmpSize Function
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.
See Also
BmpBitsSize()
, BmpColortableSize()
, BmpGetSizes()
ColorTableEntries Macro
Purpose
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.