|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CompatibilityFlags 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
Note the following about the BitmapType structure: CompatibilityThe 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
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. CompatibilityColorTableType 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 DescriptionsCompatibilityRGBColorType is defined only if 3.5 New Feature Set is present.
Bitmap Constants
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
PurposeReturn the size of the bitmap's data. PrototypeUInt16 BmpBitsSize (const BitmapType *bitmapP) Parameters
ResultReturns the size in bytes of the bitmap's data, excluding the header and the color table. CommentsThis 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. CompatibilityImplemented only if 3.5 New Feature Set is present. See AlsoBmpSize, BmpColortableSize, BmpGetBits
BmpColortableSize
PurposeReturn the size of the bitmap's color table. PrototypeUInt16 BmpColortableSize (const BitmapType *bitmapP) Parameters
ResultReturns the size in bytes of the bitmap's color table or 0 if the bitmap does not use its own color table. CompatibilityImplemented only if 3.5 New Feature Set is present. See AlsoBmpBitsSize, BmpSize, BmpGetColortable
BmpCompress
PurposeCompress or uncompress a bitmap. PrototypeErr BmpCompress (BitmapType *bitmapP, BitmapCompressionType compType) Parameters
ResultReturns one of the following values:
CommentsThis function performs the specified compression and resizes the bitmap's allocated memory. The bitmap must be in the dynamic heap. CompatibilityImplemented only if 3.5 New Feature Set is present.
BmpCreate
PurposePrototypeBitmapType *BmpCreate (Coord width, Coord height, UInt8 depth, ColorTableType *colortableP, UInt16 *error) Parameters
ResultReturns a pointer to the new bitmap structure (see BitmapType) or NULL if an error occurs. The parameter error contains one of the following:
CommentsThis 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. CompatibilityImplemented only if 3.5 New Feature Set is present. See Also
BmpDelete
PurposePrototypeErr BmpDelete (BitmapType *bitmapP) Parameters
ResultReturns 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. CommentsOnly 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. CompatibilityImplemented only if 3.5 New Feature Set is present.
BmpGetBits
PurposePrototypevoid *BmpGetBits (BitmapType *bitmapP) Parameters
ResultReturns a pointer to the bitmap's data. CommentsThis function returns the bitmap's data even if the bitmap's indirect flag is set. (See BitmapFlagsType.) CompatibilityImplemented only if 3.5 New Feature Set is present. See Also
|
-> bitmapP | Pointer to a bitmap. See BitmapType. |
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.
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."
BmpGetDimensions, BmpGetNextBitmap, BmpGetSizes
Retrieve the bitmap's color table.
ColorTableType *BmpGetColortable (BitmapType *bitmapP)
-> 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.
Implemented only if 3.5 New Feature Set is present.
Retrieve the width, height and number of data bytes per row of a bitmap.
void BmpGetDimensions (const BitmapType *bitmapP, Coord *widthP, Coord *heightP, UInt16 *rowBytesP)
-> 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. |
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.
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."
BmpGetBitDepth, BmpGetNextBitmap, BmpGetSizes
Retrieve the next bitmap type in a bitmap family.
BitmapType *BmpGetNextBitmap(BitmapType *bitmapP)
-> bitmapP | Pointer to a bitmap. See BitmapType. |
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.
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."
BmpGetBitDepth, BmpGetDimensions, BmpGetSizes
Retrieve the size of a bitmap and its header structure.
void BmpGetSizes (const BitmapType *bitmapP, UInt32 *dataSizeP, UInt32 *headerSizeP)
->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 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.
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.
Implemented only if 4.0 New Feature Set is present.
BmpGetBitDepth, BmpGetDimensions, BmpGetNextBitmap
Return the size of the bitmap.
UInt16 BmpSize (const BitmapType *bitmapP)
-> 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.
If the bitmap has its indirect flag set (see BitmapFlagsType), the bitmap data is not included in the size returned by this function.
Implemented only if 3.5 New Feature Set is present.
BmpBitsSize, BmpColortableSize
Macro that returns the color table.
-> ctP | A pointer to a ColorTableType structure. |
Returns an array of RGBColorType structures, one for each entry in the color table.
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);
Implemented only if 3.5 New Feature Set is present.
|