Merge "Doc change: Add doc for GL texture declaration/filtering, hardwareAccelerated manifest attr." into honeycomb

docs/html/guide/appendix/market-filters.jd

@@ -24,6 +24,8 @@ manifest file to the configurations defined by the device, as well as other fact
 <li><a
 href="{@docRoot}guide/practices/compatibility.html">Android Compatibility</a></li>
 <li><code><a
+href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;</a></code></li>
+<li><code><a
 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
 <li><code><a
 href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code></li>
@@ -395,5 +397,12 @@ href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
 with alternative resources.</p>
     </td>
   </tr>
+  <tr>
+    <td><nobr><a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code
+&lt;supports-gl-texture&gt;}</a></nobr></td>
+    <td>
+      <p>Android Market filters the application unless one or more of the GL texture compression formats supported by the application are also supported by the device. </p>
+    </td>
+  </tr>
 </table>
 

docs/html/guide/guide_toc.cs

@@ -223,6 +223,7 @@
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></li>
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></li>
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/service-element.html">&lt;service&gt;</a></li>
+          <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;</a></li> 
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></li>  <!-- ##api level 4## -->
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></li>
           <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></li> <!-- ##api level 4## -->

docs/html/guide/topics/manifest/activity-element.jd

@@ -14,6 +14,7 @@ page.title=<activity>
           android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"]
           android:<a href="#exported">exported</a>=["true" | "false"]
           android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"]
+          android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"]
           android:<a href="#icon">icon</a>="<i>drawable resource</i>"
           android:<a href="#label">label</a>="<i>string resource</i>"
           android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" |
@@ -286,6 +287,24 @@ are both "{@code true}", this attribute trumps the other.  The affinity of the
 activity is ignored.  The activity is not re-parented, but destroyed.
 </p>
 
+<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt>
+<dd>Whether or not hardware-accelerated rendering should be enabled for this
+Activity &mdash; "{@code true}" if it should be enabled, and "{@code false}" if
+not. The default value is "{@code false}".
+
+<p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is
+available to applications, to improve performance for many common 2D graphics
+operations. When the hardware-accelerated renderer is enabled, most operations
+in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated.
+This results in smoother animations, smoother scrolling, and improved
+responsiveness overall, even for applications that do not explicitly make use
+the framework's OpenGL libraries. </p>
+
+<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable
+the hardware-accelerated renderer, test your application to ensure that it can
+make use of the renderer without errors.</p>
+</dd>
+
 <dt><a name="icon"></a>{@code android:icon}</dt>
 <dd>An icon representing the activity. The icon is displayed to users when 
 a representation of the activity is required on-screen.  For example, icons 

docs/html/guide/topics/manifest/application-element.jd

@@ -9,6 +9,7 @@ page.title=<application>
              android:<a href="#desc">description</a>="<i>string resource</i>"
              android:<a href="#enabled">enabled</a>=["true" | "false"]
              android:<a href="#code">hasCode</a>=["true" | "false"]
+             android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"]
              android:<a href="#icon">icon</a>="<i>drawable resource</i>"
              android:<a href="#killrst">killAfterRestore</a>=["true" | "false"]
              android:<a href="#label">label</a>="<i>string resource</i>"
@@ -108,7 +109,26 @@ The default value is "{@code true}".
 <p>
 An application would not have any code of its own only if it's using nothing
 but built-in component classes, such as an activity that uses the {@link 
-android.app.AliasActivity} class, a rare occurrence.
+android.app.AliasActivity} class, a rare occurrence.</p>
+</dd>
+
+<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt>
+<dd>Whether or not hardware-accelerated rendering should be enabled for all
+Activities and Views in this application &mdash; "{@code true}" if it
+should be enabled, and "{@code false}" if not. The default value is "{@code false}".
+
+<p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is
+available to applications, to improve performance for many common 2D graphics
+operations. When the hardware-accelerated renderer is enabled, most operations
+in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated.
+This results in smoother animations, smoother scrolling, and improved
+responsiveness overall, even for applications that do not explicitly make use
+the framework's OpenGL libraries. </p>
+
+<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable
+the hardware-accelerated renderer, test your application to ensure that it can
+make use of the renderer without errors.</p>
+</dd>
 
 <dt><a name="icon"></a>{@code android:icon}</dt>
 <dd>An icon for the application as whole, and the default icon for 

docs/html/guide/topics/manifest/manifest-intro.jd

@@ -83,6 +83,8 @@ other mention of the element name.
     <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration /&gt;</a>  <!-- ##api level 3## -->
     <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature /&gt;</a>  <!-- ##api level 4## -->
     <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens /&gt;</a>  <!-- ##api level 4## -->
+    <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">&lt;compatible-screens /&gt;</a>  <!-- ##api level 9## -->
+    <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture /&gt;</a>  <!-- ##api level 11## -->
 
     <a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
 

docs/html/guide/topics/manifest/supports-gl-texture-element.jd

@@ -0,0 +1,187 @@
+page.title=<supports-gl-texture>
+@jd:body
+
+<dl class="xml">
+
+<dt>syntax:</dt>
+<dd>
+<pre class="stx">
+&lt;supports-gl-texture android:<a href="#name">name</a>="<em>string</em>" /&gt;
+</pre>
+</dd>
+
+<dt>contained in:</dt>
+<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
+
+ <div class="sidebox-wrapper">
+  <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
+  <div id="qv-sub-rule">
+    <img src="{@docRoot}assets/images/icon_market.jpg"
+    style="float:left;margin:0;padding:0;">
+    <p style="color:#669999;">Android Market and <code
+    style="color:#669999;">&lt;supports-gl-texture&gt;</code> elements</p>
+    <p style="margin-top:1em;">Android Market filters applications according
+    to the texture compression formats that they support, to ensure that
+    they can be installed only on devices that can handle their textures
+    properly. Developers can use texture compression filtering
+    as a way of targeting specific device types, based on GPU platform.</p>
+    
+    <p style="margin-top:1em;" class="caution">For important information about how
+    Android Market uses <code>&lt;supports-gl-texture&gt;</code> elements as
+    the basis for filtering, please read <a href="#market-texture-filtering">Android
+    Market and texture compression filtering</a>, below.</p>
+</div> 
+</div>
+
+<dt>description:</dt>
+<dd>Declares a single GL texture compression format that is supported by
+the application.
+
+<p>An application "supports" a GL texture compression format if it is capable of
+providing texture assets that are compressed in that format, once the
+application is installed on a device. The application can provide the
+compressed assets locally, from inside the <code>.apk</code>, or it can download them
+from a server at runtime.</p>
+
+<p>Each <code>&lt;supports-gl-texture&gt;</code> element declares exactly one
+supported texture compression format, specified as the value of a
+<code>android:name</code> attribute. If your application supports multiple
+texture compression formats, you can declare multiple
+<code>&lt;supports-gl-texture&gt;</code> elements. For example:</p>
+
+<pre>&lt;supports-gl-texture android:name="GL_OES_compressed_ETC1_RGB8_texture" /&gt;
+&lt;supports-gl-texture android:name="GL_OES_compressed_paletted_texture" /&gt;</pre>
+
+<p>Declared <code>&lt;supports-gl-texture&gt;</code> elements are informational,
+meaning that the Android system itself does not examine the elements at install
+time to ensure matching support on the device. However, other services
+(such as Android Market) or applications can check your application's
+<code>&lt;supports-gl-texture&gt;</code> declarations as part of handling or
+interacting with your application. For this reason, it's very important that
+you declare all of the texture compression formats (from the list below) that
+your application is capable of supporting. </p>
+
+<p>Applications and devices typically declare their supported GL texture
+compression formats using the same set of well-known strings, as listed below.
+The set of format strings may grow over time, as needed, and since the values
+are strings, applications are free to declare other formats as needed.</p>
+
+<p>Assuming that the application is built with SDK Platform Tools r3 or higher,
+filtering based on the <code>&lt;supports-gl-texture></code> element is activated
+for all API levels.</p>
+
+<dt>attributes:</dt>
+
+<dd>
+<dl class="attr">
+
+  <dt><a name="name"></a>{@code android:name}</dt>
+  <dd>Specifies a single GL texture compression format supported by the application,
+  as a descriptor string. Common descriptor values are listed in the table below.
+
+<table>
+<tr>
+<th>Texture Compression Format Descriptor</th>
+<th>Comments</th>
+</tr>
+<tr>
+<td><code>GL_OES_compressed_ETC1_RGB8_texture</code></td>
+<td>Ericsson texture compression. Specified in OpenGL ES 2.0 and available in all
+Android-powered devices that support OpenGL ES 2.0.</td>
+</tr>
+<tr>
+<td><code>GL_OES_compressed_paletted_texture</code></td>
+<td>Generic paletted texture compression.</td>
+</tr>
+<tr>
+<td><code>GL_AMD_compressed_3DC_texture</code></td>
+<td>ATI 3Dc texture compression. </td>
+</tr>
+<tr>
+<td><code>GL_AMD_compressed_ATC_texture</code></td>
+<td>ATI texture compression. Available on devices running Adreno GPU, including
+HTC Nexus One, Droid Incredible, EVO, and others. For widest compatibility,
+devices may also declare a <code>&lt;supports-gl-texture&gt;</code> element with the
+descriptor <code>GL_ATI_texture_compression_atitc</code>. </td>
+</tr>
+<tr>
+<td><code>GL_EXT_texture_compression_latc</code></td>
+<td>Luminance alpha texture compression. </td>
+</tr>
+<tr>
+<td><code>GL_EXT_texture_compression_dxt1</code></td>
+<td>S3 DXT1 texture compression. Supported on devices running Nvidia Tegra2
+platform, including Motorala Xoom, Motorola Atrix, Droid Bionic, and
+others.</td>
+</tr>
+<tr>
+<td><code>GL_EXT_texture_compression_s3tc</code></td>
+<td>S3 texture compression, nonspecific to DXT variant. Supported on devices
+running Nvidia Tegra2 platform, including Motorala Xoom, Motorola Atrix, Droid
+Bionic, and others. If your application requires a specific DXT variant, declare
+that descriptor instead of this one.</td>
+</tr>
+<tr>
+<td><code>GL_IMG_texture_compression_pvrtc</code></td>
+<td>PowerVR texture compression. Available in devices running PowerVR SGX530/540
+GPU, such as Motorola DROID series; Samsung Galaxy S, Nexus S, and Galaxy Tab;
+and others.</td>
+</tr>
+</table>
+
+</dd>
+</dl></dd>
+
+<!-- ##api level indication##
+<dt>introduced in:</dt>
+<dd>API Level </dd>-->
+
+<dt>see also:</dt>
+<dd>
+  <ul>
+    <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li>
+  </ul>
+</dd>
+
+<h2 id="market-texture-filtering">Android Market and texture compression filtering</h2>
+
+<p>Android Market filters the applications that are visible to users, so that
+users can see and download only those applications that are compatible with
+their devices. One of the ways Market filters applications is by texture
+compression compatibility, giving you control over the availability of your
+application to various devices, based on the capabilities of their GPUs.</p>
+
+<p>To determine an application's texture compression compatibility with a given
+user's device, Android Market compares:</p>
+
+<ul>
+<li>Texture compression formats that are supported by the application &mdash;
+an application declares its supported texture compression formats in
+<code>&lt;supports-gl-texture&gt;</code> elements in its manifest <br/>with...</li>
+<li>Texture compression formats that are supported by the GPU on the device &mdash;
+a device reports the formats it supports as read-only system properties.</li>
+</ul>
+
+<p>Each time you upload an application to the Android Market Publisher Site,
+Android Market scans the application's manifest file and looks for any
+<code>&lt;supports-gl-texture&gt;</code> elements. It extracts the
+format descriptors from the elements and stores them internally as
+metadata associated with the application <code>.apk</code> and the application
+version. </p>
+
+<p>When a user searches or browses for applications on Android Market,
+the service compares the texture compression formats supported by the application
+with those supported by the user's device. The comparison is based on the format
+descriptor strings and a match must be exact.</p>
+
+<p>If <em>any</em> of an application's supported texture compression formats is
+also supported by the device, Android Market allows the user to see the
+application and potentially download it. Otherwise, if none of the application's
+formats is supported by the device, Android Market filters the application so
+that it is not available for download. </p>
+
+<p>If an application does not declare any <code>&lt;supports-gl-texture&gt;</code> elements,
+Android Market does not apply any filtering based on GL texture compression format.</p>
+
+</dl>
+