1b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpage.title=OpenGL ES 233baa5ad7d8cdcc89ce4fbc3bc8cd537d5f5d639Joe Fernandezpage.tags=games 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project@jd:body 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<div id="qv-wrapper"> 6a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <div id="qv"> 7a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <h2>In this document</h2> 8d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 9a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 100664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#basics">The Basics</a> 110664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ol> 12b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="#packages">OpenGL ES packages</a></li> 130664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ol> 140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#manifest">Declaring OpenGL Requirements</a></li> 15d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly <li><a href="#coordinate-mapping">Mapping Coordinates for Drawn Objects</a> 160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ol> 170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#proj-es1">Projection and camera in ES 1.0</a></li> 18b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="#proj-es2">Projection and camera in ES 2.0 and higher</a></li> 190664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ol> 200664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 21b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="#faces-winding">Shape Faces and Winding</a></li> 22a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a> 23a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><a href="#textures">Texture compression support</a></li> 25b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="#gl-extension-query">Determining OpenGL extensions</a></li> 26b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="#version-check">Checking OpenGL ES Version</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> 36a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <h2>See also</h2> 37a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ol> 3850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="{@docRoot}training/graphics/opengl/index.html"> 3950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main Displaying Graphics with OpenGL ES</a></li> 40a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li> 41a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li> 42a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li> 43b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><a href="http://www.khronos.org/opengles/3_X/">OpenGL ES 3.x specification</a></li> 44a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ol> 45a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </div> 46a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</div> 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 48a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library 49778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman(OpenGL®), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that 50778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanspecifies a 510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezstandard software interface for 3D graphics processing hardware. OpenGL ES is a flavor of the OpenGL 52b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezspecification intended for embedded devices. Android supports several versions of the OpenGL ES 53b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezAPI:</p> 54b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 55b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<ul> 56b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>OpenGL ES 1.0 and 1.1 - This API specification is supported by Android 1.0 and higher.</li> 57b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>OpenGL ES 2.0 - This API specification is supported by Android 2.2 (API level 8) and higher. 58b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </li> 59b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>OpenGL ES 3.0 - This API specification is supported by Android 4.3 (API level 18) and higher. 60b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </li> 61778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>OpenGL ES 3.1 - This API specification is supported by Android 5.0 (API level 21) and higher. 62778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman </li> 63b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</ul> 64b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 65b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p class="caution"><strong>Caution:</strong> 66b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Support of the OpenGL ES 3.0 API on a device requires an implementation of this graphics 67b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez pipeline provided by the device manufacturer. A device running Android 4.3 or higher <em>may 68b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez not support</em> the OpenGL ES 3.0 API. For information on checking what version of OpenGL ES 69b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez is supported at run time, see <a href="#version-check">Checking OpenGL ES Version</a>. 70b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</p> 71b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 72b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p class="note"><strong>Note:</strong> 73b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez The specific API provided by the Android framework is similar to the J2ME JSR239 OpenGL ES API, 74b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez but is not identical. If you are familiar with J2ME JSR239 specification, be alert for 75b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez variations.</p> 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 79a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="basics">The Basics</h2> 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 81a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Android supports OpenGL both through its framework API and the Native Development 82a53afedf783176d531e7cf8744f9b07ce60a5c92Joe FernandezKit (NDK). This topic focuses on the Android framework interfaces. For more information about the 8350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainNDK, see the <a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK</a>. 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 85d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly<p>There are two foundational classes in the Android framework that let you create and manipulate 86a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezgraphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link 87a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezandroid.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application, 88a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezunderstanding how to implement these classes in an activity should be your first objective. 89a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</p> 90a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 91a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<dl> 920664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dt><strong>{@link android.opengl.GLSurfaceView}</strong></dt> 930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dd>This class is a {@link android.view.View} where you can draw and manipulate objects using 940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez OpenGL API calls and is similar in function to a {@link android.view.SurfaceView}. You can use 95d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly this class by creating an instance of {@link android.opengl.GLSurfaceView} and adding your 96a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez {@link android.opengl.GLSurfaceView.Renderer Renderer} to it. However, if you want to capture 97a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez touch screen events, you should extend the {@link android.opengl.GLSurfaceView} class to 98f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main implement the touch listeners, as shown in OpenGL training lesson, 99f05e34a10ca262cf1f73a6347b6e5be26718e686Scott Main <a href="{@docRoot}training/graphics/opengl/touch.html">Responding to Touch Events</a>.</dd> 100d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 1010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <dt><strong>{@link android.opengl.GLSurfaceView.Renderer}</strong></dt> 102b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <dd>This interface defines the methods required for drawing graphics in a {@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()}. 107d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 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 132d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly respond to changes in the {@link android.opengl.GLSurfaceView} container. 133a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 134a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 135a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </dd> 136a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</dl> 137a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 138b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<h3 id="packages">OpenGL ES packages</h3> 139b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>Once you have established a container view for OpenGL ES 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> 146b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES 147b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 1.0/1.1 classes and better performance than the {@code javax.microedition.khronos} package 148b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez interfaces. 149b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <ul> 150b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link android.opengl.GLES10}</li> 151b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link android.opengl.GLES10Ext}</li> 152b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link android.opengl.GLES11}</li> 153b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link android.opengl.GLES11Ext}</li> 154b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </ul> 155b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </li> 156a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>{@link javax.microedition.khronos.opengles} - This package provides the standard 157b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez implementation of OpenGL ES 1.0/1.1. 158b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <ul> 159b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL10}</li> 160b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li> 161b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11}</li> 162b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li> 163b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li> 164b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </ul> 165a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 166a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 167a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 168a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>OpenGL ES 2.0 API Class 169a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <ul> 1700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@link android.opengl.GLES20 android.opengl.GLES20} - This package provides the 171b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez interface to OpenGL ES 2.0 and is available starting with Android 2.2 (API level 8).</li> 172b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </ul> 173b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </li> 174778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman </li> 175778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>OpenGL ES 3.0/3.1 API Packages 176b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <ul> 177778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>{@link android.opengl} - This package provides the interface to the OpenGL ES 3.0/3.1 178778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanclasses. 179778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman Version 3.0 is available starting with Android 4.3 (API level 18). Version 3.1 is available 180778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanstarting with Android 5.0 (API level 21). 181778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <ul> 182778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>{@link android.opengl.GLES30}</li> 183778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>{@link android.opengl.GLES31} </li> 184778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>{@link android.opengl.GLES31Ext} (<a href="#aep">Android Extension Pack</a>)</li> 185778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman </ul> 186a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </ul> 187a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 188a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ul> 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 190b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>If you want to start building an app with OpenGL ES right away, follow the 191b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> 192b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezclass. 1930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 1940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 1950664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="manifest">Declaring OpenGL Requirements</h2> 1960664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>If your application uses OpenGL features that are not available on all devices, you must include 197d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lythese requirements in your <a 198b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezhref="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file. 1990664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezHere are the most common OpenGL manifest declarations:</p> 2000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2010664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 202778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li><strong>OpenGL ES version requirements</strong> - If your application requires a specific 203778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanversion of 204778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman OpenGL ES, you must declare that requirement by adding the following settings to your manifest as 205778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanshown below.</li> 206778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 207778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>For OpenGL ES 2.0:</p> 2080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 210b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<!-- Tell the system this app requires OpenGL ES 2.0. --> 211b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<uses-feature android:glEsVersion="0x00020000" android:required="true" /> 212b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</pre> 213b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 214b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <p>Adding this declaration causes Google Play to restrict your application from being 215b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez installed on devices that do not support OpenGL ES 2.0. If your application is exclusively for 216b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez devices that support OpenGL ES 3.0, you can also specify this in your manifest:</p> 217b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 218778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>For OpenGL ES 3.0:</p> 219778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 220b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<pre> 221b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<!-- Tell the system this app requires OpenGL ES 3.0. --> 222b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<uses-feature android:glEsVersion="0x00030000" android:required="true" /> 2230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 2240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 225778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>For OpenGL ES 3.1:</p> 226778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 227778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<pre> 228778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<!-- Tell the system this app requires OpenGL ES 3.1. --> 229778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<uses-feature android:glEsVersion="0x00030001" android:required="true" /> 230778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman</pre> 231778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 232b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <p class="note"><strong>Note:</strong> 233778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman The OpenGL ES 3.x API is backwards-compatible with the 2.0 API, which means you can be more 234b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez flexible with your implementation of OpenGL ES in your application. By declaring the OpenGL 235b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ES 2.0 API as a requirement in your manifest, you can use that API version as a default, check 236778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman for the availability of the 3.x API at run time and then use OpenGL ES 3.x features if the 237b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez device supports it. For more information about checking the OpenGL ES version supported by a 238b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez device, see <a href="#version-check">Checking OpenGL ES Version</a>. 239b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </p> 240b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 2410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 2420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Texture compression requirements</strong> - If your application uses texture 2438f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezcompression formats, you must declare the formats your application supports in your manifest file 2448f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezusing <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code 2458f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez<supports-gl-texture>}</a>. For more information about available texture compression 246d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lyformats, see <a href="#textures">Texture compression support</a>. 2470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Declaring texture compression requirements in your manifest hides your application from users 2490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwith devices that do not support at least one of your declared compression types. For more 2504d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Doughertyinformation on how Google Play filtering works for texture compressions, see the <a 2510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering"> 2524d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk DoughertyGoogle Play and texture compression filtering</a> section of the {@code 253d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly<supports-gl-texture>} documentation.</p> 2540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 2550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 2560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2588f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez<h2 id="coordinate-mapping">Mapping Coordinates for Drawn Objects</h2> 2590664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>One of the basic problems in displaying graphics on Android devices is that their screens can 2610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvary in size and shape. OpenGL assumes a square, uniform coordinate system and, by default, happily 2620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdraws those coordinates onto your typically non-square screen as if it is perfectly square.</p> 2630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<img src="{@docRoot}images/opengl/coordinates.png"> 2650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="img-caption"> 2660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <strong>Figure 1.</strong> Default OpenGL coordinate system (left) mapped to a typical Android 2670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen (right). 2680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 2690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The illustration above shows the uniform coordinate system assumed for an OpenGL frame on the 2710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezleft, and how these coordinates actually map to a typical device screen in landscape orientation 2720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezon the right. To solve this problem, you can apply OpenGL projection modes and camera views to 2730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztransform coordinates so your graphic objects have the correct proportions on any display.</p> 2740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In order to apply projection and camera views, you create a projection matrix and a camera view 2760664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and apply them to the OpenGL rendering pipeline. The projection matrix recalculates the 2770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcoordinates of your graphics so that they map correctly to Android device screens. The camera view 2780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix creates a transformation that renders objects from a specific eye position.</p> 2790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 280b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 2810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="proj-es1">Projection and camera view in OpenGL ES 1.0</h3> 2820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>In the ES 1.0 API, you apply projection and camera view by creating each matrix and then 2830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezadding them to the OpenGL environment.</p> 284d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 2850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol> 2860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Projection matrix</strong> - Create a projection matrix using the geometry of the 2870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice screen in order to recalculate object coordinates so they are drawn with correct proportions. 2888f134ea74badba7108989898117bb70c4226b5b5Joe FernandezThe following example code demonstrates how to modify the {@link 2898f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10, 2908f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezint, int) onSurfaceChanged()} method of a {@link android.opengl.GLSurfaceView.Renderer} 2918f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezimplementation to create a projection matrix based on the screen's aspect ratio and apply it to the 2928f134ea74badba7108989898117bb70c4226b5b5Joe FernandezOpenGL rendering environment. 2930664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 2940664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 295b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onSurfaceChanged(GL10 gl, int width, int height) { 296b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glViewport(0, 0, width, height); 297b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 298b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // make adjustments for screen ratio 299b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez float ratio = (float) width / height; 300b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glMatrixMode(GL10.GL_PROJECTION); // set matrix to projection mode 301b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glLoadIdentity(); // reset the matrix to its default state 302b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7); // apply the projection matrix 303b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 3040664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Camera transformation matrix</strong> - Once you have adjusted the coordinate system 3080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezusing a projection matrix, you must also apply a camera view. The following example code shows how 309d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lyto modify the {@link 3108f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10) 3118f134ea74badba7108989898117bb70c4226b5b5Joe FernandezonDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer} 3128f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezimplementation to apply a model view and use the 3138f134ea74badba7108989898117bb70c4226b5b5Joe Fernandez{@link android.opengl.GLU#gluLookAt(javax.microedition.khronos.opengles.GL10, float, float, float, 3148f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezfloat, float, float, float, float, float) GLU.gluLookAt()} utility to create a viewing tranformation 3158f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezwhich simulates a camera position. 3160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3170664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 318b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onDrawFrame(GL10 gl) { 319b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 320b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Set GL_MODELVIEW transformation mode 321b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glMatrixMode(GL10.GL_MODELVIEW); 322b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez gl.glLoadIdentity(); // reset the matrix to its default state 323b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 324b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // When using GL_MODELVIEW, you must set the camera view 325b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f); 326b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 327b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 328d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly</pre> 3290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol> 3310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3320664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 333b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0 and higher</h3> 334b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 335b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>In the ES 2.0 and 3.0 APIs, you apply projection and camera view by first adding a matrix member 336b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezto the vertex shaders of your graphics objects. With this matrix member added, you can then 3370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezgenerate and apply projection and camera viewing matrices to your objects.</p> 338d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 3390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ol> 3400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Add matrix to vertex shaders</strong> - Create a variable for the view projection matrix 3410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezand include it as a multiplier of the shader's position. In the following example vertex shader 342d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lycode, the included {@code uMVPMatrix} member allows you to apply projection and camera viewing 3430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrices to the coordinates of objects that use this shader. 3440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 346b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezprivate final String vertexShaderCode = 347d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 348b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // This matrix member variable provides a hook to manipulate 349b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // the coordinates of objects that use this vertex shader. 350b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez "uniform mat4 uMVPMatrix; \n" + 351d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 352b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez "attribute vec4 vPosition; \n" + 353b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez "void main(){ \n" + 354b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // The matrix must be included as part of gl_Position 355b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Note that the uMVPMatrix factor *must be first* in order 356b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // for the matrix multiplication product to be correct. 357b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez " gl_Position = uMVPMatrix * vPosition; \n" + 358d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 359b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez "} \n"; 3600664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <p class="note"><strong>Note:</strong> The example above defines a single transformation matrix 3620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmember in the vertex shader into which you apply a combined projection matrix and camera view 3630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix. Depending on your application requirements, you may want to define separate projection 3640664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmatrix and camera viewing matrix members in your vertex shaders so you can change them 3650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezindependently.</p> 3660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Access the shader matrix</strong> - After creating a hook in your vertex shaders to 3680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapply projection and camera view, you can then access that variable to apply projection and 3698f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezcamera viewing matrices. The following code shows how to modify the {@link 3708f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10, 3718f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezjavax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()} method of a {@link 3728f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer} implementation to access the matrix 3730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariable defined in the vertex shader above. 3740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 376b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onSurfaceCreated(GL10 unused, EGLConfig config) { 377b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 378b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix"); 379b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 380b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 3810664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 3820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 3830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Create projection and camera viewing matrices</strong> - Generate the projection and 3840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezviewing matrices to be applied the graphic objects. The following example code shows how to modify 385b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezthe {@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} and 386b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez{@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} methods of a 387b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez{@link android.opengl.GLSurfaceView.Renderer} implementation to create camera view matrix and a 388b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezprojection matrix based on the screen aspect ratio of the device. 3890664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 3900664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 391b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onSurfaceCreated(GL10 unused, EGLConfig config) { 392b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 393b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Create a camera view matrix 394b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f); 395b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 396d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 397b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onSurfaceChanged(GL10 unused, int width, int height) { 398b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez GLES20.glViewport(0, 0, width, height); 399d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 400b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez float ratio = (float) width / height; 401d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 402b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // create a projection matrix from device screen geometry 403b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7); 404b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 4050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 4060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 4070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 4080664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<li><strong>Apply projection and camera viewing matrices</strong> - To apply the projection and 4090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezcamera view transformations, multiply the matrices together and then set them into the vertex 4108f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezshader. The following example code shows how modify the {@link 4118f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezandroid.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10) 4128f134ea74badba7108989898117bb70c4226b5b5Joe FernandezonDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer} implementation to combine 4138f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezthe projection matrix and camera view created in the code above and then apply it to the graphic 4148f134ea74badba7108989898117bb70c4226b5b5Joe Fernandezobjects to be rendered by OpenGL. 415d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 4160664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<pre> 417b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpublic void onDrawFrame(GL10 unused) { 418b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 419b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Combine the projection and camera view matrices 420b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0); 421d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 422b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Apply the combined projection and camera view transformations 423b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0); 424d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 425b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // Draw objects 426b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez ... 427b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 4280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</pre> 4290664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</li> 4300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ol> 4310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>For a complete example of how to apply projection and camera view with OpenGL ES 2.0, see the <a 432778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanhref="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a> 433778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanclass.</p> 4340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 435b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 43650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="faces-winding">Shape Faces and Winding</h2> 43750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 43850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>In OpenGL, the face of a shape is a surface defined by three or more points in three-dimensional 43950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainspace. A set of three or more three-dimensional points (called vertices in OpenGL) have a front face 44050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainand a back face. How do you know which face is front and which is the back? Good question. The 44150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainanswer has to do with winding, or, the direction in which you define the points of a shape.</p> 44250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 44350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/opengl/ccw-winding.png"> 44450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="img-caption"> 44550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <strong>Figure 1.</strong> Illustration of a coordinate list which translates into a 44650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincounterclockwise drawing order.</p> 44750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 44850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>In this example, the points of the triangle are defined in an order such that they are drawn in a 44950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincounterclockwise direction. The order in which these coordinates are drawn defines the winding 45050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maindirection for the shape. By default, in OpenGL, the face which is drawn counterclockwise is the 45150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfront face. The triangle shown in Figure 1 is defined so that you are looking at the front face of 45250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainthe shape (as interpreted by OpenGL) and the other side is the back face.</p> 45350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 45450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Why is it important to know which face of a shape is the front face? The answer has to do with a 45550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maincommonly used feature of OpenGL, called face culling. Face culling is an option for the OpenGL 45650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainenvironment which allows the rendering pipeline to ignore (not calculate or draw) the back face of a 45750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainshape, saving time, memory and processing cycles:</p> 45850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 45950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 46050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// enable face culling feature 46150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maingl.glEnable(GL10.GL_CULL_FACE); 46250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// specify which faces to not draw 46350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Maingl.glCullFace(GL10.GL_BACK); 46450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 46550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 46650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>If you try to use the face culling feature without knowing which sides of your shapes are the 46750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfront and back, your OpenGL graphics are going to look a bit thin, or possibly not show up at all. 46850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainSo, always define the coordinates of your OpenGL shapes in a counterclockwise drawing order.</p> 46950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 47050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p class="note"><strong>Note:</strong> It is possible to set an OpenGL environment to treat the 47150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainclockwise face as the front face, but doing so requires more code and is likely to confuse 47250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainexperienced OpenGL developers when you ask them for help. So don’t do that.</p> 4730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 474b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 475a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h2 id="compatibility">OpenGL Versions and Device Compatibility</h2> 476a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 4770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0. 478b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezBeginning with Android 2.2 (API level 8), the framework supports the OpenGL ES 2.0 API 479a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezspecification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new 480b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezapplications being developed with OpenGL. OpenGL ES 3.0 is supported with Android 4.3 481b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez(API level 18) and higher, on devices that provide an implementation of the OpenGL ES 3.0 API. 482b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezFor information about the relative number of Android-powered devices 483b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezthat support a given version of OpenGL ES, see the 484b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<a href="{@docRoot}about/dashboards/index.html#OpenGL">OpenGL ES Version Dashboard</a>.</p> 485b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 486b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>Graphics programming with OpenGL ES 1.0/1.1 API is significantly different than using the 2.0 487b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezand higher versions. The 1.x version of the API has more convenience methods and a fixed graphics 488b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezpipeline, while the OpenGL ES 2.0 and 3.0 APIs provide more direct control of the pipeline through 489b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezuse of OpenGL shaders. You should carefully consider the graphics requirements and choose the API 490b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezversion that works best for your application. For more information, see 491b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<a href="#choosing-version">Choosing an OpenGL API Version</a>.</p> 492b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 493b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>The OpenGL ES 3.0 API provides additional features and better performance than the 2.0 API and is 494b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezalso backward compatible. This means that you can potentially write your application targeting 495b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezOpenGL ES 2.0 and conditionally include OpenGL ES 3.0 graphics features if they are available. For 496b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezmore information on checking for availability of the 3.0 API, see 497b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<a href="#version-check">Checking OpenGL ES Version</a></p> 498a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez 4990664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 500a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<h3 id="textures">Texture compression support</h3> 501b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 502a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p>Texture compression can significantly increase the performance of your OpenGL application by 503a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezreducing memory requirements and making more efficient use of memory bandwidth. The Android 504a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezframework provides support for the ETC1 compression format as a standard feature, including a {@link 5050664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezandroid.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in the 5060664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezAndroid SDK at {@code <sdk>/tools/}). For an example of an Android application that uses 507b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandeztexture compression, see the {@code CompressedTextureActivity} code sample in Android SDK 508b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez({@code <sdk>/samples/<version>/ApiDemos/src/com/example/android/apis/graphics/}).</p> 5099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 510b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p class="caution"><strong>Caution:</strong> The ETC1 format is supported by most Android devices, 511b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezbut it not guaranteed to be available. To check if the ETC1 format is supported on a device, call 512b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezthe {@link android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p> 5139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 514a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an 515b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandeztransparency (alpha channel). If your application requires textures with transparency, you should 516a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezinvestigate other texture compression formats available on your target devices.</p> 5179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 518b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>The ETC2/EAC texture compression formats are guaranteed to be available when using the OpenGL ES 519b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez3.0 API. This texture format offers excellent compression ratios with high visual quality and the 520b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezformat also supports transparency (alpha channel).</p> 521b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 522b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>Beyond the ETC formats, Android devices have varied support for texture compression based on 5230664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeztheir GPU chipsets and OpenGL implementations. You should investigate texture compression support on 52476dfc02135abae5337b48fe99a1b8c0a7d95e33akmccormickthe devices you are are targeting to determine what compression types your application should 5250664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupport. In order to determine what texture formats are supported on a given device, you must <a 5260664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="#gl-extension-query">query the device</a> and review the <em>OpenGL extension names</em>, 5270664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwhich identify what texture compression formats (and other OpenGL features) are supported by the 5280664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdevice. Some commonly supported texture compression formats are as follows:</p> 5299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5300664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 5310664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>ATITC (ATC)</strong> - ATI texture compression (ATITC or ATC) is available on a 5320664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezwide variety of devices and supports fixed rate compression for RGB textures with and without 5330664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezan alpha channel. This format may be represented by several OpenGL extension names, for example: 5340664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 5350664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_AMD_compressed_ATC_texture}</li> 5360664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_ATI_texture_compression_atitc}</li> 5370664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 5380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 5390664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>PVRTC</strong> - PowerVR texture compression (PVRTC) is available on a wide 5400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezvariety of devices and supports 2-bit and 4-bit per pixel textures with or without an alpha channel. 5410664a8f661e15991e20cab1c0daa41f5e21977abJoe FernandezThis format is represented by the following OpenGL extension name: 5420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 5430664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_IMG_texture_compression_pvrtc}</li> 5440664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 5450664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 5460664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>S3TC (DXT<em>n</em>/DXTC)</strong> - S3 texture compression (S3TC) has several 5470664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezformat variations (DXT1 to DXT5) and is less widely available. The format supports RGB textures with 5480664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez4-bit alpha or 8-bit alpha channels. This format may be represented by several OpenGL extension 5490664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandeznames, for example: 5500664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 5510664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_OES_texture_compression_S3TC}</li> 5520664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_s3tc}</li> 5530664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt1}</li> 5540664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt3}</li> 5550664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_EXT_texture_compression_dxt5}</li> 5560664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 5570664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </li> 5580664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>3DC</strong> - 3DC texture compression (3DC) is a less widely available format that 559b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezsupports RGB textures with an alpha channel. This format is represented by the following OpenGL 560b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezextension name: 5610664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <ul> 5620664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>{@code GL_AMD_compressed_3DC_texture}</li> 5630664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez </ul> 564b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez </li> 5650664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 5660664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5670664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="warning"><strong>Warning:</strong> These texture compression formats are <em>not 5680664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported</em> on all devices. Support for these formats can vary by manufacturer and device. For 5690664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezinformation on how to determine what texture compression formats are on a particular device, see 5700664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthe next section. 5710664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</p> 5720664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5730664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p class="note"><strong>Note:</strong> Once you decide which texture compression formats your 5740664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezapplication will support, make sure you declare them in your manifest using <a 5750664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture> 5764d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Dougherty</a>. Using this declaration enables filtering by external services such as Google Play, so that 5770664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezyour app is installed only on devices that support the formats your app requires. For details, see 5780664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<a 5790664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezhref="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p> 5800664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 581b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 5820664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h3 id="gl-extension-query">Determining OpenGL extensions</h3> 5830664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>Implementations of OpenGL vary by Android device in terms of the extensions to the OpenGL ES API 5840664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezthat are supported. These extensions include texture compressions, but typically also include other 5850664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezextensions to the OpenGL feature set.</p> 5860664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 5870664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>To determine what texture compression formats, and other OpenGL extensions, are supported on a 5880664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezparticular device:</p> 589a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<ol> 590a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez <li>Run the following code on your target devices to determine what texture compression 591a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandezformats are supported: 592a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez<pre> 593b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezString extensions = javax.microedition.khronos.opengles.GL10.glGetString( 594b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez GL10.GL_EXTENSIONS); 595a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</pre> 596b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <p class="warning"><b>Warning:</b> The results of this call <em>vary by device model!</em> You 5970664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezmust run this call on several target devices to determine what compression types are commonly 5980664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezsupported.</p> 599a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez </li> 6000664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li>Review the output of this method to determine what OpenGL extensions are supported on the 601d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Lydevice.</li> 602a53afedf783176d531e7cf8744f9b07ce60a5c92Joe Fernandez</ol> 6039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 604778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<h4 id="aep">Android Extension Pack (AEP)</h4> 605778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 606778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p> The AEP ensures that your application supports a standardized set of OpenGL extensions above 607778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanand beyond 608778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanthe core set described in the OpenGL 3.1 specification. Packaging these extensions together 609778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanencourages a consistent set of functionality across devices, while allowing developers to take full 610778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanadvantage of the latest crop of mobile GPU devices.</p> 611778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 612778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>The AEP also improves support for images, shader storage buffers, and atomic counters in 613778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanfragment shaders.</p> 614778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 615778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>For your app to be able to use the AEP, the app's manifest must declare that the AEP is required. 616778d3552d60c18a1525dfd1ecc89062936b0679fDavid FriedmanIn addition, the platform version must support it. </p> 617778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 618778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>Declare the AEP requirement in the manifest as follows:</p> 619778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 620778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<pre> 621778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<uses feature android:name="android.hardware.opengles.aep" 622778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman android:required="true" /> 623778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman</pre> 624778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 625778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>To verify that the platform version supports the AEP, use the 626778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman{@link android.content.pm.PackageManager#hasSystemFeature} method, passing in 627778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman{@link android.content.pm.PackageManager#FEATURE_OPENGLES_EXTENSION_PACK} as the argument. The following code snippet 628778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanshows an example of how to do so:</p> 629778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 630778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<pre> 631778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanboolean deviceSupportsAEP = getPackageManager().hasSystemFeature 632778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman (PackageManager.FEATURE_OPENGLES_EXTENSION_PACK); 633778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman</pre> 634778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 635778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>If the method returns true, AEP is supported.<p> 636778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 637778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>For more information about the AEP, visit its page at the <a 638778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedmanhref="https://www.khronos.org/registry/gles/extensions/ANDROID/ANDROID_extension_pack_es31a.txt"> 639778d3552d60c18a1525dfd1ecc89062936b0679fDavid FriedmanKhronos OpenGL ES Registry</a>. 640778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman 6419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 642778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<h3 id="version-check">Checking the OpenGL ES Version</h3> 643b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 644778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman<p>There are several versions of OpenGL ES available on Android devices. You can specify the 645b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezminimum version of the API your application requires in your <a href="#manifest">manifest</a>, but 646b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezyou may also want to take advantage of features in a newer API at the same time. For example, 647b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezthe OpenGL ES 3.0 API is backward-compatible with the 2.0 version of the API, so you may want to 648b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezwrite your application so that it uses OpenGL ES 3.0 features, but falls back to the 2.0 API if the 649b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez3.0 API is not available.</p> 650b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 651b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>Before using OpenGL ES features from a version higher than the minimum required in your 652b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezapplication manifest, your application should check the version of the API available on the device. 653b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezYou can do this in one of two ways:</p> 654b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 655b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<ol> 656778d3552d60c18a1525dfd1ecc89062936b0679fDavid Friedman <li>Attempt to create the higher-level OpenGL ES context ({@link android.opengl.EGLContext}) and 657b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez check the result.</li> 658b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li>Create a minimum-supported OpenGL ES context and check the version value.</li> 659b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</ol> 660b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 661b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>The following example code demonstrates how to check the available OpenGL ES version by creating 662b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezan {@link android.opengl.EGLContext} and checking the result. This example shows how to check for 663b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezOpenGL ES 3.0 version:</p> 664b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 665b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<pre> 666b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezprivate static double glVersion = 3.0; 667b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 668b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezprivate static class ContextFactory implements GLSurfaceView.EGLContextFactory { 669b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 670b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez private static int EGL_CONTEXT_CLIENT_VERSION = 0x3098; 671b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 672b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez public EGLContext createContext( 673b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez EGL10 egl, EGLDisplay display, EGLConfig eglConfig) { 674b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 675b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Log.w(TAG, "creating OpenGL ES " + glVersion + " context"); 676b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez int[] attrib_list = {EGL_CONTEXT_CLIENT_VERSION, (int) glVersion, 677b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez EGL10.EGL_NONE }; 678b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez // attempt to create a OpenGL ES 3.0 context 679b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez EGLContext context = egl.eglCreateContext( 680b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez display, eglConfig, EGL10.EGL_NO_CONTEXT, attrib_list); 681b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez return context; // returns null if 3.0 is not supported; 682b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez } 683b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez} 684b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</pre> 685b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 686b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>If the {@code createContext()} method show above returns null, your code should create a OpenGL 687b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezES 2.0 context instead and fall back to using only that API.</p> 688b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 689b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>The following code example demonstrates how to check the OpenGL ES version by creating a minimum 690b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezsupported context first, and then checking the version string:</p> 691b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 692b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<pre> 693b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez// Create a minimum supported OpenGL ES context, then check: 694b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezString version = javax.microedition.khronos.opengles.GL10.glGetString( 695b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez GL10.GL_VERSION); 696b5c29e75a078f628f8a43a6ca9174fe78d738810Joe FernandezLog.w(TAG, "Version: " + version ); 697b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez// The version format is displayed as: "OpenGL ES <major>.<minor>" 698b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez// followed by optional content provided by the implementation. 699b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez</pre> 700b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 701b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>With this approach, if you discover that the device supports a higher-level API version, you 702b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezmust destroy the minimum OpenGL ES context and create a new context with the higher 703b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezavailable API version.</p> 704b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 705b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 7060664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<h2 id="choosing-version">Choosing an OpenGL API Version</h2> 7070664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 708b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez<p>OpenGL ES 1.0 API version (and the 1.1 extensions), version 2.0, and version 3.0 all provide high 7090664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezperformance graphics interfaces for creating 3D games, visualizations and user interfaces. Graphics 710b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezprogamming for OpenGL ES 2.0 and 3.0 is largely similar, with version 3.0 representing a superset 711b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezof the 2.0 API with additional features. Programming for the OpenGL ES 1.0/1.1 API versus OpenGL ES 712b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez2.0 and 3.0 differs significantly, and so developers should carefully consider the following 713b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandezfactors before starting development with these APIs:</p> 7140664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez 7150664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<ul> 716b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><strong>Performance</strong> - In general, OpenGL ES 2.0 and 3.0 provide faster graphics 717b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez performance than the ES 1.0/1.1 APIs. However, the performance difference can vary depending on 718b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez the Android device your OpenGL application is running on, due to differences in hardware 719b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez manufacturer's implementation of the OpenGL ES graphics pipeline.</li> 720d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly <li><strong>Device Compatibility</strong> - Developers should consider the types of devices, 721b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Android versions and the OpenGL ES versions available to their customers. For more information 722b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez on OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and 723b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Device Compatibility</a> section.</li> 7240664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez <li><strong>Coding Convenience</strong> - The OpenGL ES 1.0/1.1 API provides a fixed function 725b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez pipeline and convenience functions which are not available in the OpenGL ES 2.0 or 3.0 APIs. 726b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez Developers who are new to OpenGL ES may find coding for version 1.0/1.1 faster and more 727b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez convenient.</li> 728b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 and 3.0 APIs provide a higher degree 729b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez of control by providing a fully programmable pipeline through the use of shaders. With more 730b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez direct control of the graphics processing pipeline, developers can create effects that would be 731b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez very difficult to generate using the 1.0/1.1 API.</li> 732b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez <li><strong>Texture Support</strong> - The OpenGL ES 3.0 API has the best support for texture 733b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez compression because it guarantees availability of the ETC2 compression format, which supports 734b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez transparency. The 1.x and 2.0 API implementations usually include support for ETC1, however 735b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez this texture format does not support transparency and so you must typically provide resources 736b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez in other compression formats supported by the devices you are targeting. For more information, 737b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez see <a href="#textures">Texture compression support</a>.</li> 7380664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez</ul> 739d2a4e69f3dffb85c256629f5ee9005d8b9d8ac03Robert Ly 7400664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandez<p>While performance, compatibility, convenience, control and other factors may influence your 7410664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezdecision, you should pick an OpenGL API version based on what you think provides the best experience 7420664a8f661e15991e20cab1c0daa41f5e21977abJoe Fernandezfor your users.</p> 743b5c29e75a078f628f8a43a6ca9174fe78d738810Joe Fernandez 744