From dbad9d4e98bcaf47c54a8cc4860338fb25e8a96e Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 22 Jun 2011 09:48:59 -0700 Subject: cherrypick from master: Change-Id: I169749dc594ca1d79a802db4c53ec330924fdd2c Change-Id: I6401f568ec132d959d57f32caa8b45b2613229e6 --- docs/html/guide/topics/graphics/index.jd | 25 ++-- docs/html/guide/topics/graphics/opengl.jd | 232 +++++++++++++++++++++++++----- 2 files changed, 214 insertions(+), 43 deletions(-) (limited to 'docs') 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 +

See also

+
    +
  1. 3D with OpenGL
    2. +
  2. RenderScript
    3. +
-

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}.

+ +

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.

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.

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 Draw with a -Canvas (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 3D with OpenGL and refer to other OpenGL documentation.

+Canvas (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 3D with OpenGL and +RenderScript documents.

Consider your Options

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

In this document

+ +
    +
  1. The Basics
    2. +
  2. OpenGL Versions and Device Compatibility +
      +
    1. Texture Compression Support
      2. +
    2. Declaring Use of Compressed Textures
      3. +
    +
    3. +
+

Key classes

+
    +
  1. {@link android.opengl.GLSurfaceView}
    2. +
  2. {@link android.opengl.GLSurfaceView.Renderer}
    3. +
  3. {@link javax.microedition.khronos.opengles}
    4. +
  4. {@link android.opengl}
    5. +
+

Related Samples

+
    +
  1. GLSurfaceViewActivity
    2. +
  2. GLES20Activity
    3. +
  3. TouchRotateActivity
    4. +
  4. Compressed Textures
    5. +
+

See also

+
    +
  1. Introducing +GLSurfaceView
    2. +
  2. OpenGL ES
    3. +
  3. OpenGL ES 1.x Specification
    4. +
  4. OpenGL ES 2.x specification
    5. +
+
+
-

Android includes support for high performance 3D graphics -via the OpenGL API—specifically, the OpenGL ES API.

+

Android includes support for high performance 2D and 3D graphics with the Open Graphics Library +(OpenGL) API—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.

-

OpenGL ES is a flavor of the OpenGL specification intended for embedded devices. Versions of OpenGL ES 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 OpenGL ES Versions -dashboard.

+

Note: 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.

-

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.

-

Using the API

+

The Basics

-

Here's how to use the API at an extremely high level:

+

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 Android NDK. -

    -
  1. Write a custom {@link android.view.View} subclass.
    2. -
  2. Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.
    3. -
  3. 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.
    4. -
+

+ 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. +

+ +
+
{@link android.opengl.GLSurfaceView}
+
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 TouchRotateActivity sample.
+ +
{@link android.opengl.GLSurfaceView.Renderer}
+
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()}. + +

The {@link android.opengl.GLSurfaceView.Renderer} interface requires that you implement the + following methods:

+
    +
  • + {@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. +
    • +
  • + {@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.
    • +
  • + {@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. +
    • +
+
+
+ +

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:

+ + -

Several samples using OpenGL ES are available in the API -Demos sample application. +

OpenGL Versions and Device Compatibility

+ +

+ 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 OpenGL ES Versions Dashboard.

+ +

Texture compression support

+

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 <sdk>/tools/}).

+ +

For an example of an Android application that uses texture compression, see the CompressedTextureActivity code sample.

-

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.

+

To check if the ETC1 format is supported on a device, call the {@link +android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.

-

Links to Additional Information

+

Note: 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.

-

Information about OpenGL ES can be -found at http://www.khronos.org/opengles/.

+

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.

-

Information specifically -about OpenGL ES 1.0 (including a detailed specification) can be found -at http://www.khronos.org/opengles/1_X/.

+

To determine if texture compression formats other than ETC1 are supported on a particular +device:

+
    +
  1. Run the following code on your target devices to determine what texture compression +formats are supported: +
    +  String extensions = javax.microedition.khronos.opengles.GL10.glGetString(GL10.GL_EXTENSIONS);
+
    +

    Warning: 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.

    +
    2. +
  2. Review the output of this method to determine what extensions are supported on the +device.
    3. +
-

The documentation for the Android OpenGL ES implementations are available in {@link -android.opengl} and {@link javax.microedition.khronos.opengles}.

+

Declaring compressed textures

+

Once you have decided which texture compression types your application will support, you +must declare them in your manifest file using +<supports-gl-texture>. 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 +Android Market and texture compression filtering section of the {@code +<supports-gl-texture>} documentation. -- cgit v1.1