Extended Bitmaps

Natively supported bitmap formats

Traditionally Symbian has provided native support for bitmaps in relatively simple formats, including the standard uncompressed bitmap format and bitmaps compressed using simple Run-Length Encoding (RLE). The uncompressed format stores scan lines as a sequence of individual colors, one for each pixel. The RLE compression instead breaks each scan line into runs of consecutive pixels of the same color. For each run it stores the color and the number of times it is repeated. The exact details of the compression formats are internal to Symbian.

The natively-supported compression types are enumerated in TBitmapfileCompression. You can use the Bitmap Conversion Tool to generate compressed bitmaps. In addition, you can compress bitmaps at runtime by calling CFbsBitmap::Compress() and CFbsBitmap::CompressInBackground().

The extended bitmap approach

The extended bitmap framework allows device creators to define and add their own compression formats. Bitmaps that are created using this framework are known as extended bitmaps. The Font and Bitmap Server simply stores the compressed data and does not interpret it in any way.

The key features of extended bitmaps are:

• They are read-only.

• They have a type, which is unique ID (UID) that identifies the proprietary data format.

• There are no restrictions on the data format.

• When an extended bitmap cannot be decompressed for some reason, it is rendered as solid white.

There are two ways that the bitmap can be decompressed prior to rendering. Which one is used depends on whether the application draws the extended bitmap by using the Window Server API (such as CWindowGc) for on-screen rendering or the BitGDI API for off-screen rendering and Direct Screen Access (DSA).

To illustrate how it works, let us consider a scenario in which extended bitmaps are used to store SVG data. (In the broadest sense, you can consider SVG data to be a type of compression of bitmap data.) The following diagram shows how an extended bitmap that represents an icon is ultimately displayed on the screen.

This is how it works:

1. An engine or server (the Theme Server in this example) creates an extended bitmap that stores the icon's SVG data.

2. To the application, the bitmap appears like an ordinary compressed XIP ROM-based bitmap. The application simply calls CWindowGc::DrawBitmap() in the normal way, passing in the CFbsBitmap handle. (Applications should not inspect the data inside the bitmap.)

3. The Window Server passes the CFbsBitmap handle to the render stage chain.

4. The render stage identifies the bitmap as an extended bitmap, interprets the SVG data and generates the pixel data that is ultimately displayed on the screen.

The internal steps are different when an application uses the BitGDI API to draw the bitmap—for example, when an application draws the bitmap to an off-screen bitmap by using the BitGDI graphic context class, CFbsBitGc. For this to work, the device creator must provide an extended bitmap rasterizer DLL that converts the compressed data to pixel data. However, this is also transparent to the application.

Extended bitmaps have the following advantages:

• Existing applications can use extended bitmaps without modification.

• Extended bitmaps provide a mechanism for using compressed formats (such as vector data) that are much more compact than raster data. This is an important consideration for high screen resolutions.

Architecture

The following diagram shows the main participants in the extended bitmap framework. It is the device creator's responsibility to provide appropriate support for the extended bitmap format in the render stage and a suitable extended bitmap rasterizer DLL, if support for drawing the extended bitmap through the BitGDI API is required.

Although it is not possible to have more than one extended bitmap rasterizer DLL on a device, an extended bitmap rasterizer DLL can support more than one type of proprietary data. Similarly, support for multiple data formats can be added to render stages.

The data format can be identified from the type UID. When you implement the extended bitmap feature in a device, you must obtain UIDs for the format(s) that you want to support from Symbian Signed in the normal way.

The Symbian platform does not define any compression formats apart from those that are supported natively. It therefore does not provide an implementation of an extended bitmap rasterizer. However, it does provide a stub implementation and an example implementation, which device creators can use as a reference when creating their own extended bitmap rasterizers.

Related APIs

This section summarizes the extended bitmap APIs. Note that the extended bitmap feature is new in Symbian^3.

TBitmapfileCompression

The TBitmapfileCompression enum has a new value, EProprietaryCompression, which represents an extended bitmap.

CFbsBitmap

The following table provides a summary of the new CFbsBitmap functions that provide support for extended bitmaps.

Here is a code snippet that shows how a content provider can create an extended bitmap:

const TUid KUidMyProprietaryFormat = { <UID in hex> };
const TSize KSize(640, 480);
const TInt KDataSize = 100;
    
// Only needed if not connected to the Window Server.
User::LeaveIfError(RFbsSession::Connect());
    
CFbsBitmap* bmp = new(ELeave) CFbsBitmap();
    
CleanupStack::PushL(bmp);
    
MFbsExtendedBitmapInitializer* initializer = GetMyInitializerL();
    
User::LeaveIfError(bmp->CreateExtendedBitmap(KSize, EColor16MAP, KUidMyProprietaryFormat, 
                                             KDataSize, *initializer));

The following CFbsBitmap functions provide support for extended bitmaps, provided a suitable extended bitmap rasterizer DLL is available:

• CFbsBitmap::GetPixel()
• CFbsBitmap::GetScanLine()
• CFbsBitmap::GetVerticalScanLine()

It is possible to access the proprietary data inside an extended bitmap by calling the CFbsBitmap::DataAddress() function. For example, the render stage that decompresses the extended bitmap makes use of this function. Note that clients must not modify the proprietary data.

CFbsRasterizer

This is an interface for which the extended bitmap rasterizer DLL must provide an implementation. See Creating an Extended Bitmap Rasterizer for more information.