<?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-12BB6113-216F-53BB-85FE-E14A6A6A2F8B" xml:lang="en"><title>Image
Compatibility Use Cases</title><shortdesc>This topic explains the four use cases from which the image compatibility
guarantees that are provided by the Graphics Resource component derive. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
audience</b>: Device creators. </p>
<p>The use cases are: </p>
<ul>
<li id="GUID-418ED281-C4F1-54FE-8B9A-491B88E99E5B"><xref href="GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B.dita#GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B/GUID-D8B0B3C7-5FC7-5F57-8A9C-2F261DCFCAA9">Constant images</xref></li>
<li id="GUID-DE1565D6-2300-567A-AFD4-EAF20BCD40FC"><xref href="GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B.dita#GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B/GUID-6F77A653-5150-5515-A185-D883BCE84368">Application-level CPU rendering</xref></li>
<li id="GUID-9B18F4F9-6ED3-5A97-B17C-6A006B6562C5"><xref href="GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B.dita#GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B/GUID-FABC1276-E9D5-567D-B283-76475D2C8359">Off-screen rendering</xref></li>
<li id="GUID-E1C783A5-890B-5413-BC52-FC1C4FBBE559"><xref href="GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B.dita#GUID-12BB6113-216F-53BB-85FE-E14A6A6A2F8B/GUID-8EE28379-94E9-5029-9995-11CAE9D2D89A">UI surface rendering</xref></li>
</ul>
<section id="GUID-D8B0B3C7-5FC7-5F57-8A9C-2F261DCFCAA9"><title> Constant images </title> <p>A
constant image is not modified after creation. A typical example of a constant
image is an icon that is loaded from a file and does not change. </p> <p>A
constant image has the following guaranteed set of attributes: </p> <ul>
<li id="GUID-92AFB961-628D-5717-851B-5D15208A2219"><p>The image cannot be
changed. </p> </li>
<li id="GUID-86C067BD-3A1D-5CA9-9B14-3B687CDD5C50"><p>Applications cannot
have direct access to the pixels (no CPU access). </p> </li>
<li id="GUID-0B8693D6-1DD7-5857-ABE3-79894B7849E7"><p>The image may only be
used as a source for DirectGDI* or <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>
<li id="GUID-E9B32C32-E752-5774-A389-8A64578FB3AE"><p>The screen ID can be
-1 or the ID of a screen on the phone. For example, on a device that has a
single screen, it can be -1 or 0. -1 indicates "screen agnostic", which means
that the image can be rendered on any screen. This is the only use case for
which this is guaranteed. </p> </li>
<li id="GUID-F8CF2787-F718-5BB0-AD85-F4FC809C28DA"><p>The pixel size can be
any size, subject to memory available for use. </p> </li>
<li id="GUID-01058E49-F28C-5B7A-8D87-13AA11F1D189"><p>The image may be sharable
or non-sharable. </p> </li>
</ul> <p>A constant image is one that is created with no request for CPU write
access and no request for use as a rendering target. For more information,
see <xref href="GUID-FE0BB820-00B3-3E13-907A-FAFB2D20D43B.dita"><apiname>TSgImageInfo</apiname></xref>. </p> <p>This use case covers images created
using <codeph>RSgImage::Create()</codeph> where the user provides the initial
data. </p> <p>The pixel formats supported for this use case are: </p> <table id="GUID-35174611-684B-5506-A511-96D5F9CB45EF">
<tgroup cols="1"><colspec colname="col0"/>
<tbody>
<row>
<entry><p> <codeph>EUidPixelFormatARGB_8888_PRE</codeph></p> </entry>
</row>
<row>
<entry><p><codeph>EUidPixelFormatXRGB_8888</codeph> </p> </entry>
</row>
<row>
<entry><p> <codeph>EUidPixelFormatARGB_8888</codeph></p> </entry>
</row>
<row>
<entry><p> <codeph>EUidPixelFormatRGB_565</codeph></p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>* If DirectGDI is present on the platform. </p> </section>
<section id="GUID-6F77A653-5150-5515-A185-D883BCE84368"><title> Application-level
CPU rendering </title> <p>This use case corresponds to an image that is modified
directly by an application, without the use of rendering functions provided
by the platform. For example, a game that uses its own rendering functions. </p> <p>The
set of guaranteed attributes for this type of image are: </p> <ul>
<li id="GUID-59B85742-F5F5-5930-931B-9A3B487F2209"><p>The image can be changed
(it is mutable). </p> </li>
<li id="GUID-B1252595-8891-5A86-B004-D307FC518B5F"><p>The application can
have direct read and write access to the pixel data. </p> </li>
<li id="GUID-B2F732B6-EC1E-5D11-912B-38025979681A"><p>Support is only guaranteed
for usage as a source for DirectGDI* or <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>
<li id="GUID-444F5D1F-FE88-59E9-8844-35EC97A10B25"><p>Support is only guaranteed
if the image is tied to one screen. The screen ID must therefore be the actual
ID of one of the screens on the device. If the image needs to be used on multiple
screens, multiple copies of the image may be required. </p> </li>
<li id="GUID-A1522C8E-57F6-5A08-884F-60A3586876D8"><p>The image size (size
in pixels) is limited only by memory availability. </p> </li>
<li id="GUID-0746CAB1-3181-5998-B8F4-48F2A037CA71"><p>The image may be sharable
or non-sharable. </p> </li>
</ul> <p>To allow the CPU to access the pixel data, a developer can use the
following functions: </p> <table id="GUID-DA69A90D-0517-569B-9B7E-3C8562AEC8FF">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <xref href="GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C.dita#GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C/GUID-73EDBD53-DA17-32B7-9DE3-E151EAC5EDE0"><apiname>RSgImage::MapReadOnly()</apiname></xref>  </p> </entry>
<entry><p>Makes pixel data accessible for reading by the CPU </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C.dita#GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C/GUID-7BB75B50-5EF0-3AB1-B44E-4756CDCB98C9"><apiname>RSgImage::MapWriteOnly()</apiname></xref>  </p> </entry>
<entry><p>Makes pixel data accessible for writing by the CPU </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C.dita#GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C/GUID-9AF1743D-BB04-3F02-B5C7-2AB6FE2EA3DC"><apiname>RSgImage::MapReadWrite()</apiname></xref>  </p> </entry>
<entry><p>Makes pixel data accessible for reading and writing by the CPU </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C.dita#GUID-EDC0E03F-37F6-3BEC-8FF3-D03C3CDB949C/GUID-A4549751-8EDE-3202-8C97-E83A5DA96B59"><apiname>RSgImage::Unmap()</apiname></xref>  </p> </entry>
<entry><p>Makes pixel data not accessible for reading or writing by the CPU </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>The pixel formats supported for this use case are: </p> <table id="GUID-6EF641DF-4E27-50AD-9944-30530E90B480">
<tgroup cols="1"><colspec colname="col0"/>
<tbody>
<row>
<entry><p> <codeph>EUidPixelFormatARGB_8888_PRE</codeph>  </p> </entry>
</row>
<row>
<entry><p> <codeph>EUidPixelFormatXRGB_8888</codeph>  </p> </entry>
</row>
<row>
<entry><p> <codeph>EUidPixelFormatRGB_565</codeph>  </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>* If DirectGDI is present on the platform. </p> </section>
<section id="GUID-FABC1276-E9D5-567D-B283-76475D2C8359"><title>Off-screen
rendering</title> <p>This use case corresponds to images that are used to
store the results of rendering pipelines provided by the platform; for example
DirectGDI, OpenGLES or OpenVG. </p> <p>The set of guaranteed attributes for
this type of image are: </p> <ul>
<li id="GUID-033AB275-3620-5450-9197-DEB511AB05ED"><p>The image can be changed
(it is mutable) </p> </li>
<li id="GUID-8E34E82E-84E6-5B3D-A20E-363328248418"><p>The application cannot
have direct access to the pixels on the image to read or write (no CPU access) </p> </li>
<li id="GUID-94C54C9A-AC49-5043-A052-447A37A72ACB"><p>The image can be used
as a: </p> <ul>
<li id="GUID-56F5941B-8197-505E-B086-685DA4F0BFB0"><p>Target for DirectGDI*,
OpenGLES** or OpenVG*** rendering. </p> </li>
<li id="GUID-13AD417E-70FE-56E2-B708-35CDD61896F7"><p>Source for DirectGDI*
or <xref href="GUID-FE0BB820-00B3-3E13-907A-FAFB2D20D43B.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>
</ul> </li>
<li id="GUID-96F8EF27-E215-5A23-A4B5-44CCBBF609F3"><p>Support is only guaranteed
if the image is tied to one screen. The screen ID must therefore be the actual
ID of one of the screens on the device. If the image needs to be used on multiple
screens, multiple copies of the image may be required. </p> </li>
<li id="GUID-D927209A-6913-52E2-9571-2153C74AC937"><p>The image size (in pixels)
is limited only by memory availability </p> </li>
<li id="GUID-EB99D1C1-7462-5A7C-9DFB-BB753C119236"><p>The image may be sharable
or non-sharable. </p> </li>
</ul> <p>The pixel formats supported for this use case are: </p> <table id="GUID-90B13F9C-EAFB-5BD7-80B2-6AC1C8695EBA">
<tgroup cols="1"><colspec colname="col0"/>
<tbody>
<row>
<entry><p>At least one RGB format <b>with an alpha channel</b>, and a minimum
of 8 bits per channel. Channel ordering is not specified </p> </entry>
</row>
<row>
<entry><p>At least one RGB format <b>with no alpha channel</b>, and a minimum
of 8 bits per channel. Channel ordering is not specified. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>* If DirectGDI is present on the platform. </p> <p>** If OpenGL
ES is present on the platform. </p> <p>*** If OpenVG is present on the platform. </p> </section>
<section id="GUID-8EE28379-94E9-5029-9995-11CAE9D2D89A"><title> UI surface
rendering </title> <p>This use case corresponds to an image that is created
by the Window Server to transfer UI rendering into the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">composition
engine</xref>. This use case only applies to the creation of <xref href="GUID-FE0BB820-00B3-3E13-907A-FAFB2D20D43B.dita"><apiname>RSgImageCollection</apiname></xref> instances. </p> <p>The
set of guaranteed attributes for this type of image are: </p> <ul>
<li id="GUID-B1973F49-7495-5893-B07E-8B76960112C9"><p>The image can be changed
(it is mutable) </p> </li>
<li id="GUID-B1BE0B2C-E47F-5362-8846-5A5336AD8554"><p>The user does not require
direct access to the image pixels (no CPU access) </p> </li>
<li id="GUID-4F329D2C-314D-52A9-BEE6-28B030F6E547"><p>The image can be used
as a: </p> <ul>
<li id="GUID-75492618-1372-51CF-8AB7-3A656FCF4A09"><p>Target for DirectGDI*,
OpenGLES** or OpenVG*** rendering </p> </li>
<li id="GUID-30826072-D8F2-576E-9FD0-A572EE92C429"><p>Composition source,
which means that it is used as input to the composition engine </p> </li>
<li id="GUID-96567159-5753-5792-BA25-E352603676D1"><p>Screen source, which
means that the display hardware can read it directly </p> </li>
</ul> </li>
<li id="GUID-C0777DB4-904F-5477-90F2-E680783BF5F8"><p>Support is only guaranteed
if the image is tied to one screen. The screen ID must therefore be the actual
ID of one of the screens on the device. </p> </li>
<li id="GUID-B5F4FC50-732E-546B-AFDA-9E4B787E5D51"><p>The image size must
be supported by the specified screen. </p> </li>
<li id="GUID-175F2884-02D9-5D27-840E-466CEBFADA1C"><p>The image is not shareable
between processes. </p> </li>
</ul> <p>The pixel formats supported for this use case are: </p> <table id="GUID-1B522269-38E0-5F09-8909-AF2C2AF22048">
<tgroup cols="1"><colspec colname="col0"/>
<tbody>
<row>
<entry><p>At least one RGB format <b>with an alpha channel</b>, and a minimum
of 8 bits per channel. Channel ordering is not specified. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>* If DirectGDI is present on the platform. </p> <p>** If OpenGL
ES is present on the platform. </p> <p>*** If OpenVG is present on the platform. </p> </section>
</conbody><related-links>
<link href="GUID-29C7FBFB-2F33-58CA-86BE-978E3187E4D6.dita"><linktext>Image Compatibility
Guarantees</linktext></link>
<link href="GUID-69E426EC-CDBB-5B19-8264-050EB93B9315.dita"><linktext>Supported
Image Formats</linktext></link>
<link href="GUID-610C1484-112E-5442-95DC-89CF890A8310.dita"><linktext>Pixel Formats</linktext>
</link>
</related-links></concept>