|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D76C7759-739D-5C98-B718-7297687FE630" xml:lang="en"><title>Extended |
|
13 Bitmaps</title><shortdesc>The Font and Bitmap Server provides a framework for device creators |
|
14 to add support for their own types of bitmap compression. Bitmaps that use |
|
15 compression formats that are provided by device creators are known as extended |
|
16 bitmaps. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <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 |
|
18 audience</b>: Device creators. </p> |
|
19 <section><title>Natively supported bitmap formats</title> <p>Traditionally |
|
20 Symbian has provided native support for bitmaps in relatively simple formats, |
|
21 including the standard uncompressed bitmap format and bitmaps compressed using |
|
22 simple Run-Length Encoding (RLE). The uncompressed format stores scan lines |
|
23 as a sequence of individual colors, one for each pixel. The RLE compression |
|
24 instead breaks each scan line into runs of consecutive pixels of the same |
|
25 color. For each run it stores the color and the number of times it is repeated. |
|
26 The exact details of the compression formats are internal to Symbian. </p> <p>The |
|
27 natively-supported compression types are enumerated in <xref href="GUID-6E40B867-F7C6-35EA-8C6F-F54AB11BDD6E.dita"><apiname>TBitmapfileCompression</apiname></xref>. |
|
28 You can use the Bitmap Conversion Tool to generate compressed bitmaps. In |
|
29 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> |
|
30 <section><title>The extended bitmap approach</title> <p>The extended bitmap |
|
31 framework allows device creators to define and add their own compression formats. |
|
32 Bitmaps that are created using this framework are known as <b>extended bitmaps</b>. |
|
33 The Font and Bitmap Server simply stores the compressed data and does not |
|
34 interpret it in any way. </p> <p>The key features of extended bitmaps are: </p> <ul> |
|
35 <li id="GUID-57B99A75-79AB-50FD-BC32-E9B3D6D4D4BA"><p>They are read-only. </p> </li> |
|
36 <li id="GUID-32159A2F-DEF7-562D-BAC7-0C782F292E8C"><p>They have a type, which |
|
37 is unique ID (UID) that identifies the proprietary data format. </p> </li> |
|
38 <li id="GUID-D972ECDE-FDDC-5518-999B-591FC22C5BE6"><p>There are no restrictions |
|
39 on the data format. </p> </li> |
|
40 <li id="GUID-47813A67-8550-51FB-8DFA-E911322EE9DC"><p>When an extended bitmap |
|
41 cannot be decompressed for some reason, it is rendered as solid white. </p> </li> |
|
42 </ul> <p>There are two ways that the bitmap can be decompressed prior to rendering. |
|
43 Which one is used depends on whether the application draws the extended bitmap |
|
44 by using the Window Server API (such as <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>) for |
|
45 on-screen rendering or the BitGDI API for off-screen rendering and Direct |
|
46 Screen Access (DSA). </p> <p>To illustrate how it works, let us consider a |
|
47 scenario in which extended bitmaps are used to store SVG data. (In the broadest |
|
48 sense, you can consider SVG data to be a type of compression of bitmap data.) |
|
49 The following diagram shows how an extended bitmap that represents an icon |
|
50 is ultimately displayed on the screen. </p> <fig id="GUID-690043B5-EF70-59BB-87D4-8B0B6EEA3F31"> |
|
51 <title> Example extended bitmap scenario </title> |
|
52 <image href="GUID-970A2948-5A72-5E92-84C0-86DDEE59A569_d0e233664_href.png" placement="inline"/> |
|
53 </fig> <p>This is how it works: </p> <ol id="GUID-2B3B99F0-BF43-5F1C-A86E-5E9605460D7E"> |
|
54 <li id="GUID-77F3E86D-7FC1-5682-90C0-EE83C8C39A22"><p>An engine or server |
|
55 (the Theme Server in this example) creates an extended bitmap that stores |
|
56 the icon's SVG data. </p> </li> |
|
57 <li id="GUID-3F46695F-DAD7-58D8-822A-18EB89A0D119"><p>To the application, |
|
58 the bitmap appears like an ordinary compressed XIP ROM-based bitmap. The application |
|
59 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, |
|
60 passing in the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> handle. (Applications should |
|
61 not inspect the data inside the bitmap.) </p> </li> |
|
62 <li id="GUID-557E0CDF-6B80-5D9F-B64B-2CA6571F7474"><p>The Window Server passes |
|
63 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 |
|
64 stage chain</xref>. </p> </li> |
|
65 <li id="GUID-7519E0F4-37FA-5B52-8060-73EE6E347C89"><p>The render stage identifies |
|
66 the bitmap as an extended bitmap, interprets the SVG data and generates the |
|
67 pixel data that is ultimately displayed on the screen. </p> </li> |
|
68 </ol> <p>The internal steps are different when an application uses the BitGDI |
|
69 API to draw the bitmap—for example, when an application draws the bitmap to |
|
70 an off-screen bitmap by using the BitGDI graphic context class, <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref>. |
|
71 For this to work, the device creator must provide an extended bitmap rasterizer |
|
72 DLL that converts the compressed data to pixel data. However, this is also |
|
73 transparent to the application. </p> <p>Extended bitmaps have the following |
|
74 advantages: </p> <ul> |
|
75 <li id="GUID-BAF6B974-AD40-58C2-AF10-9A9A894F8AAB"><p>Existing applications |
|
76 can use extended bitmaps without modification. </p> </li> |
|
77 <li id="GUID-33427210-B60D-55C0-BB00-02BE2559FD56"><p>Extended bitmaps provide |
|
78 a mechanism for using compressed formats (such as vector data) that are much |
|
79 more compact than raster data. This is an important consideration for high |
|
80 screen resolutions. </p> </li> |
|
81 </ul> </section> |
|
82 <section><title>Architecture</title><p>The following diagram shows the main |
|
83 participants in the extended bitmap framework. It is the device creator's |
|
84 responsibility to provide appropriate support for the extended |
|
85 bitmap format in the render stage and a suitable extended bitmap rasterizer |
|
86 DLL, if support for drawing the extended bitmap through the BitGDI API is |
|
87 required.</p><fig id="GUID-3A965E47-106D-4EC3-BCFA-E2D40EDB2647"> |
|
88 <title>The main participants in the extended bitmap framework, showing the |
|
89 dependencies </title> |
|
90 <image href="GUID-A67FFE7B-9573-543B-B3EA-0539278FE4AB_d0e233744_href.png" placement="inline"/> |
|
91 </fig><p>Although it is not possible to have more than one extended bitmap |
|
92 rasterizer DLL on a device, an extended bitmap rasterizer DLL can support |
|
93 more than one type of proprietary data. Similarly, support for multiple data |
|
94 formats can be added to render stages.</p><p> The data format can be identified |
|
95 from the type UID. When you implement the extended bitmap feature in a device, |
|
96 you must obtain UIDs for the format(s) that you want to support from Symbian |
|
97 Signed in the normal way. </p><p>The Symbian platform does not define any |
|
98 compression formats apart from those that are supported natively. It therefore |
|
99 does not provide an implementation of an extended bitmap rasterizer. However, |
|
100 it does provide a stub implementation and an example implementation, which |
|
101 device creators can use as a reference when creating their own extended bitmap |
|
102 rasterizers.</p></section> |
|
103 <section><title>Related APIs</title> <p>This section summarizes the extended |
|
104 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 |
|
105 an extended bitmap. </p> <p><b>CFbsBitmap </b> </p> <p>The following table |
|
106 provides a summary of the new <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> functions that |
|
107 provide support for extended bitmaps. </p> <table id="GUID-7CF90E7D-1908-50FB-84AB-36F04B04E2DF"> |
|
108 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
109 <thead> |
|
110 <row> |
|
111 <entry>Function</entry> |
|
112 <entry>Description</entry> |
|
113 </row> |
|
114 </thead> |
|
115 <tbody> |
|
116 <row> |
|
117 <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> |
|
118 <entry><p>Creates an extended bitmap. There are two overloads of this function. |
|
119 They both have a parameter for the UID of the proprietary data format. One |
|
120 takes a pointer to the raw data, whereas the other takes a pointer to an initializer, |
|
121 which is an implementation of the <xref href="GUID-C950A55E-B52A-3680-B897-04E7C3A7BB71.dita"><apiname>MFbsExtendedBitmapInitializer</apiname></xref> interface. |
|
122 The second overload is the recommended approach because it avoids unnecessary |
|
123 memory copying. </p> </entry> |
|
124 </row> |
|
125 <row> |
|
126 <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> |
|
127 <entry><p>Gets the UID of the proprietary data format. Returns null if it |
|
128 is not an extended bitmap. </p> </entry> |
|
129 </row> |
|
130 <row> |
|
131 <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> |
|
132 <entry><p>Returns the size in bytes of the data stored in the bitmap. For |
|
133 an extended bitmap this is the size of the proprietary data (not the size |
|
134 of the rasterized pixel data). </p> </entry> |
|
135 </row> |
|
136 </tbody> |
|
137 </tgroup> |
|
138 </table> <p>Here is a code snippet that shows how a content provider can create |
|
139 an extended bitmap: </p> <codeblock id="GUID-4511B5FF-1A17-5B8B-8471-C6F696D049F3" xml:space="preserve">const TUid KUidMyProprietaryFormat = { <UID in hex> }; |
|
140 const TSize KSize(640, 480); |
|
141 const TInt KDataSize = 100; |
|
142 |
|
143 // Only needed if not connected to the Window Server. |
|
144 User::LeaveIfError(RFbsSession::Connect()); |
|
145 |
|
146 CFbsBitmap* bmp = new(ELeave) CFbsBitmap(); |
|
147 |
|
148 CleanupStack::PushL(bmp); |
|
149 |
|
150 MFbsExtendedBitmapInitializer* initializer = GetMyInitializerL(); |
|
151 |
|
152 User::LeaveIfError(bmp->CreateExtendedBitmap(KSize, EColor16MAP, KUidMyProprietaryFormat, |
|
153 KDataSize, *initializer));</codeblock> <p>The |
|
154 following <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> functions provide support for extended |
|
155 bitmaps, provided a suitable extended bitmap rasterizer DLL is available: </p> <ul> |
|
156 <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> |
|
157 <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> |
|
158 <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> |
|
159 </ul> <p>It is possible to access the proprietary data inside an extended |
|
160 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. |
|
161 For example, the render stage that decompresses the extended bitmap makes |
|
162 use of this function. Note that clients must not modify the proprietary data. </p> <p><b>CFbsRasterizer </b> </p> <p>This |
|
163 is an interface for which the extended bitmap rasterizer DLL must provide |
|
164 an implementation. See <xref href="GUID-E6E6A439-B3CC-5FEA-9148-2DB5F37003F2.dita">Creating |
|
165 an Extended Bitmap Rasterizer</xref> for more information. </p> </section> |
|
166 </conbody><related-links> |
|
167 <link href="GUID-E6E6A439-B3CC-5FEA-9148-2DB5F37003F2.dita"><linktext> Creating |
|
168 an Extended Bitmap Rasterizer</linktext></link> |
|
169 <link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext> |
|
170 </link> |
|
171 <link href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita"><linktext>Font and |
|
172 Bitmap Server Overview</linktext></link> |
|
173 </related-links></concept> |