Bitmaps

Bitmapped graphics have a variety of applications, ranging from displaying corporate logos to rendering the characters of a game. Consequently, Series 60, through graphics contexts and specific bitmap classes, provides numerous APIs for manipulating and drawing bitmaps. Both the Window Server and Font and Bitmap Server can play vital roles, and as a result there are two types of bitmap class. A CFbsBitmap is a bitmap managed by the Font and Bitmap Server, while a CWsBitmap is an extension for more efficient use by the Window Server. Functions with a CWsBitmap parameter tend to be faster than their CFbsBitmap equivalents.

Due to the memory constraints of Series 60 devices, and the storage demands of bitmapped graphics, bitmap ( .bmp ) files should be converted into Symbian OS multibitmap ( .mbm ) file format. There is also scope for using GIF and JPEG file types, although these must first be converted to one of the bitmap types for display ”this is discussed in the Image Manipulation section of this chapter.

Generating Bitmaps for Application Use

A PC utility is provided by the SDK called bmconv , which, when supplied with a list of .bmp (Windows bitmap) files, will generate a single .mbm (Symbian OS multibitmap) file, containing all of the bitmap images. More information on bmconv can be found in Chapter 2.

While this can be used directly, it is far simpler to employ the START BITMAP END command within the application's .mmp file to automatically run this tool for you.

If desired, all of the application's bitmaps can be contained within a single .mbm file, although it may be more manageable to group related graphics into separate .mbm files. For example, in a game, levels.mbm might contain all the images for the various levels, while player.mbm may contain the bitmaps for the central character. It would be rare and inadvisable to have an .mbm file for each .bmp file.

Handles to individual bitmaps within an .mbm are obtained through an enumeration. This enumeration is contained within a header file with an .mbg extension, which is generated as part of the conversion process. The .mbg file and enumeration will have the same name as the .mbm file ”for example, levels.mbm will have a corresponding levels.mbg file, and the enumeration name will be TMbmLevels . The enumeration value for a specific bitmap is then of the form EMbmLevelsMybitmap , where Mybitmap is the name of the .bmp file of interest.

The process is shown in Figure 11-13, with an outline of the commands within START BITMAP provided in Table 11-8.

Figure 11-13. Converting multiple .bmp files to a single .mbm file with a partnering .mbg file.

The pregenerated .bmp files are referenced within the scope of the START BITMAP command via the SOURCE command. The SOURCEPATH value is the location where the .bmp files are being stored. There can be multiple SOURCEPATH statements; however, the .bmp files in subsequent SOURCE statement must be contained within that path .

Table 11-8. Overview of the START BITMAP Commands

Command	Purpose
START BITMAP	For each .mbm required, a separate START BITMAP is required.
[TARGETFILE target-fil e ]	Name of the .mbm file to be produced.
[TARGETPATH targetpath ]	If not specified, the .mbm file will be built in the same directory as the application.
[HEADER]	This command is needed to ensure the .mbg file is generated in the \epoc32\include directory, in the root directory of your SDK.
[SOURCEPATH sourcepath ]	Directory of the .bmp files that follow in subsequent SOURCE statements.
SOURCE color -depth source-bitmap-list	The bitmaps that follow will all be of the color depth specified. The color depth must be of the form [c]depth, where the (optional) " c " indicates a color image and depth represents the color depth. Multiple SOURCEPATH and SOURCE statements can be defined ”source bitmaps specified with each SOURCE statement should exist in the directory denoted by the SOURCEPATH statement above it.
END	This command concludes the .mbm creation.

Loading and Drawing Bitmaps

With an .mbm file in place, bitmaps can be loaded and drawn ”the path to the bitmap is declared within the application code and is used by the CFbsBitmap::Load() function:

 _LIT(KDrawBitmapPath, "\system\apps\Bitmap\Bitmap.mbm"); ... iBitmap = new (ELeave) CFbsBitmap(); User::LeaveIfError(iBitmap->Load(KDrawBitmapPath, EMbmBitmapDrawbitmap)); ... 

In order to draw the bitmaps, a graphics context is required. Graphics contexts that derive from CBitmapContext are used for drawing bitmaps and provide two named functions, DrawBitmap() and BitBlt() . These two functions each have a variety of overloaded variations to suit differing needs and are illustrated in the SDK documentation. Clipping is performed automatically, so this need not concern you.

DrawBitmap() is the slower of the two, as it always performs bitmap scaling as part of its operation, whereas BitBlt() performs a block transfer of the bitmap. The Bitmap example application demonstrates both approaches, with DrawBitmap() being called by the CDrawBitmapContainer::Draw() function and BitBlt() by CBitmapBitBltContainer::Draw() .

 ... gc.DrawBitmap(TRect(topLeft, bitmapSize), iBitmap); ... gc.BitBlt(topLeft, iBitmap); ... 

Bitmap Masking

Though drawing of bitmaps always occurs within rectangular areas, the bitmaps themselves can vary greatly in shape. Often it is useful that portions of the rectangular area are actually transparent to give the bitmap the appearance of its true shape without drawing over portions of a background. This is achieved through a technique known as masking.

Masking requires a second image that is used to determine which areas of the visible bitmap will actually be displayed. Masking bitmaps generally have a color depth of two (representing image/no image), and the BitBltMasked() function is passed both the masking image and displayed image as parameters.

BitBltMasked() is called by CBitmapBitBltMaskContainer::Draw() in the Bitmap example:

[View full width]

 
 [View full width] 
 ... gc.BitBltMasked(topLeft, iBitmap, TRect(TPoint(0, 0), TSize(KSizeWidth, KSizeHeight)),  iMask, ETrue); ... 

Figure 11-14 shows how a bitmap can be masked.

Figure 11-14. Using a rectangular bitmap and a masking bitmap to create a masked bitmap.

When developing controls that require images, such as information dialogs, it is advisable always to use bitmap masking. This is because Series 60 can be greatly customized by Licensees, and the background colors of a particular control may vary from device to device.

Bitmap Functions

The CFbsBitmap class has numerous useful functions for obtaining information about a bitmap's attributes, as listed in Table 11-9.

Table 11-9. Useful CFbsBitmap Methods

Function	Role
DataAddress()	Returns the address of the first (top left) pixel.
DisplayMode()	The display mode of the bitmap.
ExternalizeL()	Externalizes the bitmap to a stream.
GetPixel()	Returns the RGB value ( trgb ) of a given pixel.
InternalizeL()	Internalizes the bitmap from a stream.
Save()	Saves the bitmap to a named file.