Merge "cherrypick from master: Change-Id:... (0fbe1dfb) · Commits · e / os / android_frameworks_base

docs/html/guide/topics/graphics/index.jd

+16 −9

Original line number	Diff line number	Diff line
		@@ -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>

docs/html/guide/topics/graphics/opengl.jd

+198 −34

Original line number	Diff line number	Diff line
		@@ -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>

		<p>Android includes support for high performance 3D graphics
		via the OpenGL API—specifically, the OpenGL ES API.</p>
		<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>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>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.</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>
		<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>

		<h2>Using the API</h2>

		<p>Here's how to use the API at an extremely high level:</p>
		<h2 id="basics">The Basics</h2>

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

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

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

		<h2>Links to Additional Information</h2>
		<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>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>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>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>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>

		<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 <sdk>/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>

		<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">
		<supports-gl-texture></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
		<supports-gl-texture>} documentation.