opengl.jd revision 0664a8f661e15991e20cab1c0daa41f5e21977ab
19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpage.title=3D with OpenGL
2c918e4a86d42d89cb893b0150358cfd01ef7d532Scott Mainparent.title=Graphics
39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectparent.link=index.html
49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project@jd:body
59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
6a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<div id="qv-wrapper">
7a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  <div id="qv">
8a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <h2>In this document</h2>
9a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    
10a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ol>
110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="#basics">The Basics</a>
120664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        <ol>
130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez           <li><a href="#packages">OpenGL packages</a></li>
140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        </ol>
150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="#manifest">Declaring OpenGL Requirements</a></li>
160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      </li>
170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="#coordinate-mapping">Coordinate Mapping for Drawn Objects</a>  
180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        <ol>
190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          <li><a href="#proj-es1">Projection and camera in ES 1.0</a></li>
200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          <li><a href="#proj-es1">Projection and camera in ES 2.0</a></li>
210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        </ol>
220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      </li>
23a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a>
24a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        <ol>
250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          <li><a href="#textures">Texture compression support</a></li>
260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          <li><a href="#gl-extension-query">Determining OpenGL Extensions</a></li>
27a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        </ol>
28a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      </li>
290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="#choosing-version">Choosing an OpenGL API Version</a></li>
30a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ol>
31a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <h2>Key classes</h2>
32a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ol>
33a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>{@link android.opengl.GLSurfaceView}</li>
34a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>{@link android.opengl.GLSurfaceView.Renderer}</li>
35a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ol>
360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <h2>Related tutorials</h2>
370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <ol>
380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="{@docRoot}resources/tutorials/opengl/opengl-es10.html">OpenGL ES 1.0</a></li>
390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li><a href="{@docRoot}resources/tutorials/opengl/opengl-es20.html">OpenGL ES 2.0</a></li>
400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    </ol>
410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <h2>Related samples</h2>
42a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ol>
43a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
44a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezGLSurfaceViewActivity.html">GLSurfaceViewActivity</a></li>
45a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
46a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezGLES20Activity.html">GLES20Activity</a></li>
47a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
48a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezTouchRotateActivity.html">TouchRotateActivity</a></li>
49a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
50a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezCompressedTextureActivity.html">Compressed Textures</a></li>
51a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ol>
52a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <h2>See also</h2>
53a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ol>
54a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="{@docRoot}resources/articles/glsurfaceview.html">Introducing
55a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezGLSurfaceView</a></li>
56a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li>
57a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li>
58a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li>
59a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ol>
60a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  </div>
61a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</div>
629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
63a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library
640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez(OpenGL), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that specifies a
650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezstandard software interface for 3D graphics processing hardware. OpenGL ES is a flavor of the OpenGL
660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezspecification intended for embedded devices. The OpenGL ES 1.0 and 1.1 API specifications have been
670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported since Android 1.0. Beginning with Android 2.2 (API Level 8), the framework supports the
680664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezOpenGL ES 2.0 API specification.</p>
699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
70a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p class="note"><b>Note:</b> The specific API provided by the Android framework is similar to the
71a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  J2ME JSR239 OpenGL ES  API, but is not identical. If you are familiar with J2ME JSR239
72a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  specification, be alert for variations.</p>
739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
75a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="basics">The Basics</h2>
769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
77a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android supports OpenGL both through its framework API and the Native Development
78a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezKit (NDK). This topic focuses on the Android framework interfaces. For more information about the
79a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezNDK, see the <a href="{@docRoot}sdk/ndk/index.html">Android NDK</a>.
809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
81a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>
82a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  There are two foundational classes in the Android framework that let you create and manipulate
83a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezgraphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link
84a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application,
85a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezunderstanding how to implement these classes in an activity should be your first objective.
86a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</p>
87a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez
88a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<dl>
890664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <dt><strong>{@link android.opengl.GLSurfaceView}</strong></dt>
900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <dd>This class is a {@link android.view.View} where you can draw and manipulate objects using
910664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    OpenGL API calls and is similar in function to a {@link android.view.SurfaceView}. You can use
920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    this class by creating an instance of {@link android.opengl.GLSurfaceView} and adding your 
93a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    {@link android.opengl.GLSurfaceView.Renderer Renderer} to it. However, if you want to capture
94a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    touch screen events, you should extend the {@link android.opengl.GLSurfaceView} class to
950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    implement the touch listeners, as shown in OpenGL Tutorials for 
960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <a href="{@docRoot}resources/tutorials/opengl/opengl-es10.html#touch">ES 1.0</a>, 
970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <a href="{@docRoot}resources/tutorials/opengl/opengl-es20.html#touch">ES 2.0</a> and the <a
98a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/TouchRotateActivity
99a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez.html">TouchRotateActivity</a> sample.</dd>
100a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  
1010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <dt><strong>{@link android.opengl.GLSurfaceView.Renderer}</strong></dt>
102a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  <dd>This interface defines the methods required for drawing graphics in an OpenGL {@link
103a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    android.opengl.GLSurfaceView}. You must provide an implementation of this interface as a
104a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    separate class and attach it to your {@link android.opengl.GLSurfaceView} instance using
105a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    {@link android.opengl.GLSurfaceView#setRenderer(android.opengl.GLSurfaceView.Renderer)
106a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    GLSurfaceView.setRenderer()}.
107a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    
108a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <p>The {@link android.opengl.GLSurfaceView.Renderer} interface requires that you implement the
109a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      following methods:</p>
110a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ul>
111a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>
112a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        {@link
113a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10,
114a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()}: The system calls this
115a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    method once, when creating the {@link android.opengl.GLSurfaceView}. Use this method to perform
116a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    actions that need to happen only once, such as setting OpenGL environment parameters or
117a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    initializing OpenGL graphic objects.
118a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      </li>
119a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>
120a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        {@link
121a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)
122a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        onDrawFrame()}: The system calls this method on each redraw of the {@link
123a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        android.opengl.GLSurfaceView}. Use this method as the primary execution point for
124a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        drawing (and re-drawing) graphic objects.</li>
125a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>
126a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        {@link
127a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10,
128a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    int, int) onSurfaceChanged()}: The system calls this method when the {@link
129a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    android.opengl.GLSurfaceView} geometry changes, including changes in size of the {@link
130a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    android.opengl.GLSurfaceView} or orientation of the device screen. For example, the system calls
131a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    this method when the device changes from portrait to landscape orientation. Use this method to
132a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    respond to changes in the {@link android.opengl.GLSurfaceView} container. 
133a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      </li>
134a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ul>
135a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </dd>
136a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</dl>
137a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez
1380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="packages">OpenGL packages</h3>
139a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Once you have established a container view for OpenGL using {@link
140a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer}, you can begin
141a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezcalling OpenGL APIs using the following classes:</p>
142a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez
143a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<ul>
144a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  <li>OpenGL ES 1.0/1.1 API Packages
145a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ul>
1460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES
1470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez1.0/1.1 classes and better performance than the javax.microedition.khronos package interfaces.
1480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          <ul>
1490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez            <li>{@link android.opengl.GLES10}</li>
1500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez            <li>{@link android.opengl.GLES10Ext}</li>
1510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez            <li>{@link android.opengl.GLES11}</li>
1520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez            <li>{@link android.opengl.GLES10Ext}</li>
1530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez          </ul>
1540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        </li>
155a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      <li>{@link javax.microedition.khronos.opengles} - This package provides the standard
1560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezimplementation of OpenGL ES 1.0/1.1.
157a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez          <ul>
158a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez            <li>{@link javax.microedition.khronos.opengles.GL10}</li>
159a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez            <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li>
160a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez            <li>{@link javax.microedition.khronos.opengles.GL11}</li>
161a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez            <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li>
162a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez            <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li>
163a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez          </ul>
164a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez        </li>
165a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez      </ul>
166a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  </li>
167a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  <li>OpenGL ES 2.0 API Class
168a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    <ul>
1690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@link android.opengl.GLES20 android.opengl.GLES20} - This package provides the
1700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinterface to OpenGL ES 2.0 and is available starting with Android 2.2 (API Level 8).</li>
171a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez    </ul>
172a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  </li>
173a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ul>
1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
1750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>If you'd like to start building an app with OpenGL right away, have a look at the tutorials for
1760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<a href="{@docRoot}resources/tutorials/opengl/opengl-es10.html">OpenGL ES 1.0</a> or 
1770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<a href="{@docRoot}resources/tutorials/opengl/opengl-es20.html">OpenGL ES 2.0</a>!
1780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p>
1790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
1800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="manifest">Declaring OpenGL Requirements</h2>
1810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>If your application uses OpenGL features that are not available on all devices, you must include
1820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthese requirements in your <a 
1830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a></code> file.
1840664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezHere are the most common OpenGL manifest declarations:</p>
1850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
1860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul>
1870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>OpenGL ES version requirements</strong> - If your application only supports OpenGL ES
1880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez2.0, you must declare that requirement by adding the following settings to your manifest as
1890664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezshown below.
1900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
1910664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
1920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    &lt;!-- Tell the system this app requires OpenGL ES 2.0. --&gt;
1930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    &lt;uses-feature android:glEsVersion="0x00020000" android:required="true" /&gt;
1940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
1950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
1960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <p>Adding this declaration causes the Android Market to restrict your application from being
1970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  installed on devices that do not support OpenGL ES 2.0.</p>
1980664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  </li>
1990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>Texture compression requirements</strong> - If your application uses texture
2000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcompression formats that are not supported by all devices, you must declare them in your manifest
2010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezfile using <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">
2020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez{@code &lt;supports-gl-texture&gt;}</a>. For more information about available texture compression
2030664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezformats, see <a href="#textures">Texture compression support</a>. 
2040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Declaring texture compression requirements in your manifest hides your application from users
2060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwith devices that do not support at least one of your declared compression types. For more
2070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinformation on how Android Market filtering works for texture compressions, see the <a
2080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering">
2090664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid Market and texture compression filtering</a> section of the {@code
2100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez&lt;supports-gl-texture&gt;} documentation.</p> 
2110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  </li>
2120664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul>
2130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="coordinate-mapping">Coordinate Mapping for Drawn Objects</h2>
2160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>One of the basic problems in displaying graphics on Android devices is that their screens can
2180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvary in size and shape. OpenGL assumes a square, uniform coordinate system and, by default, happily
2190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdraws those coordinates onto your typically non-square screen as if it is perfectly square.</p>
2200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<img src="{@docRoot}images/opengl/coordinates.png">
2220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="img-caption">
2230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <strong>Figure 1.</strong> Default OpenGL coordinate system (left) mapped to a typical Android
2240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen (right).
2250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p>
2260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The illustration above shows the uniform coordinate system assumed for an OpenGL frame on the
2280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezleft, and how these coordinates actually map to a typical device screen in landscape orientation
2290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezon the right. To solve this problem, you can apply OpenGL projection modes and camera views to
2300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztransform coordinates so your graphic objects have the correct proportions on any display.</p>
2310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2320664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In order to apply projection and camera views, you create a projection matrix and a camera view
2330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and apply them to the OpenGL rendering pipeline. The projection matrix recalculates the
2340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcoordinates of your graphics so that they map correctly to Android device screens. The camera view
2350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix creates a transformation that renders objects from a specific eye position.</p>
2360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="proj-es1">Projection and camera view in OpenGL ES 1.0</h3>
2380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In the ES 1.0 API, you apply projection and camera view by creating each matrix and then
2390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezadding them to the OpenGL environment.</p>
2400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  
2410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol>
2420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Projection matrix</strong> - Create a projection matrix using the geometry of the
2430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen in order to recalculate object coordinates so they are drawn with correct proportions.
2440664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezThe following example code demonstrates how to modify the {@code onSurfaceChanged()} method of a
2450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez{@link android.opengl.GLSurfaceView.Renderer} implementation to create a projection matrix based on
2460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe screen's aspect ratio and apply it to the OpenGL rendering environment.
2470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
2490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  public void onSurfaceChanged(GL10 gl, int width, int height) {
2500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      gl.glViewport(0, 0, width, height);
2510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      
2520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      // make adjustments for screen ratio
2530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      float ratio = (float) width / height;
2540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      gl.glMatrixMode(GL10.GL_PROJECTION);        // set matrix to projection mode
2550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      gl.glLoadIdentity();                        // reset the matrix to its default state
2560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7);  // apply the projection matrix
2570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  }  
2580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
2590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
2600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Camera transformation matrix</strong> - Once you have adjusted the coordinate system
2620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezusing a projection matrix, you must also apply a camera view. The following example code shows how
2630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezto modify the {@code onDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer}
2640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezimplementation to apply a model view and use the {@link
2650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.GLU#gluLookAt(javax.microedition.khronos.opengles.GL10, float, float, float, float,
2660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezfloat, float, float, float, float) GLU.gluLookAt()} utility to create a viewing tranformation which
2670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsimulates a camera position.
2680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
2700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    public void onDrawFrame(GL10 gl) {
2710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
2720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // Set GL_MODELVIEW transformation mode
2730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        gl.glMatrixMode(GL10.GL_MODELVIEW);
2740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        gl.glLoadIdentity();                      // reset the matrix to its default state
2750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
2760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // When using GL_MODELVIEW, you must set the camera view
2770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f);        
2780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
2790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    }
2800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>   
2810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
2820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol>
2830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>For a complete example of how to apply projection and camera views with OpenGL ES 1.0, see the <a
2850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}resources/tutorials/opengl/opengl-es10.html#projection-and-views">OpenGL ES 1.0
2860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztutorial</a>.</p>
2870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
2890664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0</h3>
2900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In the ES 2.0 API, you apply projection and camera view by first adding a matrix member to
2910664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe vertex shaders of your graphics objects. With this matrix member added, you can then
2920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezgenerate and apply projection and camera viewing matrices to your objects.</p>
2930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  
2940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol>
2950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Add matrix to vertex shaders</strong> - Create a variable for the view projection matrix
2960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezand include it as a multiplier of the shader's position. In the following example vertex shader
2970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcode, the included {@code uMVPMatrix} member allows you to apply projection and camera viewing 
2980664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrices to the coordinates of objects that use this shader.
2990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
3000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
3010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    private final String vertexShaderCode = 
3020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3030664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // This matrix member variable provides a hook to manipulate
3040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // the coordinates of objects that use this vertex shader
3050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        "uniform mat4 uMVPMatrix;   \n" +
3060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        "attribute vec4 vPosition;  \n" +
3080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        "void main(){               \n" +
3090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // the matrix must be included as part of gl_Position
3110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        " gl_Position = uMVPMatrix * vPosition; \n" +
3120664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        "}  \n";
3140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
3150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <p class="note"><strong>Note:</strong> The example above defines a single transformation matrix
3160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmember in the vertex shader into which you apply a combined projection matrix and camera view
3170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix. Depending on your application requirements, you may want to define separate projection
3180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and camera viewing matrix members in your vertex shaders so you can change them
3190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezindependently.</p>
3200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
3210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Access the shader matrix</strong> - After creating a hook in your vertex shaders to
3220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapply projection and camera view, you can then access that variable to apply projection and
3230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcamera viewing matrices. The following code shows how to modify the {@code onSurfaceCreated()}
3240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmethod of a {@link android.opengl.GLSurfaceView.Renderer} implementation to access the matrix
3250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariable defined in the vertex shader above.
3260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
3270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
3280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    public void onSurfaceCreated(GL10 unused, EGLConfig config) {
3290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
3300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix");
3310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
3320664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    }
3330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
3340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
3350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Create projection and camera viewing matrices</strong> - Generate the projection and
3360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezviewing matrices to be applied the graphic objects. The following example code shows how to modify
3370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe {@code onSurfaceCreated()} and {@code onSurfaceChanged()} methods of a {@link
3380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.GLSurfaceView.Renderer} implementation to create camera view matrix and a projection
3390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix based on the screen aspect ratio of the device.
3400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
3410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
3420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    public void onSurfaceCreated(GL10 unused, EGLConfig config) {
3430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
3440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // Create a camera view matrix
3450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f);
3460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    }    
3470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    
3480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    public void onSurfaceChanged(GL10 unused, int width, int height) {
3490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        GLES20.glViewport(0, 0, width, height);
3500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        float ratio = (float) width / height;
3520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // create a projection matrix from device screen geometry
3540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7);
3550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    }  
3560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
3570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
3580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
3590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Apply projection and camera viewing matrices</strong> - To apply the projection and
3600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcamera view transformations, multiply the matrices together and then set them into the vertex
3610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezshader. The following example code shows how modify the {@code onDrawFrame()} method of a {@link
3620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.GLSurfaceView.Renderer} implementation to combine the projection matrix and camera
3630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezview created in the code above and then apply it to the graphic objects to be rendered by OpenGL.
3640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  
3650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre>
3660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    public void onDrawFrame(GL10 unused) {
3670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
3680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // Combine the projection and camera view matrices
3690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0);
3700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // Apply the combined projection and camera view transformations
3720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0);
3730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        
3740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        // Draw objects
3750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez        ...
3760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    }
3770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre>
3780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li>
3790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol>
3800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>For a complete example of how to apply projection and camera view with OpenGL ES 2.0, see the <a
3810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}resources/tutorials/opengl/opengl-es20.html#projection-and-views">OpenGL ES 2.0
3820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztutorial</a>.</p>
3830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
3840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
385a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="compatibility">OpenGL Versions and Device Compatibility</h2>
386a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez
3870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0.
388a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezBeginning with Android 2.2 (API Level 8), the framework supports the OpenGL ES 2.0 API
389a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezspecification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new
390a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezapplications being developed with OpenGL. For information about the relative number of
391a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezAndroid-powered devices that support a given version of OpenGL ES, see the <a
392a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezhref="{@docRoot}resources/dashboard/opengl.html">OpenGL ES Versions Dashboard</a>.</p>
393a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez
3940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
395a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h3 id="textures">Texture compression support</h3>
396a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Texture compression can significantly increase the performance of your OpenGL application by
397a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezreducing memory requirements and making more efficient use of memory bandwidth. The Android
398a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezframework provides support for the ETC1 compression format as a standard feature, including a {@link
3990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in the
4000664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid SDK at {@code &lt;sdk&gt;/tools/}). For an example of an Android application that uses
4010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztexture compression, see the <a
402a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/
403a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezCompressedTextureActivity.html">CompressedTextureActivity</a> code sample.
4049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p>
4059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
406a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>To check if the ETC1 format is supported on a device, call the {@link
407a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p>
4089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
409a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an
410a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezalpha channel. If your application requires textures with an alpha channel, you should
411a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezinvestigate other texture compression formats available on your target devices.</p>
4129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
413a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Beyond the ETC1 format, Android devices have varied support for texture compression based on
4140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztheir GPU chipsets and OpenGL implementations. You should investigate texture compression support on
4150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe the devices you are are targeting to determine what compression types your application should
4160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupport. In order to determine what texture formats are supported on a given device, you must <a
4170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="#gl-extension-query">query the device</a> and review the <em>OpenGL extension names</em>,
4180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwhich identify what texture compression formats (and other OpenGL features) are supported by the
4190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice. Some commonly supported texture compression formats are as follows:</p>
4209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
4210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul>
4220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>ATITC (ATC)</strong> - ATI texture compression (ATITC or ATC) is available on a
4230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwide variety of devices and supports fixed rate compression for RGB textures with and without
4240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezan alpha channel. This format may be represented by several OpenGL extension names, for example:
4250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <ul>
4260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_AMD_compressed_ATC_texture}</li>
4270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_ATI_texture_compression_atitc}</li>
4280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    </ul>
4290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  </li>
4300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>PVRTC</strong> - PowerVR texture compression (PVRTC) is available on a wide
4310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariety of devices and supports 2-bit and 4-bit per pixel textures with or without an alpha channel.
4320664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezThis format is represented by the following OpenGL extension name:
4330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <ul>
4340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_IMG_texture_compression_pvrtc}</li>
4350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    </ul>
4360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  </li>
4370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>S3TC (DXT<em>n</em>/DXTC)</strong> - S3 texture compression (S3TC) has several
4380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezformat variations (DXT1 to DXT5) and is less widely available. The format supports RGB textures with
4390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez4-bit alpha or 8-bit alpha channels. This format may be represented by several OpenGL extension
4400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeznames, for example:
4410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <ul>
4420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_OES_texture_compression_S3TC}</li>
4430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_EXT_texture_compression_s3tc}</li>
4440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_EXT_texture_compression_dxt1}</li>
4450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_EXT_texture_compression_dxt3}</li>
4460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_EXT_texture_compression_dxt5}</li>
4470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    </ul>
4480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  </li>
4490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>3DC</strong> - 3DC texture compression (3DC) is a less widely available format that
4500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupports RGB textures with an an alpha channel. This format is represented by the following OpenGL
4510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezextension name:</li>
4520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    <ul>
4530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez      <li>{@code GL_AMD_compressed_3DC_texture}</li>
4540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez    </ul>
4550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul>
4560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
4570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="warning"><strong>Warning:</strong> These texture compression formats are <em>not
4580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported</em> on all devices. Support for these formats can vary by manufacturer and device. For
4590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinformation on how to determine what texture compression formats are on a particular device, see
4600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe next section.
4610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p>
4620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
4630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="note"><strong>Note:</strong> Once you decide which texture compression formats your
4640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapplication will support, make sure you declare them in your manifest using <a
4650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;
4660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</a>. Using this declaration enables filtering by external services such as Android Market, so that
4670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezyour app is installed only on devices that support the formats your app requires. For details, see
4680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<a
4690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p>
4700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
4710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="gl-extension-query">Determining OpenGL extensions</h3>
4720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Implementations of OpenGL vary by Android device in terms of the extensions to the OpenGL ES API
4730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthat are supported. These extensions include texture compressions, but typically also include other
4740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezextensions to the OpenGL feature set.</p>
4750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
4760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>To determine what texture compression formats, and other OpenGL extensions, are supported on a
4770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezparticular device:</p>
478a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<ol>
479a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  <li>Run the following code on your target devices to determine what texture compression
480a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezformats are supported:
481a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<pre>
482a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  String extensions = javax.microedition.khronos.opengles.GL10.glGetString(GL10.GL_EXTENSIONS);
483a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</pre>
4840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <p class="warning"><b>Warning:</b> The results of this call <em>vary by device!</em> You
4850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmust run this call on several target devices to determine what compression types are commonly
4860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported.</p>
487a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez  </li>
4880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li>Review the output of this method to determine what OpenGL extensions are supported on the
489a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezdevice.</li> 
490a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ol>
4919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
4929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project
4930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="choosing-version">Choosing an OpenGL API Version</h2>
4940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
4950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>OpenGL ES API version 1.0 (and the 1.1 extensions) and version 2.0 both provide high
4960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezperformance graphics interfaces for creating 3D games, visualizations and user interfaces. Graphics
4970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezprogramming for the OpenGL ES 1.0/1.1 API versus ES 2.0 differs significantly, and so developers
4980664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezshould carefully consider the following factors before starting development with either API:</p>
4990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez
5000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul>
5010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>Performance</strong> - In general, OpenGL ES 2.0 provides faster graphics performance
5020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthan the ES 1.0/1.1 APIs. However, the performance difference can vary depending on the Android
5030664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice your OpenGL application is running on, due to differences in the implementation of the OpenGL
5040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezgraphics pipeline.</li>
5050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>Device Compatibility</strong> - Developers should consider the types of devices, 
5060664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid versions and the OpenGL ES versions available to their customers. For more information
5070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezon OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and Device
5080664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezCompatibility</a> section.</li>
5090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>Coding Convenience</strong> - The OpenGL ES 1.0/1.1 API provides a fixed function
5100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezpipeline and convenience functions which are not available in the ES 2.0 API. Developers who are new
5110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezto OpenGL may find coding for OpenGL ES 1.0/1.1 faster and more convenient.</li>
5120664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 API provides a higher degree
5130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezof control by providing a fully programmable pipeline through the use of shaders. With more
5140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdirect control of the graphics processing pipeline, developers can create effects that would be
5150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvery difficult to generate using the 1.0/1.1 API.</li>
5160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul>
5170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez  
5180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>While performance, compatibility, convenience, control and other factors may influence your
5190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdecision, you should pick an OpenGL API version based on what you think provides the best experience
5200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezfor your users.</p>
521