Merge "docs: Re-write of OpenGL Framework topic bug 4285030"

2 files changed, 214 insertions, 43 deletions

diff --git a/docs/html/guide/topics/graphics/index.jd b/docs/html/guide/topics/graphics/index.jd
index be1b0fc..2490e39 100644
--- a/docs/html/guide/topics/graphics/index.jd
+++ b/docs/html/guide/topics/graphics/index.jd
@@ -14,13 +14,20 @@ page.title=Graphics
     </ol>
     </li>
   </ol>
+  <h2>See also</h2>
+  <ol>
+    <li><a href="{@docRoot}guide/topics/graphics/opengl.html">3D with OpenGL</a></li>
+    <li><a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a></li>
+  </ol>
   </div>
 </div>
-<p>Android graphics are powered by a custom 2D graphics library and OpenGL ES 1.0
-for high performance 3D graphics. The most common 2D graphics APIs can be found in the 
-{@link android.graphics.drawable drawable package}. OpenGL APIs are available
-from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES package},
-plus some Android {@link android.opengl OpenGL utilities}.</p>
+
+<p>Android graphics are powered by a custom 2D graphics library, and the framework provides
+support for high performance 3D graphics in the form of OpenGL ES and RenderScript. The most
+common 2D graphics APIs can be found in the {@link android.graphics.drawable drawable package}.
+OpenGL APIs are available from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES} and
+the {@link android.opengl} packages. The RenderScript APIs are available in the 
+{@link android.renderscript} package.</p>
 
 <p>When starting a project, it's important to consider exactly what your graphical demands will be. 
 Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations
@@ -32,10 +39,10 @@ and which tasks they're best suited for.</p>
 
 <p>If you're specifically looking for information on drawing 3D graphics, this page won't
 help a lot. However, the information below about how to <a href="#draw-with-canvas">Draw with a
-Canvas</a> (and the section on SurfaceView), 
-will give you a quick idea of how you should draw to the View hierarchy. For more information
-on Android's 3D graphic utilities (provided by the OpenGL ES API), 
-read <a href="opengl.html">3D with OpenGL</a> and refer to other OpenGL documentation.</p>
+Canvas</a> (and the section on SurfaceView), will give you a quick idea of how you should draw to
+the View hierarchy. For more information on Android's 3D graphics APIs, see
+the <a href="opengl.html">3D with OpenGL</a> and  
+<a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> documents.</p>
 
 
 <h2 id="options">Consider your Options</h2>
diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd
index 9f88954..cc467f2 100644
--- a/docs/html/guide/topics/graphics/opengl.jd
+++ b/docs/html/guide/topics/graphics/opengl.jd
@@ -3,51 +3,215 @@ parent.title=Graphics
 parent.link=index.html
 @jd:body
 
+<div id="qv-wrapper">
+  <div id="qv">
+    <h2>In this document</h2>
+    
+    <ol>
+      <li><a href="#basics">The Basics</a></li>
+      <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a>
+        <ol>
+          <li><a href="#textures">Texture Compression Support</a></li>
+          <li><a href="#declare-compression">Declaring Use of Compressed Textures</a></li>
+        </ol>
+      </li>
+    </ol>
+    <h2>Key classes</h2>
+    <ol>
+      <li>{@link android.opengl.GLSurfaceView}</li>
+      <li>{@link android.opengl.GLSurfaceView.Renderer}</li>
+      <li>{@link javax.microedition.khronos.opengles}</li>
+      <li>{@link android.opengl}</li>
+    </ol>
+    <h2>Related Samples</h2>
+    <ol>
+      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
+GLSurfaceViewActivity.html">GLSurfaceViewActivity</a></li>
+      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
+GLES20Activity.html">GLES20Activity</a></li>
+      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
+TouchRotateActivity.html">TouchRotateActivity</a></li>
+      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
+CompressedTextureActivity.html">Compressed Textures</a></li>
+    </ol>
+    <h2>See also</h2>
+    <ol>
+      <li><a href="{@docRoot}resources/articles/glsurfaceview.html">Introducing
+GLSurfaceView</a></li>
+      <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li>
+      <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li>
+      <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li>
+    </ol>
+  </div>
+</div>
 
-<p>Android includes support for high performance 3D graphics 
-via the OpenGL API&mdash;specifically, the OpenGL ES API.</p>
+<p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library
+(OpenGL) API&mdash;specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that
+specifies a standard software interface for 3D graphics processing hardware. OpenGL ES is a flavor
+of the OpenGL specification intended for embedded devices. The OpenGL ES 1.0 and 1.1 API
+specifications have been supported since Android 1.0. Beginning with Android 2.2 (API
+Level 8), the framework supports the OpenGL ES 2.0 API specification.</p>
 
-<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded devices. Versions of <a
-href="http://www.khronos.org/opengles/">OpenGL ES</a> are loosely peered to versions of the primary
-OpenGL standard. Beginning with Android 2.2, the platform supports OpenGL ES 2.0 (with
-backward compatibility support for OpenGL ES 1.1). For information about the relative number of
-Android-powered devices that support a given version of OpenGL ES, see the <a
-href="http://developer.android.com/resources/dashboard/opengl.html">OpenGL ES Versions</a>
-dashboard.</p>
+<p class="note"><b>Note:</b> The specific API provided by the Android framework is similar to the
+  J2ME JSR239 OpenGL ES  API, but is not identical. If you are familiar with J2ME JSR239
+  specification, be alert for variations.</p>
 
-<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL
-ES API. However, it may not be identical, so watch out for deviations.</p>
 
-<h2>Using the API</h2>
+<h2 id="basics">The Basics</h2>
 
-<p>Here's how to use the API at an extremely high level:</p>
+<p>Android supports OpenGL both through its framework API and the Native Development
+Kit (NDK). This topic focuses on the Android framework interfaces. For more information about the
+NDK, see the <a href="{@docRoot}sdk/ndk/index.html">Android NDK</a>.
 
-<ol>
-<li>Write a custom {@link android.view.View} subclass.</li>
-<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li>
-<li>In your View's {@link android.view.View#onDraw onDraw()} method, get a handle to a GL object,
-and use its methods to perform GL operations.</li>
-</ol>
+<p>
+  There are two foundational classes in the Android framework that let you create and manipulate
+graphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link
+android.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application,
+understanding how to implement these classes in an activity should be your first objective.
+</p>
+
+<dl>
+  <dt>{@link android.opengl.GLSurfaceView}</dt>
+  <dd>This class is a container on which you can draw and manipulate objects using OpenGL API calls.
+    This class is similar in function to a {@link android.view.SurfaceView}, except that it is
+    specifically for use with OpenGL. You can use this class by simply creating an instance of 
+    {@link android.opengl.GLSurfaceView} and adding your 
+    {@link android.opengl.GLSurfaceView.Renderer Renderer} to it. However, if you want to capture
+    touch screen events, you should extend the {@link android.opengl.GLSurfaceView} class to
+    implement the touch listeners, as shown in the <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/TouchRotateActivity
+.html">TouchRotateActivity</a> sample.</dd>
+  
+  <dt>{@link android.opengl.GLSurfaceView.Renderer}</dt>
+  <dd>This interface defines the methods required for drawing graphics in an OpenGL {@link
+    android.opengl.GLSurfaceView}. You must provide an implementation of this interface as a
+    separate class and attach it to your {@link android.opengl.GLSurfaceView} instance using
+    {@link android.opengl.GLSurfaceView#setRenderer(android.opengl.GLSurfaceView.Renderer)
+    GLSurfaceView.setRenderer()}.
+    
+    <p>The {@link android.opengl.GLSurfaceView.Renderer} interface requires that you implement the
+      following methods:</p>
+    <ul>
+      <li>
+        {@link
+    android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10,
+    javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()}: The system calls this
+    method once, when creating the {@link android.opengl.GLSurfaceView}. Use this method to perform
+    actions that need to happen only once, such as setting OpenGL environment parameters or
+    initializing OpenGL graphic objects.
+      </li>
+      <li>
+        {@link
+        android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)
+        onDrawFrame()}: The system calls this method on each redraw of the {@link
+        android.opengl.GLSurfaceView}. Use this method as the primary execution point for
+        drawing (and re-drawing) graphic objects.</li>
+      <li>
+        {@link
+    android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10,
+    int, int) onSurfaceChanged()}: The system calls this method when the {@link
+    android.opengl.GLSurfaceView} geometry changes, including changes in size of the {@link
+    android.opengl.GLSurfaceView} or orientation of the device screen. For example, the system calls
+    this method when the device changes from portrait to landscape orientation. Use this method to
+    respond to changes in the {@link android.opengl.GLSurfaceView} container. 
+      </li>
+    </ul>
+    </dd>
+</dl>
+
+<p>Once you have established a container view for OpenGL using {@link
+android.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer}, you can begin
+calling OpenGL APIs using the following classes:</p>
+
+<ul>
+  <li>OpenGL ES 1.0/1.1 API Packages
+    <ul>
+      <li>{@link javax.microedition.khronos.opengles} - This package provides the standard
+implementation of OpenGL ES 1.0 and 1.1.
+          <ul>
+            <li>{@link javax.microedition.khronos.opengles.GL10}</li>
+            <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li>
+            <li>{@link javax.microedition.khronos.opengles.GL11}</li>
+            <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li>
+            <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li>
+          </ul>
+        </li>
+        <li>{@link android.opengl} - This package provides a static interface to the OpenGL classes
+          above. These interfaces were added with Android 1.6 (API Level 4).
+          <ul>
+            <li>{@link android.opengl.GLES10}</li>
+            <li>{@link android.opengl.GLES10Ext}</li>
+            <li>{@link android.opengl.GLES11}</li>
+            <li>{@link android.opengl.GLES10Ext}</li>
+          </ul>
+        </li>
+      </ul>
+  </li>
+  <li>OpenGL ES 2.0 API Class
+    <ul>
+      <li>{@link android.opengl.GLES20 android.opengl.GLES20}</li>
+    </ul>
+  </li>
+</ul>
 
-<p>Several samples using OpenGL ES are available in the <a
-href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/index.html">API
-Demos</a> sample application.
+<h2 id="compatibility">OpenGL Versions and Device Compatibility</h2>
+
+<p>
+  The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0.
+Beginning with Android 2.2 (API Level 8), the framework supports the OpenGL ES 2.0 API
+specification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new
+applications being developed with OpenGL. For information about the relative number of
+Android-powered devices that support a given version of OpenGL ES, see the <a
+href="{@docRoot}resources/dashboard/opengl.html">OpenGL ES Versions Dashboard</a>.</p>
+
+<h3 id="textures">Texture compression support</h3>
+<p>Texture compression can significantly increase the performance of your OpenGL application by
+reducing memory requirements and making more efficient use of memory bandwidth. The Android
+framework provides support for the ETC1 compression format as a standard feature, including a {@link
+android.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in your
+Android SDK at {@code &lt;sdk&gt;/tools/}).</p>
+
+<p>For an example of an Android application that uses texture compression, see the <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
+CompressedTextureActivity.html">CompressedTextureActivity</a> code sample.
 </p>
 
-<p>A summary of how to actually write 3D applications using OpenGL is
-beyond the scope of this text and is left as an exercise for the reader.</p>
+<p>To check if the ETC1 format is supported on a device, call the {@link
+android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p>
 
-<h2>Links to Additional Information</h2>
+<p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an
+alpha channel. If your application requires textures with an alpha channel, you should
+investigate other texture compression formats available on your target devices.</p>
 
-<p>Information about OpenGL ES can be
-found at <a title="http://www.khronos.org/opengles/"
-href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> 
+<p>Beyond the ETC1 format, Android devices have varied support for texture compression based on
+their GPU chipsets. You should investigate texture compression support on the the devices you are
+are targeting to determine what compression types your application should support.</p>
 
-<p>Information specifically
-about OpenGL ES 1.0 (including a detailed specification) can be found
-at <a title="http://www.khronos.org/opengles/1_X/"
-href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p>
+<p>To determine if texture compression formats other than ETC1 are supported on a particular
+device:</p>
+<ol>
+  <li>Run the following code on your target devices to determine what texture compression
+formats are supported:
+<pre>
+  String extensions = javax.microedition.khronos.opengles.GL10.glGetString(GL10.GL_EXTENSIONS);
+</pre>
+  <p class="warning"><b>Warning:</b> The results of this call vary by device! You must run this
+call on several target devices to determine what compression types are commonly supported on
+your target devices.</p>
+  </li>
+  <li>Review the output of this method to determine what extensions are supported on the
+device.</li> 
+</ol>
 
-<p>The documentation for the Android OpenGL ES implementations are available in {@link
-android.opengl} and {@link javax.microedition.khronos.opengles}.</p>
 
+<h3 id="declare-compression">Declaring compressed textures</h3>
+<p>Once you have decided which texture compression types your application will support, you
+must declare them in your manifest file using <a
+href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">
+&lt;supports-gl-texture&gt;</a>. Declaring this information in your manifest file hides your
+application from users with devices that do not support at least one of your declared
+compression types. For more information on how Android Market filtering works for texture
+compressions, see the <a
+href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering">
+Android Market and texture compression filtering</a> section of the {@code
+&lt;supports-gl-texture&gt;} documentation.