Extended +Bitmaps

Variant: ScreenPlay and non-ScreenPlay. Target +audience: Device creators.

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.

+ Example extended bitmap scenario + +

This is how it works:

An engine or server +(the Theme Server in this example) creates an extended bitmap that stores +the icon's SVG data.
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.)
The Window Server passes +the CFbsBitmap handle to the render +stage chain.
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.

+The main participants in the extended bitmap framework, showing the +dependencies + +

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.

+ + + +Function +Description + + + + +

CFbsBitmap::CreateExtendedBitmap()

Creates an extended bitmap. There are two overloads of this function. +They both have a parameter for the UID of the proprietary data format. One +takes a pointer to the raw data, whereas the other takes a pointer to an initializer, +which is an implementation of the MFbsExtendedBitmapInitializer interface. +The second overload is the recommended approach because it avoids unnecessary +memory copying.

+ + +

CFbsBitmap::ExtendedBitmapType()

Gets the UID of the proprietary data format. Returns null if it +is not an extended bitmap.

+ + +

CFbsBitmap::DataSize()

Returns the size in bytes of the data stored in the bitmap. For +an extended bitmap this is the size of the proprietary data (not the size +of the rasterized pixel data).

+ + + +

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.