Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "cherrypick from master: Change-Id: I169749dc594ca1d79a802db4c53ec330924fdd2c" into honeycomb-mr2

Browse Source
This commit is contained in:
Joe Fernandez
2011-07-07 15:03:55 -07:00
committed by Android (Google) Code Review
parent 40afb97c32 dbad9d4e98
commit 0fbe1dfb8d
2 changed files with 215 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/html/guide/topics/graphics/index.jd
View File

@@ -14,13 +14,20 @@ page.title=Graphics
</ol> </ol>
</li> </li>
</ol> </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>
</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 <p>Android graphics are powered by a custom 2D graphics library, and the framework provides
{@link android.graphics.drawable drawable package}. OpenGL APIs are available support for high performance 3D graphics in the form of OpenGL ES and RenderScript. The most
from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES package}, common 2D graphics APIs can be found in the {@link android.graphics.drawable drawable package}.
plus some Android {@link android.opengl OpenGL utilities}.</p> 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. <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 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 <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 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), Canvas</a> (and the section on SurfaceView), will give you a quick idea of how you should draw to
will give you a quick idea of how you should draw to the View hierarchy. For more information the View hierarchy. For more information on Android's 3D graphics APIs, see
on Android's 3D graphic utilities (provided by the OpenGL ES API), the <a href="opengl.html">3D with OpenGL</a> and
read <a href="opengl.html">3D with OpenGL</a> and refer to other OpenGL documentation.</p> <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> documents.</p>
<h2 id="options">Consider your Options</h2> <h2 id="options">Consider your Options</h2>

234
docs/html/guide/topics/graphics/opengl.jd
View File

@@ -3,51 +3,215 @@ parent.title=Graphics
parent.link=index.html parent.link=index.html
@jd:body @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 <p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library
via the OpenGL API&mdash;specifically, the OpenGL ES API.</p> (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 <p class="note"><b>Note:</b> The specific API provided by the Android framework is similar to the
href="http://www.khronos.org/opengles/">OpenGL ES</a> are loosely peered to versions of the primary J2ME JSR239 OpenGL ES API, but is not identical. If you are familiar with J2ME JSR239
OpenGL standard. Beginning with Android 2.2, the platform supports OpenGL ES 2.0 (with specification, be alert for variations.</p>
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>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> <p>
<li>Write a custom {@link android.view.View} subclass.</li> There are two foundational classes in the Android framework that let you create and manipulate
<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li> graphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link
<li>In your View's {@link android.view.View#onDraw onDraw()} method, get a handle to a GL object, android.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application,
and use its methods to perform GL operations.</li> understanding how to implement these classes in an activity should be your first objective.
</ol>
<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.
</p> </p>
<p>A summary of how to actually write 3D applications using OpenGL is <dl>
beyond the scope of this text and is left as an exercise for the reader.</p> <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>
<h2>Links to Additional Information</h2> <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>
<p>Information about OpenGL ES can be <ul>
found at <a title="http://www.khronos.org/opengles/" <li>OpenGL ES 1.0/1.1 API Packages
href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> <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>Information specifically <h2 id="compatibility">OpenGL Versions and Device Compatibility</h2>
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>The documentation for the Android OpenGL ES implementations are available in {@link <p>
android.opengl} and {@link javax.microedition.khronos.opengles}.</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>To check if the ETC1 format is supported on a device, call the {@link
android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p>
<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>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>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>
<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.