<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-D76C7759-739D-5C98-B718-7297687FE630" xml:lang="en"><title>Extended
Bitmaps</title><shortdesc>The 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. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> and <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref>. <b>Target
audience</b>: Device creators. </p>
<section><title>Natively supported bitmap formats</title> <p>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. </p> <p>The
natively-supported compression types are enumerated in <xref href="GUID-6E40B867-F7C6-35EA-8C6F-F54AB11BDD6E.dita"><apiname>TBitmapfileCompression</apiname></xref>.
You can use the Bitmap Conversion Tool to generate compressed bitmaps. In
addition, you can compress bitmaps at runtime by calling <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-A6DEEA44-5EFF-3260-B003-35A6C9B0E70B"><apiname>CFbsBitmap::Compress()</apiname></xref> and <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-0098D4B6-35F3-31DB-ADCE-9586601AAAFA"><apiname>CFbsBitmap::CompressInBackground()</apiname></xref>. </p> </section>
<section><title>The extended bitmap approach</title> <p>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 <b>extended bitmaps</b>.
The Font and Bitmap Server simply stores the compressed data and does not
interpret it in any way. </p> <p>The key features of extended bitmaps are: </p> <ul>
<li id="GUID-57B99A75-79AB-50FD-BC32-E9B3D6D4D4BA"><p>They are read-only. </p> </li>
<li id="GUID-32159A2F-DEF7-562D-BAC7-0C782F292E8C"><p>They have a type, which
is unique ID (UID) that identifies the proprietary data format. </p> </li>
<li id="GUID-D972ECDE-FDDC-5518-999B-591FC22C5BE6"><p>There are no restrictions
on the data format. </p> </li>
<li id="GUID-47813A67-8550-51FB-8DFA-E911322EE9DC"><p>When an extended bitmap
cannot be decompressed for some reason, it is rendered as solid white. </p> </li>
</ul> <p>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 <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>) for
on-screen rendering or the BitGDI API for off-screen rendering and Direct
Screen Access (DSA). </p> <p>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. </p> <fig id="GUID-690043B5-EF70-59BB-87D4-8B0B6EEA3F31">
<title>              Example extended bitmap scenario            </title>
<image href="GUID-970A2948-5A72-5E92-84C0-86DDEE59A569_d0e264372_href.png" placement="inline"/>
</fig> <p>This is how it works: </p> <ol id="GUID-2B3B99F0-BF43-5F1C-A86E-5E9605460D7E">
<li id="GUID-77F3E86D-7FC1-5682-90C0-EE83C8C39A22"><p>An engine or server
(the Theme Server in this example) creates an extended bitmap that stores
the icon's SVG data. </p> </li>
<li id="GUID-3F46695F-DAD7-58D8-822A-18EB89A0D119"><p>To the application,
the bitmap appears like an ordinary compressed XIP ROM-based bitmap. The application
simply calls <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita#GUID-0AEE5955-C530-35F1-A904-69183331B294/GUID-1A360BAF-D2EF-3D96-8E6A-C399631EFBB9"><apiname>CWindowGc::DrawBitmap()</apiname></xref> in the normal way,
passing in the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> handle. (Applications should
not inspect the data inside the bitmap.) </p> </li>
<li id="GUID-557E0CDF-6B80-5D9F-B64B-2CA6571F7474"><p>The Window Server passes
the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> handle to the <xref href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita">render
stage chain</xref>. </p> </li>
<li id="GUID-7519E0F4-37FA-5B52-8060-73EE6E347C89"><p>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. </p> </li>
</ol> <p>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, <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref>.
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. </p> <p>Extended bitmaps have the following
advantages: </p> <ul>
<li id="GUID-BAF6B974-AD40-58C2-AF10-9A9A894F8AAB"><p>Existing applications
can use extended bitmaps without modification. </p> </li>
<li id="GUID-33427210-B60D-55C0-BB00-02BE2559FD56"><p>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. </p> </li>
</ul> </section>
<section><title>Architecture</title><p>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.</p><fig id="GUID-3A965E47-106D-4EC3-BCFA-E2D40EDB2647">
<title>The main participants in the extended bitmap framework, showing the
dependencies </title>
<image href="GUID-A67FFE7B-9573-543B-B3EA-0539278FE4AB_d0e264452_href.png" placement="inline"/>
</fig><p>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.</p><p> 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. </p><p>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.</p></section>
<section><title>Related APIs</title> <p>This section summarizes the extended
bitmap APIs. Note that the extended bitmap feature is new in Symbian^3. </p> <p><b>TBitmapfileCompression </b> </p> <p>The <xref href="GUID-6E40B867-F7C6-35EA-8C6F-F54AB11BDD6E.dita"><apiname>TBitmapfileCompression</apiname></xref> enum has a new value, <codeph>EProprietaryCompression</codeph>, which represents
an extended bitmap. </p> <p><b>CFbsBitmap </b> </p> <p>The following table
provides a summary of the new <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> functions that
provide support for extended bitmaps. </p> <table id="GUID-7CF90E7D-1908-50FB-84AB-36F04B04E2DF">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Function</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-F2AAAC53-3D74-3C9F-B275-58BD5FF81C85"><apiname>CFbsBitmap::CreateExtendedBitmap()</apiname></xref>  </p> </entry>
<entry><p>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 <xref href="GUID-C950A55E-B52A-3680-B897-04E7C3A7BB71.dita"><apiname>MFbsExtendedBitmapInitializer</apiname></xref> interface.
The second overload is the recommended approach because it avoids unnecessary
memory copying. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-9274BB13-2BE4-3B3B-A55C-2500E2FE432C"><apiname>CFbsBitmap::ExtendedBitmapType()</apiname></xref>  </p> </entry>
<entry><p>Gets the UID of the proprietary data format. Returns null if it
is not an extended bitmap. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-BF789218-A647-3D94-AF56-05265C45F7E7"><apiname>CFbsBitmap::DataSize()</apiname></xref>  </p> </entry>
<entry><p>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). </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>Here is a code snippet that shows how a content provider can create
an extended bitmap: </p> <codeblock id="GUID-4511B5FF-1A17-5B8B-8471-C6F696D049F3" xml:space="preserve">const TUid KUidMyProprietaryFormat = { &lt;UID in hex&gt; };
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-&gt;CreateExtendedBitmap(KSize, EColor16MAP, KUidMyProprietaryFormat, 
                                             KDataSize, *initializer));</codeblock> <p>The
following <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> functions provide support for extended
bitmaps, provided a suitable extended bitmap rasterizer DLL is available: </p> <ul>
<li id="GUID-6ABAA42C-1270-5F5C-9D4E-7F1750C05659"><xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-838CF3C5-C513-33B7-9C81-0EBCE075F6B7"><apiname>CFbsBitmap::GetPixel()</apiname></xref> </li>
<li id="GUID-876BA701-AE33-515F-8756-6052A37991F8"><xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-D24300BA-20D7-34E6-BD23-ED281A0D957E"><apiname>CFbsBitmap::GetScanLine()</apiname></xref> </li>
<li id="GUID-152C155E-94DB-5462-80EE-AF409C001B49"><xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-57BC8EB1-B9F4-39A9-A18B-594CFB7786B6"><apiname>CFbsBitmap::GetVerticalScanLine()</apiname></xref> </li>
</ul> <p>It is possible to access the proprietary data inside an extended
bitmap by calling the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-2AB943ED-7DBE-3FDA-82AF-317F152EDB03"><apiname>CFbsBitmap::DataAddress()</apiname></xref> 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. </p> <p><b>CFbsRasterizer </b> </p> <p>This
is an interface for which the extended bitmap rasterizer DLL must provide
an implementation. See <xref href="GUID-E6E6A439-B3CC-5FEA-9148-2DB5F37003F2.dita">Creating
an Extended Bitmap Rasterizer</xref> for more information. </p> </section>
</conbody><related-links>
<link href="GUID-E6E6A439-B3CC-5FEA-9148-2DB5F37003F2.dita"><linktext> Creating
an Extended Bitmap Rasterizer</linktext></link>
<link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext>
</link>
<link href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita"><linktext>Font and
Bitmap Server Overview</linktext></link>
</related-links></concept>