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-12BB6113-216F-53BB-85FE-E14A6A6A2F8B" xml:lang="en"><title>Image

    13 Compatibility Use Cases</title><shortdesc>This topic explains the four use cases from which the image compatibility

    14 guarantees that are provided by the Graphics Resource component derive. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target

    16 audience</b>: Device creators. </p>

    17 <p>The use cases are: </p>

    18 <ul>

    19 <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>

    20 <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>

    21 <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>

    22 <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>

    23 </ul>

    24 <section id="GUID-D8B0B3C7-5FC7-5F57-8A9C-2F261DCFCAA9"><title> Constant images </title> <p>A

    25 constant image is not modified after creation. A typical example of a constant

    26 image is an icon that is loaded from a file and does not change. </p> <p>A

    27 constant image has the following guaranteed set of attributes: </p> <ul>

    28 <li id="GUID-92AFB961-628D-5717-851B-5D15208A2219"><p>The image cannot be

    29 changed. </p> </li>

    30 <li id="GUID-86C067BD-3A1D-5CA9-9B14-3B687CDD5C50"><p>Applications cannot

    31 have direct access to the pixels (no CPU access). </p> </li>

    32 <li id="GUID-0B8693D6-1DD7-5857-ABE3-79894B7849E7"><p>The image may only be

    33 used as a source for DirectGDI* or <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>

    34 <li id="GUID-E9B32C32-E752-5774-A389-8A64578FB3AE"><p>The screen ID can be

    35 -1 or the ID of a screen on the phone. For example, on a device that has a

    36 single screen, it can be -1 or 0. -1 indicates "screen agnostic", which means

    37 that the image can be rendered on any screen. This is the only use case for

    38 which this is guaranteed. </p> </li>

    39 <li id="GUID-F8CF2787-F718-5BB0-AD85-F4FC809C28DA"><p>The pixel size can be

    40 any size, subject to memory available for use. </p> </li>

    41 <li id="GUID-01058E49-F28C-5B7A-8D87-13AA11F1D189"><p>The image may be sharable

    42 or non-sharable. </p> </li>

    43 </ul> <p>A constant image is one that is created with no request for CPU write

    44 access and no request for use as a rendering target. For more information,

    45 see <xref href="GUID-FE0BB820-00B3-3E13-907A-FAFB2D20D43B.dita"><apiname>TSgImageInfo</apiname></xref>. </p> <p>This use case covers images created

    46 using <codeph>RSgImage::Create()</codeph> where the user provides the initial

    47 data. </p> <p>The pixel formats supported for this use case are: </p> <table id="GUID-35174611-684B-5506-A511-96D5F9CB45EF">

    48 <tgroup cols="1"><colspec colname="col0"/>

    49 <tbody>

    50 <row>

    51 <entry><p> <codeph>EUidPixelFormatARGB_8888_PRE</codeph></p> </entry>

    52 </row>

    53 <row>

    54 <entry><p><codeph>EUidPixelFormatXRGB_8888</codeph> </p> </entry>

    55 </row>

    56 <row>

    57 <entry><p> <codeph>EUidPixelFormatARGB_8888</codeph></p> </entry>

    58 </row>

    59 <row>

    60 <entry><p> <codeph>EUidPixelFormatRGB_565</codeph></p> </entry>

    61 </row>

    62 </tbody>

    63 </tgroup>

    64 </table> <p>* If DirectGDI is present on the platform. </p> </section>

    65 <section id="GUID-6F77A653-5150-5515-A185-D883BCE84368"><title> Application-level

    66 CPU rendering </title> <p>This use case corresponds to an image that is modified

    67 directly by an application, without the use of rendering functions provided

    68 by the platform. For example, a game that uses its own rendering functions. </p> <p>The

    69 set of guaranteed attributes for this type of image are: </p> <ul>

    70 <li id="GUID-59B85742-F5F5-5930-931B-9A3B487F2209"><p>The image can be changed

    71 (it is mutable). </p> </li>

    72 <li id="GUID-B1252595-8891-5A86-B004-D307FC518B5F"><p>The application can

    73 have direct read and write access to the pixel data. </p> </li>

    74 <li id="GUID-B2F732B6-EC1E-5D11-912B-38025979681A"><p>Support is only guaranteed

    75 for usage as a source for DirectGDI* or <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>

    76 <li id="GUID-444F5D1F-FE88-59E9-8844-35EC97A10B25"><p>Support is only guaranteed

    77 if the image is tied to one screen. The screen ID must therefore be the actual

    78 ID of one of the screens on the device. If the image needs to be used on multiple

    79 screens, multiple copies of the image may be required. </p> </li>

    80 <li id="GUID-A1522C8E-57F6-5A08-884F-60A3586876D8"><p>The image size (size

    81 in pixels) is limited only by memory availability. </p> </li>

    82 <li id="GUID-0746CAB1-3181-5998-B8F4-48F2A037CA71"><p>The image may be sharable

    83 or non-sharable. </p> </li>

    84 </ul> <p>To allow the CPU to access the pixel data, a developer can use the

    85 following functions: </p> <table id="GUID-DA69A90D-0517-569B-9B7E-3C8562AEC8FF">

    86 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    87 <tbody>

    88 <row>

    89 <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>

    90 <entry><p>Makes pixel data accessible for reading by the CPU </p> </entry>

    91 </row>

    92 <row>

    93 <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>

    94 <entry><p>Makes pixel data accessible for writing by the CPU </p> </entry>

    95 </row>

    96 <row>

    97 <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>

    98 <entry><p>Makes pixel data accessible for reading and writing by the CPU </p> </entry>

    99 </row>

   100 <row>

   101 <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>

   102 <entry><p>Makes pixel data not accessible for reading or writing by the CPU </p> </entry>

   103 </row>

   104 </tbody>

   105 </tgroup>

   106 </table> <p>The pixel formats supported for this use case are: </p> <table id="GUID-6EF641DF-4E27-50AD-9944-30530E90B480">

   107 <tgroup cols="1"><colspec colname="col0"/>

   108 <tbody>

   109 <row>

   110 <entry><p> <codeph>EUidPixelFormatARGB_8888_PRE</codeph>  </p> </entry>

   111 </row>

   112 <row>

   113 <entry><p> <codeph>EUidPixelFormatXRGB_8888</codeph>  </p> </entry>

   114 </row>

   115 <row>

   116 <entry><p> <codeph>EUidPixelFormatRGB_565</codeph>  </p> </entry>

   117 </row>

   118 </tbody>

   119 </tgroup>

   120 </table> <p>* If DirectGDI is present on the platform. </p> </section>

   121 <section id="GUID-FABC1276-E9D5-567D-B283-76475D2C8359"><title>Off-screen

   122 rendering</title> <p>This use case corresponds to images that are used to

   123 store the results of rendering pipelines provided by the platform; for example

   124 DirectGDI, OpenGLES or OpenVG. </p> <p>The set of guaranteed attributes for

   125 this type of image are: </p> <ul>

   126 <li id="GUID-033AB275-3620-5450-9197-DEB511AB05ED"><p>The image can be changed

   127 (it is mutable) </p> </li>

   128 <li id="GUID-8E34E82E-84E6-5B3D-A20E-363328248418"><p>The application cannot

   129 have direct access to the pixels on the image to read or write (no CPU access) </p> </li>

   130 <li id="GUID-94C54C9A-AC49-5043-A052-447A37A72ACB"><p>The image can be used

   131 as a: </p> <ul>

   132 <li id="GUID-56F5941B-8197-505E-B086-685DA4F0BFB0"><p>Target for DirectGDI*,

   133 OpenGLES** or OpenVG*** rendering. </p> </li>

   134 <li id="GUID-13AD417E-70FE-56E2-B708-35CDD61896F7"><p>Source for DirectGDI*

   135 or <xref href="GUID-FE0BB820-00B3-3E13-907A-FAFB2D20D43B.dita"><apiname>CWindowGc</apiname></xref> rendering. </p> </li>

   136 </ul> </li>

   137 <li id="GUID-96F8EF27-E215-5A23-A4B5-44CCBBF609F3"><p>Support is only guaranteed

   138 if the image is tied to one screen. The screen ID must therefore be the actual

   139 ID of one of the screens on the device. If the image needs to be used on multiple

   140 screens, multiple copies of the image may be required. </p> </li>

   141 <li id="GUID-D927209A-6913-52E2-9571-2153C74AC937"><p>The image size (in pixels)

   142 is limited only by memory availability </p> </li>

   143 <li id="GUID-EB99D1C1-7462-5A7C-9DFB-BB753C119236"><p>The image may be sharable

   144 or non-sharable. </p> </li>

   145 </ul> <p>The pixel formats supported for this use case are: </p> <table id="GUID-90B13F9C-EAFB-5BD7-80B2-6AC1C8695EBA">

   146 <tgroup cols="1"><colspec colname="col0"/>

   147 <tbody>

   148 <row>

   149 <entry><p>At least one RGB format <b>with an alpha channel</b>, and a minimum

   150 of 8 bits per channel. Channel ordering is not specified </p> </entry>

   151 </row>

   152 <row>

   153 <entry><p>At least one RGB format <b>with no alpha channel</b>, and a minimum

   154 of 8 bits per channel. Channel ordering is not specified. </p> </entry>

   155 </row>

   156 </tbody>

   157 </tgroup>

   158 </table> <p>* If DirectGDI is present on the platform. </p> <p>** If OpenGL

   159 ES is present on the platform. </p> <p>*** If OpenVG is present on the platform. </p> </section>

   160 <section id="GUID-8EE28379-94E9-5029-9995-11CAE9D2D89A"><title> UI surface

   161 rendering </title> <p>This use case corresponds to an image that is created

   162 by the Window Server to transfer UI rendering into the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">composition

   163 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

   164 set of guaranteed attributes for this type of image are: </p> <ul>

   165 <li id="GUID-B1973F49-7495-5893-B07E-8B76960112C9"><p>The image can be changed

   166 (it is mutable) </p> </li>

   167 <li id="GUID-B1BE0B2C-E47F-5362-8846-5A5336AD8554"><p>The user does not require

   168 direct access to the image pixels (no CPU access) </p> </li>

   169 <li id="GUID-4F329D2C-314D-52A9-BEE6-28B030F6E547"><p>The image can be used

   170 as a: </p> <ul>

   171 <li id="GUID-75492618-1372-51CF-8AB7-3A656FCF4A09"><p>Target for DirectGDI*,

   172 OpenGLES** or OpenVG*** rendering </p> </li>

   173 <li id="GUID-30826072-D8F2-576E-9FD0-A572EE92C429"><p>Composition source,

   174 which means that it is used as input to the composition engine </p> </li>

   175 <li id="GUID-96567159-5753-5792-BA25-E352603676D1"><p>Screen source, which

   176 means that the display hardware can read it directly </p> </li>

   177 </ul> </li>

   178 <li id="GUID-C0777DB4-904F-5477-90F2-E680783BF5F8"><p>Support is only guaranteed

   179 if the image is tied to one screen. The screen ID must therefore be the actual

   180 ID of one of the screens on the device. </p> </li>

   181 <li id="GUID-B5F4FC50-732E-546B-AFDA-9E4B787E5D51"><p>The image size must

   182 be supported by the specified screen. </p> </li>

   183 <li id="GUID-175F2884-02D9-5D27-840E-466CEBFADA1C"><p>The image is not shareable

   184 between processes. </p> </li>

   185 </ul> <p>The pixel formats supported for this use case are: </p> <table id="GUID-1B522269-38E0-5F09-8909-AF2C2AF22048">

   186 <tgroup cols="1"><colspec colname="col0"/>

   187 <tbody>

   188 <row>

   189 <entry><p>At least one RGB format <b>with an alpha channel</b>, and a minimum

   190 of 8 bits per channel. Channel ordering is not specified. </p> </entry>

   191 </row>

   192 </tbody>

   193 </tgroup>

   194 </table> <p>* If DirectGDI is present on the platform. </p> <p>** If OpenGL

   195 ES is present on the platform. </p> <p>*** If OpenVG is present on the platform. </p> </section>

   196 </conbody><related-links>

   197 <link href="GUID-29C7FBFB-2F33-58CA-86BE-978E3187E4D6.dita"><linktext>Image Compatibility

   198 Guarantees</linktext></link>

   199 <link href="GUID-69E426EC-CDBB-5B19-8264-050EB93B9315.dita"><linktext>Supported

   200 Image Formats</linktext></link>

   201 <link href="GUID-610C1484-112E-5442-95DC-89CF890A8310.dita"><linktext>Pixel Formats</linktext>

   202 </link>

   203 </related-links></concept>