1d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lypage.title=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> 9d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 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> 17d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly <li><a href="#coordinate-mapping">Mapping Coordinates 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> 2350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="#faces-winding">Shape Faces and Winding</li> 24a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a> 25a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#textures">Texture compression support</a></li> 270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#gl-extension-query">Determining OpenGL Extensions</a></li> 28a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 29a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#choosing-version">Choosing an OpenGL API Version</a></li> 31a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 32a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <h2>Key classes</h2> 33a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 34a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link android.opengl.GLSurfaceView}</li> 35a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link android.opengl.GLSurfaceView.Renderer}</li> 36a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <h2>Related samples</h2> 38a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 3919aad293c0dba4ed9a47939c487fecdd5318ef08Scott Main <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">GLSurfaceViewActivity</a></li> 4019aad293c0dba4ed9a47939c487fecdd5318ef08Scott Main <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/GLES20Activity.html">GLES20Activity</a></li> 4119aad293c0dba4ed9a47939c487fecdd5318ef08Scott Main <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/TouchRotateActivity.html">TouchRotateActivity</a></li> 4219aad293c0dba4ed9a47939c487fecdd5318ef08Scott Main <li><a 4319aad293c0dba4ed9a47939c487fecdd5318ef08Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/CompressedTextureActivity.html">Compressed Textures</a></li> 44a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 45a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <h2>See also</h2> 46a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 4750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="{@docRoot}training/graphics/opengl/index.html"> 4850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Displaying Graphics with OpenGL ES</a></li> 49a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li> 50a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li> 51a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li> 52a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 53a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </div> 54a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</div> 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 56a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library 570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez(OpenGL), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that specifies a 580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezstandard software interface for 3D graphics processing hardware. OpenGL ES is a flavor of the OpenGL 590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezspecification intended for embedded devices. The OpenGL ES 1.0 and 1.1 API specifications have been 600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported since Android 1.0. Beginning with Android 2.2 (API Level 8), the framework supports the 610664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezOpenGL ES 2.0 API specification.</p> 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 63a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p class="note"><b>Note:</b> The specific API provided by the Android framework is similar to the 64a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez J2ME JSR239 OpenGL ES API, but is not identical. If you are familiar with J2ME JSR239 65a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez specification, be alert for variations.</p> 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 68a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="basics">The Basics</h2> 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 70a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android supports OpenGL both through its framework API and the Native Development 71a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezKit (NDK). This topic focuses on the Android framework interfaces. For more information about the 7250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainNDK, see the <a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK</a>. 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 74d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly<p>There are two foundational classes in the Android framework that let you create and manipulate 75a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezgraphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link 76a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application, 77a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezunderstanding how to implement these classes in an activity should be your first objective. 78a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</p> 79a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 80a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<dl> 810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dt><strong>{@link android.opengl.GLSurfaceView}</strong></dt> 820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dd>This class is a {@link android.view.View} where you can draw and manipulate objects using 830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez OpenGL API calls and is similar in function to a {@link android.view.SurfaceView}. You can use 84d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly this class by creating an instance of {@link android.opengl.GLSurfaceView} and adding your 85a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link android.opengl.GLSurfaceView.Renderer Renderer} to it. However, if you want to capture 86a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez touch screen events, you should extend the {@link android.opengl.GLSurfaceView} class to 87f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main implement the touch listeners, as shown in OpenGL training lesson, 88f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main <a href="{@docRoot}training/graphics/opengl/touch.html">Responding to Touch Events</a>.</dd> 89d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dt><strong>{@link android.opengl.GLSurfaceView.Renderer}</strong></dt> 91a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <dd>This interface defines the methods required for drawing graphics in an OpenGL {@link 92a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView}. You must provide an implementation of this interface as a 93a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez separate class and attach it to your {@link android.opengl.GLSurfaceView} instance using 94a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link android.opengl.GLSurfaceView#setRenderer(android.opengl.GLSurfaceView.Renderer) 95a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez GLSurfaceView.setRenderer()}. 96d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 97a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <p>The {@link android.opengl.GLSurfaceView.Renderer} interface requires that you implement the 98a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez following methods:</p> 99a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ul> 100a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li> 101a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link 102a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10, 103a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()}: The system calls this 104a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez method once, when creating the {@link android.opengl.GLSurfaceView}. Use this method to perform 105a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez actions that need to happen only once, such as setting OpenGL environment parameters or 106a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez initializing OpenGL graphic objects. 107a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 108a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li> 109a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link 110a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10) 111a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez onDrawFrame()}: The system calls this method on each redraw of the {@link 112a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView}. Use this method as the primary execution point for 113a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez drawing (and re-drawing) graphic objects.</li> 114a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li> 115a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link 116a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10, 117a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez int, int) onSurfaceChanged()}: The system calls this method when the {@link 118a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView} geometry changes, including changes in size of the {@link 119a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez android.opengl.GLSurfaceView} or orientation of the device screen. For example, the system calls 120a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez this method when the device changes from portrait to landscape orientation. Use this method to 121d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly respond to changes in the {@link android.opengl.GLSurfaceView} container. 122a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 123a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 124a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </dd> 125a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</dl> 126a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 1270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="packages">OpenGL packages</h3> 128a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Once you have established a container view for OpenGL using {@link 129a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer}, you can begin 130a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezcalling OpenGL APIs using the following classes:</p> 131a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 132a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<ul> 133a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>OpenGL ES 1.0/1.1 API Packages 134a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ul> 1350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES 1360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez1.0/1.1 classes and better performance than the javax.microedition.khronos package interfaces. 1370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 1380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES10}</li> 1390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES10Ext}</li> 1400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES11}</li> 1410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES10Ext}</li> 1420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 1430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 144a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles} - This package provides the standard 1450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezimplementation of OpenGL ES 1.0/1.1. 146a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ul> 147a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL10}</li> 148a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li> 149a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11}</li> 150a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li> 151a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li> 152a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 153a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 154a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 155a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 156a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>OpenGL ES 2.0 API Class 157a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ul> 1580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES20 android.opengl.GLES20} - This package provides the 1590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinterface to OpenGL ES 2.0 and is available starting with Android 2.2 (API Level 8).</li> 160a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 161a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 162a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ul> 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 164f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main<p>If you'd like to start building an app with OpenGL right away, follow the 165f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main<a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> class. 1660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 1670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="manifest">Declaring OpenGL Requirements</h2> 1690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>If your application uses OpenGL features that are not available on all devices, you must include 170d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lythese requirements in your <a 1710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a></code> file. 1720664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezHere are the most common OpenGL manifest declarations:</p> 1730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 1750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>OpenGL ES version requirements</strong> - If your application only supports OpenGL ES 1760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez2.0, you must declare that requirement by adding the following settings to your manifest as 1770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezshown below. 1780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 1800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <!-- Tell the system this app requires OpenGL ES 2.0. --> 1810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <uses-feature android:glEsVersion="0x00020000" android:required="true" /> 1820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 1830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1844d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Dougherty <p>Adding this declaration causes Google Play to restrict your application from being 1850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez installed on devices that do not support OpenGL ES 2.0.</p> 1860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 1870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Texture compression requirements</strong> - If your application uses texture 1888f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezcompression formats, you must declare the formats your application supports in your manifest file 1898f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezusing <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code 1908f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez<supports-gl-texture>}</a>. For more information about available texture compression 191d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lyformats, see <a href="#textures">Texture compression support</a>. 1920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Declaring texture compression requirements in your manifest hides your application from users 1940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwith devices that do not support at least one of your declared compression types. For more 1954d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Doughertyinformation on how Google Play filtering works for texture compressions, see the <a 1960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering"> 1974d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk DoughertyGoogle Play and texture compression filtering</a> section of the {@code 198d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly<supports-gl-texture>} documentation.</p> 1990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 2000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 2010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2038f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez<h2 id="coordinate-mapping">Mapping Coordinates for Drawn Objects</h2> 2040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>One of the basic problems in displaying graphics on Android devices is that their screens can 2060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvary in size and shape. OpenGL assumes a square, uniform coordinate system and, by default, happily 2070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdraws those coordinates onto your typically non-square screen as if it is perfectly square.</p> 2080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<img src="{@docRoot}images/opengl/coordinates.png"> 2100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="img-caption"> 2110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <strong>Figure 1.</strong> Default OpenGL coordinate system (left) mapped to a typical Android 2120664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen (right). 2130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 2140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The illustration above shows the uniform coordinate system assumed for an OpenGL frame on the 2160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezleft, and how these coordinates actually map to a typical device screen in landscape orientation 2170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezon the right. To solve this problem, you can apply OpenGL projection modes and camera views to 2180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztransform coordinates so your graphic objects have the correct proportions on any display.</p> 2190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In order to apply projection and camera views, you create a projection matrix and a camera view 2210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and apply them to the OpenGL rendering pipeline. The projection matrix recalculates the 2220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcoordinates of your graphics so that they map correctly to Android device screens. The camera view 2230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix creates a transformation that renders objects from a specific eye position.</p> 2240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="proj-es1">Projection and camera view in OpenGL ES 1.0</h3> 2260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In the ES 1.0 API, you apply projection and camera view by creating each matrix and then 2270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezadding them to the OpenGL environment.</p> 228d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol> 2300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Projection matrix</strong> - Create a projection matrix using the geometry of the 2310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen in order to recalculate object coordinates so they are drawn with correct proportions. 2328f134ea74badba7108989898117bb70c4226b5b5Joe FernandezThe following example code demonstrates how to modify the {@link 2338f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10, 2348f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezint, int) onSurfaceChanged()} method of a {@link android.opengl.GLSurfaceView.Renderer} 2358f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezimplementation to create a projection matrix based on the screen's aspect ratio and apply it to the 2368f134ea74badba7108989898117bb70c4226b5b5Joe FernandezOpenGL rendering environment. 2370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 2390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onSurfaceChanged(GL10 gl, int width, int height) { 2400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glViewport(0, 0, width, height); 241d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // make adjustments for screen ratio 2430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez float ratio = (float) width / height; 2440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glMatrixMode(GL10.GL_PROJECTION); // set matrix to projection mode 2450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glLoadIdentity(); // reset the matrix to its default state 2460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7); // apply the projection matrix 247d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly } 2480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 2490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 2500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Camera transformation matrix</strong> - Once you have adjusted the coordinate system 2520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezusing a projection matrix, you must also apply a camera view. The following example code shows how 253d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lyto modify the {@link 2548f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10) 2558f134ea74badba7108989898117bb70c4226b5b5Joe FernandezonDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer} 2568f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezimplementation to apply a model view and use the 2578f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez{@link android.opengl.GLU#gluLookAt(javax.microedition.khronos.opengles.GL10, float, float, float, 2588f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezfloat, float, float, float, float, float) GLU.gluLookAt()} utility to create a viewing tranformation 2598f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezwhich simulates a camera position. 2600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 2620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onDrawFrame(GL10 gl) { 2630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 2640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // Set GL_MODELVIEW transformation mode 2650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glMatrixMode(GL10.GL_MODELVIEW); 2660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez gl.glLoadIdentity(); // reset the matrix to its default state 267d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // When using GL_MODELVIEW, you must set the camera view 269d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f); 2700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 2710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez } 272d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly</pre> 2730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 2740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol> 2750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0</h3> 2780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In the ES 2.0 API, you apply projection and camera view by first adding a matrix member to 2790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe vertex shaders of your graphics objects. With this matrix member added, you can then 2800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezgenerate and apply projection and camera viewing matrices to your objects.</p> 281d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol> 2830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Add matrix to vertex shaders</strong> - Create a variable for the view projection matrix 2840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezand include it as a multiplier of the shader's position. In the following example vertex shader 285d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lycode, the included {@code uMVPMatrix} member allows you to apply projection and camera viewing 2860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrices to the coordinates of objects that use this shader. 2870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 289d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly private final String vertexShaderCode = 290d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2910664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // This matrix member variable provides a hook to manipulate 2920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // the coordinates of objects that use this vertex shader 2930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez "uniform mat4 uMVPMatrix; \n" + 294d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez "attribute vec4 vPosition; \n" + 2960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez "void main(){ \n" + 297d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2980664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // the matrix must be included as part of gl_Position 2990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez " gl_Position = uMVPMatrix * vPosition; \n" + 300d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez "} \n"; 3020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3030664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <p class="note"><strong>Note:</strong> The example above defines a single transformation matrix 3040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmember in the vertex shader into which you apply a combined projection matrix and camera view 3050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix. Depending on your application requirements, you may want to define separate projection 3060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and camera viewing matrix members in your vertex shaders so you can change them 3070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezindependently.</p> 3080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Access the shader matrix</strong> - After creating a hook in your vertex shaders to 3100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapply projection and camera view, you can then access that variable to apply projection and 3118f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezcamera viewing matrices. The following code shows how to modify the {@link 3128f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10, 3138f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezjavax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()} method of a {@link 3148f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer} implementation to access the matrix 3150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariable defined in the vertex shader above. 3160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 3180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onSurfaceCreated(GL10 unused, EGLConfig config) { 3190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 3200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix"); 3210664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 3220664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez } 3230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Create projection and camera viewing matrices</strong> - Generate the projection and 3260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezviewing matrices to be applied the graphic objects. The following example code shows how to modify 327d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lythe {@link 3288f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10, 3298f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezjavax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()} and {@link 3308f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10, 3318f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezint, int) onSurfaceChanged()} methods of a {@link android.opengl.GLSurfaceView.Renderer} 3328f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezimplementation to create camera view matrix and a projection matrix based on the screen aspect ratio 3338f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezof the device. 3340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 3360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onSurfaceCreated(GL10 unused, EGLConfig config) { 3370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 3380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // Create a camera view matrix 3390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f); 340d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly } 341d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onSurfaceChanged(GL10 unused, int width, int height) { 3430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez GLES20.glViewport(0, 0, width, height); 344d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez float ratio = (float) width / height; 346d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // create a projection matrix from device screen geometry 3480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7); 349d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly } 3500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Apply projection and camera viewing matrices</strong> - To apply the projection and 3540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcamera view transformations, multiply the matrices together and then set them into the vertex 3558f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezshader. The following example code shows how modify the {@link 3568f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10) 3578f134ea74badba7108989898117bb70c4226b5b5Joe FernandezonDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer} implementation to combine 3588f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezthe projection matrix and camera view created in the code above and then apply it to the graphic 3598f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezobjects to be rendered by OpenGL. 360d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 3620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez public void onDrawFrame(GL10 unused) { 3630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 3640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // Combine the projection and camera view matrices 3650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0); 366d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // Apply the combined projection and camera view transformations 3680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0); 369d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez // Draw objects 3710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez ... 3720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez } 3730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol> 3760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>For a complete example of how to apply projection and camera view with OpenGL ES 2.0, see the <a 377f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Mainhref="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> class.</p> 3780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 37950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="faces-winding">Shape Faces and Winding</h2> 38050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 38150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>In OpenGL, the face of a shape is a surface defined by three or more points in three-dimensional 38250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainspace. A set of three or more three-dimensional points (called vertices in OpenGL) have a front face 38350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainand a back face. How do you know which face is front and which is the back? Good question. The 38450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainanswer has to do with winding, or, the direction in which you define the points of a shape.</p> 38550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 38650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/opengl/ccw-winding.png"> 38750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 38850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 1.</strong> Illustration of a coordinate list which translates into a 38950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincounterclockwise drawing order.</p> 39050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 39150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>In this example, the points of the triangle are defined in an order such that they are drawn in a 39250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincounterclockwise direction. The order in which these coordinates are drawn defines the winding 39350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maindirection for the shape. By default, in OpenGL, the face which is drawn counterclockwise is the 39450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfront face. The triangle shown in Figure 1 is defined so that you are looking at the front face of 39550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainthe shape (as interpreted by OpenGL) and the other side is the back face.</p> 39650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 39750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Why is it important to know which face of a shape is the front face? The answer has to do with a 39850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincommonly used feature of OpenGL, called face culling. Face culling is an option for the OpenGL 39950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainenvironment which allows the rendering pipeline to ignore (not calculate or draw) the back face of a 40050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainshape, saving time, memory and processing cycles:</p> 40150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 40250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 40350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// enable face culling feature 40450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maingl.glEnable(GL10.GL_CULL_FACE); 40550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// specify which faces to not draw 40650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maingl.glCullFace(GL10.GL_BACK); 40750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 40850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 40950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>If you try to use the face culling feature without knowing which sides of your shapes are the 41050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfront and back, your OpenGL graphics are going to look a bit thin, or possibly not show up at all. 41150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainSo, always define the coordinates of your OpenGL shapes in a counterclockwise drawing order.</p> 41250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 41350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"><strong>Note:</strong> It is possible to set an OpenGL environment to treat the 41450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainclockwise face as the front face, but doing so requires more code and is likely to confuse 41550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainexperienced OpenGL developers when you ask them for help. So don’t do that.</p> 4160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 417a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="compatibility">OpenGL Versions and Device Compatibility</h2> 418a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 4190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0. 420a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezBeginning with Android 2.2 (API Level 8), the framework supports the OpenGL ES 2.0 API 421a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezspecification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new 422a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezapplications being developed with OpenGL. For information about the relative number of 423a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezAndroid-powered devices that support a given version of OpenGL ES, see the <a 424a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezhref="{@docRoot}resources/dashboard/opengl.html">OpenGL ES Versions Dashboard</a>.</p> 425a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 4260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 427a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h3 id="textures">Texture compression support</h3> 428a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Texture compression can significantly increase the performance of your OpenGL application by 429a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezreducing memory requirements and making more efficient use of memory bandwidth. The Android 430a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezframework provides support for the ETC1 compression format as a standard feature, including a {@link 4310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in the 4320664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid SDK at {@code <sdk>/tools/}). For an example of an Android application that uses 4330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztexture compression, see the <a 43419aad293c0dba4ed9a47939c487fecdd5318ef08Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/CompressedTextureActivity.html" 43519aad293c0dba4ed9a47939c487fecdd5318ef08Scott Main>CompressedTextureActivity</a> code sample.</p> 4369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 43750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>The ETC format is supported by most Android devices, but it not guarranteed to be available. To 43850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincheck if the ETC1 format is supported on a device, call the {@link 439a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p> 4409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 441a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an 442a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezalpha channel. If your application requires textures with an alpha channel, you should 443a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezinvestigate other texture compression formats available on your target devices.</p> 4449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 445a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Beyond the ETC1 format, Android devices have varied support for texture compression based on 4460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztheir GPU chipsets and OpenGL implementations. You should investigate texture compression support on 4470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe the devices you are are targeting to determine what compression types your application should 4480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupport. In order to determine what texture formats are supported on a given device, you must <a 4490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="#gl-extension-query">query the device</a> and review the <em>OpenGL extension names</em>, 4500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwhich identify what texture compression formats (and other OpenGL features) are supported by the 4510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice. Some commonly supported texture compression formats are as follows:</p> 4529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 4540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>ATITC (ATC)</strong> - ATI texture compression (ATITC or ATC) is available on a 4550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwide variety of devices and supports fixed rate compression for RGB textures with and without 4560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezan alpha channel. This format may be represented by several OpenGL extension names, for example: 4570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 4580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_AMD_compressed_ATC_texture}</li> 4590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_ATI_texture_compression_atitc}</li> 4600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 4610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 4620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>PVRTC</strong> - PowerVR texture compression (PVRTC) is available on a wide 4630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariety of devices and supports 2-bit and 4-bit per pixel textures with or without an alpha channel. 4640664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezThis format is represented by the following OpenGL extension name: 4650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 4660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_IMG_texture_compression_pvrtc}</li> 4670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 4680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 4690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>S3TC (DXT<em>n</em>/DXTC)</strong> - S3 texture compression (S3TC) has several 4700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezformat variations (DXT1 to DXT5) and is less widely available. The format supports RGB textures with 4710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez4-bit alpha or 8-bit alpha channels. This format may be represented by several OpenGL extension 4720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeznames, for example: 4730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 4740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_OES_texture_compression_S3TC}</li> 4750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_s3tc}</li> 4760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt1}</li> 4770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt3}</li> 4780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt5}</li> 4790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 4800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 4810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>3DC</strong> - 3DC texture compression (3DC) is a less widely available format that 4820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupports RGB textures with an an alpha channel. This format is represented by the following OpenGL 4830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezextension name:</li> 4840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 4850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_AMD_compressed_3DC_texture}</li> 4860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 4870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 4880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 4890664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="warning"><strong>Warning:</strong> These texture compression formats are <em>not 4900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported</em> on all devices. Support for these formats can vary by manufacturer and device. For 4910664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinformation on how to determine what texture compression formats are on a particular device, see 4920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe next section. 4930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 4940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 4950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="note"><strong>Note:</strong> Once you decide which texture compression formats your 4960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapplication will support, make sure you declare them in your manifest using <a 4970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture> 4984d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Dougherty</a>. Using this declaration enables filtering by external services such as Google Play, so that 4990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezyour app is installed only on devices that support the formats your app requires. For details, see 5000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<a 5010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p> 5020664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5030664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="gl-extension-query">Determining OpenGL extensions</h3> 5040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Implementations of OpenGL vary by Android device in terms of the extensions to the OpenGL ES API 5050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthat are supported. These extensions include texture compressions, but typically also include other 5060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezextensions to the OpenGL feature set.</p> 5070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>To determine what texture compression formats, and other OpenGL extensions, are supported on a 5090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezparticular device:</p> 510a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<ol> 511a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>Run the following code on your target devices to determine what texture compression 512a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezformats are supported: 513a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<pre> 514a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez String extensions = javax.microedition.khronos.opengles.GL10.glGetString(GL10.GL_EXTENSIONS); 515a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</pre> 5160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <p class="warning"><b>Warning:</b> The results of this call <em>vary by device!</em> You 5170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmust run this call on several target devices to determine what compression types are commonly 5180664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported.</p> 519a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 5200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>Review the output of this method to determine what OpenGL extensions are supported on the 521d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lydevice.</li> 522a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ol> 5239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="choosing-version">Choosing an OpenGL API Version</h2> 5260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>OpenGL ES API version 1.0 (and the 1.1 extensions) and version 2.0 both provide high 5280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezperformance graphics interfaces for creating 3D games, visualizations and user interfaces. Graphics 5290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezprogramming for the OpenGL ES 1.0/1.1 API versus ES 2.0 differs significantly, and so developers 5300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezshould carefully consider the following factors before starting development with either API:</p> 5310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5320664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 5330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Performance</strong> - In general, OpenGL ES 2.0 provides faster graphics performance 5340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthan the ES 1.0/1.1 APIs. However, the performance difference can vary depending on the Android 5350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice your OpenGL application is running on, due to differences in the implementation of the OpenGL 5360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezgraphics pipeline.</li> 537d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly <li><strong>Device Compatibility</strong> - Developers should consider the types of devices, 5380664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid versions and the OpenGL ES versions available to their customers. For more information 5390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezon OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and Device 5400664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezCompatibility</a> section.</li> 5410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Coding Convenience</strong> - The OpenGL ES 1.0/1.1 API provides a fixed function 5420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezpipeline and convenience functions which are not available in the ES 2.0 API. Developers who are new 5430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezto OpenGL may find coding for OpenGL ES 1.0/1.1 faster and more convenient.</li> 5440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 API provides a higher degree 5450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezof control by providing a fully programmable pipeline through the use of shaders. With more 5460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdirect control of the graphics processing pipeline, developers can create effects that would be 5470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvery difficult to generate using the 1.0/1.1 API.</li> 5480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 549d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 5500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>While performance, compatibility, convenience, control and other factors may influence your 5510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdecision, you should pick an OpenGL API version based on what you think provides the best experience 5520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezfor your users.</p> 553