Extended -Bitmaps

Extended -BitmapsThe Font and Bitmap Server provides a framework for device creators -to add support for their own types of bitmap compression. Bitmaps that use -compression formats that are provided by device creators are known as 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.

- Creating -an Extended Bitmap Rasterizer -Render Stages - -Font and -Bitmap Server Overview + + + + + +Extended +BitmapsThe Font and Bitmap Server provides a framework for device creators +to add support for their own types of bitmap compression. Bitmaps that use +compression formats that are provided by device creators are known as 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.

+ Creating +an Extended Bitmap Rasterizer +Render Stages + +Font and +Bitmap Server Overview

\ No newline at end of file