< Home < Developers < Development Support < Documentation

## 26 Bitmaps

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 26 Bitmaps Bitmap Data Structures BitmapCompressionType BitmapDirectInfoType BitmapFlagsType BitmapPtr BitmapType ColorTableType RGBColorType Bitmap Constants Bitmap Resources Bitmap Functions BmpBitsSize BmpColortableSize BmpCompress BmpCreate BmpDelete BmpGetBits BmpGetBitDepth BmpGetColortable BmpGetDimensions BmpGetNextBitmap BmpGetSizes BmpSize ColorTableEntries |  |  |  | This chapter provides information about bitmaps by discussing these topics: Bitmap Data Structures Bitmap Constants Bitmap Resources Bitmap Functions The header file Bitmap.h declares the API that this chapter describes. For more information on bitmaps, see the section "Bitmaps" in the Palm OS Programmer's Companion, vol. I. ## Bitmap Data Structures ## BitmapCompressionType The BitmapCompressionType enum specifies possible bitmap compression types. These are the possible values for the compressionType field of BitmapType. You can compress or uncompress a bitmap using a call to BmpCompress.
    typedef enum {
      BitmapCompressionTypeScanLine = 0,
      BitmapCompressionTypeRLE,
      BitmapCompressionTypePackBits,
      BitmapCompressionTypeEnd,
      BitmapCompressionTypeBest = 0x64,
      BitmapCompressionTypeNone = 0xFF
    } BitmapCompressionType;
#### Value Descriptions #####
BitmapCompressionTypeScanLine | Use scan line compression. Scan line compression is compatible with Palm OS® 2.0 and higher.
BitmapCompressionTypeRLE | Use RLE compression. RLE compression is supported in Palm OS 3.5 and higher.
BitmapCompressionTypePackBits | Use PackBits compression. PackBits compression is supported in Palm OS 4.0 only.
BitmapCompressionTypeEnd | For internal use only.
BitmapCompressionTypeBest | For internal use only.
BitmapCompressionTypeNone | No compression is used. This value should only be used as an argument to BmpCompress.
#### Compatibility BitmapCompressionType is only defined if 3.5 New Feature Set is present. Earlier releases do support compressed bitmaps, but in scan line format only. ## New BitmapDirectInfoType For direct color bitmaps-each pixel is represented by an RGB triplet rather than a palette index-the BitmapDirectInfoType structure follows the color table if one is present, or immediately follows the BitmapType if a color table is not present. For direct color bitmaps, only 16 bits per pixel is supported, 5 bits for red, 6 bits for green, and 5 bits for blue. WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapDirectInfoType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct BitmapDirectInfoType {
      UInt8 redBits;
      UInt8 greenBits;
      UInt8 blueBits;
      UInt8 reserved;
      RGBColorType transparentColor;
    } BitmapDirectInfoType;
#### Field Descriptions #####
redBits | Number of bits used by the red component in each pixel.
greenBits | Number of bits used by the green component in each pixel.
blueBits | Number of bits used by the blue component in each pixel.
reserved | Must be zero. Reserved for future use.
transparentcolor | Contains the red, green, and blue components of the transparent color.
#### Compatibility BitmapDirectInfoType is only defined if 4.0 New Feature Set is present. ## BitmapFlagsType The BitmapFlagsType bit field defines the flags field of BitmapType. It specifies the bitmap's attributes. WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapFlagsType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct BitmapFlagsType {
      UInt16 compressed:1;
      UInt16 hasColorTable:1;
      UInt16 hasTransparency:1;
      UInt16 indirect:1;
      UInt16 forScreen:1;
      UInt16 directColor:1;
      UInt16 reserved:10;
    } BitmapFlagsType;
#### Field Descriptions #####
compressed | If true, the bitmap is compressed and the compressionType field specifies the compression used. If false, the bitmap is uncompressed. The BmpCompress function sets this field.
hasColorTable | If true, the bitmap has its own color table. If false, the bitmap uses the system color table. You specify whether the bitmap has its own color table when you create the bitmap.
hasTransparency | If true, the OS will not draw pixels that have a value equal to the transparentIndex. If false, the bitmap has no transparency value. You specify the transparent color when you create the bitmap using Constructor.
indirect | If true, the address to the bitmap's data is stored where the bitmap itself would normally be stored. The actual bitmap data is stored elsewhere. If false, the bitmap data is stored directly following the bitmap header or directly following the bitmap's color table if it has one. Never set this flag. Only the display (screen) bitmap has the indirect bit set.
forScreen | If true, bitmap intended for the display (screen) window. Never set this flag.
directColor | If true, bitmap is a direct color (RGB) bitmap.
reserved | Reserved for future use.
#### Compatibility Flags hasTransparency, indirect, and forScreen are only defined if 3.5 New Feature Set is present. The directColor flag is only defined if 4.0 New Feature Set is present. ## BitmapPtr The BitmapPtr type defines a pointer to a BitmapType structure.
    typedef BitmapType *BitmapPtr;
## BitmapType The BitmapType structure represents a bitmap. This structure defines both the bitmaps representing the window display and bitmap resources ('Tbmp' and 'tAIB') that you create using Constructor or some other application and load into your program. WARNING! Palm, Inc. does not support or provide backward compatibility for the BitmapType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
    typedef struct BitmapType {
      Int16            width;
      Int16            height;
      UInt16           rowBytes;
      BitmapFlagsType  flags;
      UInt8            pixelSize;
      UInt8            version;
      UInt16           nextDepthOffset;
      UInt8            transparentIndex;
      UInt8            compressionType;
      UInt16           reserved;
    } BitmapType;
#### Field Descriptions #####
width | The width of the bitmap in pixels. You specify this value when you create the bitmap. Use BmpGetDimensions to access this field.
height | The height of the bitmap in pixels. You specify this value when you create the bitmap. Use BmpGetDimensions to access this field.
rowBytes | The number of bytes stored for each row of the bitmap where height is the number of rows. Use BmpGetDimensions to access this field.
flags | The bitmap's attributes. See BitmapFlagsType.
pixelSize | The pixel depth. Currently supported pixel depths are 1, 2, 4, and 8-bit. You specify this value when you create the bitmap.
version | The version of bitmap encoding used. See Bitmap Constants.
nextDepthOffset | For bitmap families, this field specifies the start of the next bitmap in the family. The value it contains is the number of 4-byte words to the next BitmapType from the beginning of this one. If the bitmap is not part of a bitmap family or it is the last bitmap in the family, the nextDepthOffset is 0.
transparentIndex | The color index for the transparent color. Only used for version 2 bitmaps and only when the hasTransparency flag is set (see BitmapFlagsType). You specify this value when you create the bitmap using Constructor.
compressionType | The compression type used. Only used for version 2 bitmaps and only when the compressed flag is set (see BitmapFlagsType). See BitmapCompressionType for possible values. The BmpCompress function sets this field.
reserved | Reserved for future use. Must be set to 0.
Note the following about the BitmapType structure: None of these fields contains the actual bitmap data. Instead, the bitmap data is stored immediately following this BitmapType header structure. If the bitmap has its own color table, the color table is stored in between the header and the data. If the bitmap has a pixel size of 16, the BitmapDirectInfoType structure is stored between the header and the data. You can retrieve a bitmap's data by passing its BitmapType structure to BmpGetBits, and you can retrieve its color table with BmpGetColortable. Unlike most other user interface structures, the BitmapType does not store the bitmap's location on the screen. The WindowType or the FormBitmapType with which this bitmap is associated contains that information. A bitmap may be part of a bitmap family. A bitmap family is a group of bitmaps, each containing the same drawing but at a different pixel depth (see Figure 5.14 in the User Interface chapter of the Palm OS Programmer's Companion, vol. I). When requested to draw a bitmap family, the operating system chooses the version of the bitmap with the pixel depth closest to, but not greater than, the current pixel depth of the display. When BitmapType represents a bitmap family, the nextDepthOffset field contains the offset from the start of this bitmap to the next bitmap in the family. #### Compatibility The transparentIndex and compressionType flags are defined only if 3.5 New Feature Set is present. ## ColorTableType The ColorTableType structure defines a color table. Bitmaps can have color tables attached to them; however, doing so is not recommended for performance reasons. WARNING! Palm, Inc. does not support or provide backward compatibility for the ColorTableType structure. Never access its structure members directly, or your code may break in future versions. Use BmpGetColortable to access this structure. Use the information below for debugging purposes only.
    typedef struct ColorTableType {
      UInt16            numEntries;
      // RGBColorType   entry[];
    } ColorTableType;
#### Field Descriptions #####
numEntries | The number of entries in table. High bits (numEntries > 256) reserved.
The color table entries themselves are of type RGBColorType, and there is one per numEntries. Use the macro ColorTableEntries to retrieve these entries. Care should be taken not to confuse a full color table (which includes the count) with an array of RGB color values. Some routines operate on entire color tables; others operate on lists of color entries. #### Compatibility ColorTableType is defined only if 3.5 New Feature Set is present. ## RGBColorType The RGBColorType structure defines a color. It is used as an entry in the color table. RGBColorTypes can also be created manually and passed to several user interface functions.
    typedef struct RGBColorType {
      UInt8 index;
      UInt8 r;
      UInt8 g;
      UInt8 b;
    } RGBColorType;
#### Field Descriptions #####
index | The index of this color in the color table. Not all functions that use RGBColorType use the index field. Direct bitmaps support no more than 256 colors. The number of possible RGB colors greatly exceeds this amount. For this reason, some drawing functions use a color look up table (CLUT). If the CLUT is used, the index field contains the index of an available color that is the closest match to the color specified by the r, g, and b fields.
r | Amount of red (0 to 255).
g | Amount of green (0 to 255).
b | Amount of blue (0 to 255).
#### Compatibility RGBColorType is defined only if 3.5 New Feature Set is present. ## Bitmap Constants #####
Constant | Value | Description
--- | --- | ---
BitmapVersionZero | 0 | Uses the version 0 encoding of a bitmap. Version 0 encoding is supported in Palm OS 1.0 and later.
BitmapVersionOne | 1 | Uses the version 1 encoding of a bitmap. Version 1 encoding is supported in Palm OS 3.0 and later. PalmRez automatically creates version 1 bitmaps unless you have specified a transparency index or a compressed type when creating the bitmap in Constructor.
BitmapVersionTwo | 2 | Uses the version 2 encoding of a bitmap. Palm OS 3.5 and later supports version 2 bitmaps. Version 2 bitmaps either use the transparency index or are compressed. If you programmatically create a bitmap using BmpCreate, a version 2 bitmap is created.
## Bitmap Resources You can create a bitmap resource and include it as part of your application's PRC file. Use the resource type 'Tbmp' for most images and the resource type 'tAIB' for application icons. Symbolically, these two resource types are bitmapRsc and iconType, respectively. Note that if you are creating a bitmap or a bitmap family in Constructor, you create a 'tbmf' resource (or 'taif' resource for icons) and one or more 'PICT' images. The PalmRez post linker converts them into a single 'Tbmp' or 'tAIB' resource. Note that the PalmRez post linker takes PICT images even on the Microsoft Windows operating system. ## Bitmap Functions ## BmpBitsSize #### Purpose Return the size of the bitmap's data. #### Prototype UInt16 BmpBitsSize (const BitmapType *bitmapP) #### Parameters #####
-> bitmapP | Pointer to the bitmap. (See BitmapType.)
#### Result Returns the size in bytes of the bitmap's data, excluding the header and the color table. #### Comments This function returns the bitmap's data size even if the bitmap's indirect flag is set. (See BitmapFlagsType.) If the bitmap is compressed, this function returns the compressed size of the bitmap. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpSize, BmpColortableSize, BmpGetBits ## BmpColortableSize #### Purpose Return the size of the bitmap's color table. #### Prototype UInt16 BmpColortableSize (const BitmapType *bitmapP) #### Parameters #####
-> bitmapP | Pointer to the bitmap. (See BitmapType.)
#### Result Returns the size in bytes of the bitmap's color table or 0 if the bitmap does not use its own color table. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpBitsSize, BmpSize, BmpGetColortable ## BmpCompress #### Purpose Compress or uncompress a bitmap. #### Prototype Err BmpCompress (BitmapType *bitmapP, BitmapCompressionType compType) #### Parameters #####
-> bitmapP | Pointer to the bitmap to compress. (See BitmapType.)
#####
-> compType | The type of compression to use. (See BitmapCompressionType.) If set to BitmapCompressionTypeNone and bitmapP is compressed, this function uncompresses the bitmap.
#### Result 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. ## BmpCreate #### Purpose Create a bitmap. #### Prototype BitmapType *BmpCreate (Coord width, Coord height, UInt8 depth, ColorTableType *colortableP, UInt16 *error) #### Parameters #####
-> width | The width of the bitmap in pixels. Must not be 0.
#####
-> height | The height of the bitmap in pixels. Must not be 0.
#####
-> depth | The pixel depth of the bitmap. Must be 1, 2, 4, 8, or 16. This value is used as the pixelSize field of BitmapType.
#####
-> colortableP | A pointer to the color table associated with the bitmap, or NULL if the bitmap should not include a color table. If specified, the number of colors in the color table must match the depth parameter. (2 for 1-bit, 4 for 2-bit, 16 for 4-bit, and 256 for 8-bit). 16-bit bitmaps do not use a color table.
#####
<- error | Contains the error code if an error occurs.
#### Result Returns a pointer to the new bitmap structure (see BitmapType) or NULL if an error occurs. The parameter error contains one of the following: #####
errNone | Success.
#####
sysErrParamErr | The width, height, depth, or colorTableP parameter is invalid. See the descriptions above for acceptable values.
#####
sysErrNoFreeResource | There is not enough memory available to allocate the structure.
#### Comments This function creates an uncompressed, non-transparent BitmapVersionTwo bitmap with the width, height, and depth that you specify. If you pass a color table, the bitmap's hasColorTable flag is set. For performance reasons, attaching a custom color table to a bitmap is strongly discouraged. An alternative is to use the WinPalette command to change the color table as needed, draw the bitmap, and then undo your changes after you have finished displaying the bitmap. BmpCreate allocates sufficient memory on the dynamic heap to hold the bitmap and initializes all of its pixels to white. To change the bitmap's contents, use the window drawing functions. First, you must use WinCreateBitmapWindow to create an off screen window wrapper around the bitmap, then draw to that window. For example:
    BitmapType *bmpP;
    WinHandle win;
    Err error;
    RectangleType onScreenRect;

    bmpP = BmpCreate(10, 10, 8, NULL, &error);
    if (bmpP) {
      win = WinCreateBitmapWindow(bmpP, &error);
      if (win) {
        WinSetDrawWindow(win);
        WinDrawLines(win, ...);
        /* etc */
        WinSetWindowBounds(win, onScreenRect);
      }
    }
You cannot use this function to create a bitmap written directly to a database; that is, you must create the bitmap on the dynamic heap first, then write it to the storage heap. It is not necessary to use BmpCreate to load a bitmap stored in a resource. Instead, you simply load the resource and lock its handle. The returned pointer is a pointer to a BitmapType. For example:
    MemHandle resH =
      DmGetResource (bitmapRsc, rscID);
    BitmapType *bitmap = MemHandleLock (resH);
Bitmaps 64 Kb and greater are now supported with Palm OS 4.0. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpDelete ## BmpDelete #### Purpose Delete a bitmap structure. #### Prototype Err BmpDelete (BitmapType *bitmapP) #### Parameters #####
-> bitmapP | Pointer to the structure of the bitmap to be deleted. (See BitmapType.)
#### Result Returns errNone upon success, sysErrParamErr if the bitmap's forScreen flag is set or the bitmap resides in the storage heap. Returns one of the memory errors if the freeing pointer fails. #### Comments Only delete bitmaps that have been created using BmpCreate. You cannot use this function on a bitmap located in a database. To delete a bitmap from a database, use the standard data manager calls. #### Compatibility Implemented only if 3.5 New Feature Set is present. ## BmpGetBits #### Purpose Retrieve the bitmap's data. #### Prototype void *BmpGetBits (BitmapType *bitmapP) #### Parameters #####
-> bitmapP | Pointer to the bitmap's structure. (See BitmapType.)
#### Result Returns a pointer to the bitmap's data. #### Comments This function returns the bitmap's data even if the bitmap's indirect flag is set. (See BitmapFlagsType.) #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpBitsSize ## New BmpGetBitDepth #### Purpose Retrieve the depth of a bitmap. #### Prototype UInt8 BmpGetBitDepth (const BitmapType* bitmapP) #### Parameters #####
-> bitmapP | Pointer to a bitmap. See BitmapType.
#### Result This function returns the bit depth of the bitmap, as represented by the pixelSize field in BitmapType. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL. #### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetBitDepth. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also BmpGetDimensions, BmpGetNextBitmap, BmpGetSizes ## BmpGetColortable #### Purpose Retrieve the bitmap's color table. #### Prototype ColorTableType *BmpGetColortable (BitmapType *bitmapP) #### Parameters #####
-> bitmapP | A pointer to the bitmap. See BitmapType.
#### Result Returns a pointer to the color table or NULL if the bitmap uses the system color table. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpColortableSize ## New BmpGetDimensions #### Purpose Retrieve the width, height and number of data bytes per row of a bitmap. #### Prototype void BmpGetDimensions (const BitmapType *bitmapP, Coord *widthP, Coord *heightP, UInt16 *rowBytesP) #### Parameters #####
-> bitmapP | Pointer to the bitmap. See BitmapType.
#####
<- widthP | Pointer to bitmap's width in pixels. Use NULL if this information is not wanted.
#####
<- heightP | Pointer to bitmap's height in pixels. Use NULL if this information is not wanted. Use NULL if this information is not wanted.
#####
<- rowBytesP | Pointer to number of bytes per row of bitmap. Use NULL if this information is not wanted.
#### Result This function returns the width in pixels of the bitmap in widthP, the height in pixels of the bitmap in heightP, and the number of bytes of data per row of the bitmap in rowBytesP. This function reports an error on debug ROMs if bitmapP is NULL. #### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetDimensions. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also BmpGetBitDepth, BmpGetNextBitmap, BmpGetSizes ## New BmpGetNextBitmap #### Purpose Retrieve the next bitmap type in a bitmap family. #### Prototype BitmapType *BmpGetNextBitmap(BitmapType *bitmapP) #### Parameters #####
-> bitmapP | Pointer to a bitmap. See BitmapType.
#### Result This function returns a pointer to the next BitmapType in a bitmap family. It returns NULL if bitmapP is the last bitmap. For debug ROMs, this function reports an error and returns 0 if bitmapP is NULL. #### Compatibility Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call BmpGlueGetNextBitmap. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also BmpGetBitDepth, BmpGetDimensions, BmpGetSizes ## New BmpGetSizes #### Purpose Retrieve the size of a bitmap and its header structure. #### Prototype void BmpGetSizes (const BitmapType *bitmapP, UInt32 *dataSizeP, UInt32 *headerSizeP) #### Parameters #####
->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.
#### Result Returns the size of the bitmap and the size of the bitmap's structures. This function will report an error on debug ROMs if bitmapP is NULL. #### Comments This function returns the size in bytes of the bitmap data in dataSizeP. The size does not include the data structures (BitmapType, BitmapDirectInfoType, or color table) that are associated with a bitmap. The size of the structures (in bytes) are returned in headerSizeP, which includes the size of the BitmapType, BitmapDirectInfoType (if any), the color table (if any), and the size of the pointer for indirect bitmaps (described in BitmapFlagsType). This function should be used when working with bitmaps that may be 64 Kb or greater. Do not use BmpSize or BmpBitsSize when working with bitmaps that may be greater than or equal to 64Kb. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also BmpGetBitDepth, BmpGetDimensions, BmpGetNextBitmap ## BmpSize #### Purpose Return the size of the bitmap. #### Prototype UInt16 BmpSize (const BitmapType *bitmapP) #### Parameters #####
-> bitmapP | A pointer to the bitmap. See BitmapType.
#### Result Returns the size in bytes of the bitmap, including its header, color table (if any), and sizeof(BitmapDirectInfoType) if one exists. #### Comments If the bitmap has its indirect flag set (see BitmapFlagsType), the bitmap data is not included in the size returned by this function. #### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpBitsSize, BmpColortableSize ## ColorTableEntries #### Purpose Macro that returns the color table. #### Prototype ColorTableEntries (ctP) #### Parameters #####
-> ctP | A pointer to a ColorTableType structure.
#### Result Returns an array of RGBColorType structures, one for each entry in the color table. #### Comments You can use this macro to retrieve the RGB values in use by a bitmap. For example:
    BitmapType *bmpP;
    RGBColorType *tableP =
      ColorTableEntries(BmpGetColorTable(bmpP));
If you want to retrieve the RGB values in use by the system color table, you can simply use the WinPalette function instead of this macro:
    RGBColorType table[256];
    Err e;

    /* allocate space for table */
    e = WinPalette(winPaletteGet, 0, 256, tableP);
#### Compatibility Implemented only if 3.5 New Feature Set is present. #### See Also BmpGetColortable |