Home | History | Annotate | Download | only in graphics
      1 page.title=OpenGL ES
      2 page.tags=games
      3 @jd:body
      4 
      5 <div id="qv-wrapper">
      6   <div id="qv">
      7     <h2>In this document</h2>
      8 
      9     <ol>
     10       <li><a href="#basics">The Basics</a>
     11         <ol>
     12           <li><a href="#packages">OpenGL ES packages</a></li>
     13         </ol>
     14       <li><a href="#manifest">Declaring OpenGL Requirements</a></li>
     15       <li><a href="#coordinate-mapping">Mapping Coordinates for Drawn Objects</a>
     16         <ol>
     17           <li><a href="#proj-es1">Projection and camera in ES 1.0</a></li>
     18           <li><a href="#proj-es2">Projection and camera in ES 2.0 and higher</a></li>
     19         </ol>
     20       </li>
     21       <li><a href="#faces-winding">Shape Faces and Winding</a></li>
     22       <li><a href="#compatibility">OpenGL Versions and Device Compatibility</a>
     23         <ol>
     24           <li><a href="#textures">Texture compression support</a></li>
     25           <li><a href="#gl-extension-query">Determining OpenGL extensions</a></li>
     26           <li><a href="#version-check">Checking OpenGL ES Version</a></li>
     27         </ol>
     28       </li>
     29       <li><a href="#choosing-version">Choosing an OpenGL API Version</a></li>
     30     </ol>
     31     <h2>Key classes</h2>
     32     <ol>
     33       <li>{@link android.opengl.GLSurfaceView}</li>
     34       <li>{@link android.opengl.GLSurfaceView.Renderer}</li>
     35     </ol>
     36     <h2>See also</h2>
     37     <ol>
     38       <li><a href="{@docRoot}training/graphics/opengl/index.html">
     39           Displaying Graphics with OpenGL ES</a></li>
     40       <li><a href="http://www.khronos.org/opengles/">OpenGL ES</a></li>
     41       <li><a href="http://www.khronos.org/opengles/1_X/">OpenGL ES 1.x Specification</a></li>
     42       <li><a href="http://www.khronos.org/opengles/2_X/">OpenGL ES 2.x specification</a></li>
     43       <li><a href="http://www.khronos.org/opengles/3_X/">OpenGL ES 3.x specification</a></li>
     44     </ol>
     45   </div>
     46 </div>
     47 
     48 <p>Android includes support for high performance 2D and 3D graphics with the Open Graphics Library
     49 (OpenGL&reg;), specifically, the OpenGL ES API. OpenGL is a cross-platform graphics API that
     50 specifies a
     51 standard software interface for 3D graphics processing hardware. OpenGL ES is a flavor of the OpenGL
     52 specification intended for embedded devices. Android supports several versions of the OpenGL ES
     53 API:</p>
     54 
     55 <ul>
     56   <li>OpenGL ES 1.0 and 1.1 - This API specification is supported by Android 1.0 and higher.</li>
     57   <li>OpenGL ES 2.0 - This API specification is supported by Android 2.2 (API level 8) and higher.
     58     </li>
     59   <li>OpenGL ES 3.0 - This API specification is supported by Android 4.3 (API level 18) and higher.
     60     </li>
     61   <li>OpenGL ES 3.1 - This API specification is supported by Android 5.0 (API level 21) and higher.
     62     </li>
     63 </ul>
     64 
     65 <p class="caution"><strong>Caution:</strong>
     66   Support of the OpenGL ES 3.0 API on a device requires an implementation of this graphics
     67   pipeline provided by the device manufacturer. A device running Android 4.3 or higher <em>may
     68   not support</em> the OpenGL ES 3.0 API. For information on checking what version of OpenGL ES
     69   is supported at run time, see <a href="#version-check">Checking OpenGL ES Version</a>.
     70 </p>
     71 
     72 <p class="note"><strong>Note:</strong>
     73   The specific API provided by the Android framework is similar to the J2ME JSR239 OpenGL ES API,
     74   but is not identical. If you are familiar with J2ME JSR239 specification, be alert for
     75   variations.</p>
     76 
     77 
     78 
     79 <h2 id="basics">The Basics</h2>
     80 
     81 <p>Android supports OpenGL both through its framework API and the Native Development
     82 Kit (NDK). This topic focuses on the Android framework interfaces. For more information about the
     83 NDK, see the <a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK</a>.
     84 
     85 <p>There are two foundational classes in the Android framework that let you create and manipulate
     86 graphics with the OpenGL ES API: {@link android.opengl.GLSurfaceView} and {@link
     87 android.opengl.GLSurfaceView.Renderer}. If your goal is to use OpenGL in your Android application,
     88 understanding how to implement these classes in an activity should be your first objective.
     89 </p>
     90 
     91 <dl>
     92   <dt><strong>{@link android.opengl.GLSurfaceView}</strong></dt>
     93   <dd>This class is a {@link android.view.View} where you can draw and manipulate objects using
     94     OpenGL API calls and is similar in function to a {@link android.view.SurfaceView}. You can use
     95     this class by creating an instance of {@link android.opengl.GLSurfaceView} and adding your
     96     {@link android.opengl.GLSurfaceView.Renderer Renderer} to it. However, if you want to capture
     97     touch screen events, you should extend the {@link android.opengl.GLSurfaceView} class to
     98     implement the touch listeners, as shown in OpenGL training lesson,
     99     <a href="{@docRoot}training/graphics/opengl/touch.html">Responding to Touch Events</a>.</dd>
    100 
    101   <dt><strong>{@link android.opengl.GLSurfaceView.Renderer}</strong></dt>
    102   <dd>This interface defines the methods required for drawing graphics in a {@link
    103     android.opengl.GLSurfaceView}. You must provide an implementation of this interface as a
    104     separate class and attach it to your {@link android.opengl.GLSurfaceView} instance using
    105     {@link android.opengl.GLSurfaceView#setRenderer(android.opengl.GLSurfaceView.Renderer)
    106     GLSurfaceView.setRenderer()}.
    107 
    108     <p>The {@link android.opengl.GLSurfaceView.Renderer} interface requires that you implement the
    109       following methods:</p>
    110     <ul>
    111       <li>
    112         {@link
    113     android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10,
    114     javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()}: The system calls this
    115     method once, when creating the {@link android.opengl.GLSurfaceView}. Use this method to perform
    116     actions that need to happen only once, such as setting OpenGL environment parameters or
    117     initializing OpenGL graphic objects.
    118       </li>
    119       <li>
    120         {@link
    121         android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)
    122         onDrawFrame()}: The system calls this method on each redraw of the {@link
    123         android.opengl.GLSurfaceView}. Use this method as the primary execution point for
    124         drawing (and re-drawing) graphic objects.</li>
    125       <li>
    126         {@link
    127     android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10,
    128     int, int) onSurfaceChanged()}: The system calls this method when the {@link
    129     android.opengl.GLSurfaceView} geometry changes, including changes in size of the {@link
    130     android.opengl.GLSurfaceView} or orientation of the device screen. For example, the system calls
    131     this method when the device changes from portrait to landscape orientation. Use this method to
    132     respond to changes in the {@link android.opengl.GLSurfaceView} container.
    133       </li>
    134     </ul>
    135     </dd>
    136 </dl>
    137 
    138 <h3 id="packages">OpenGL ES packages</h3>
    139 <p>Once you have established a container view for OpenGL ES using {@link
    140 android.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer}, you can begin
    141 calling OpenGL APIs using the following classes:</p>
    142 
    143 <ul>
    144   <li>OpenGL ES 1.0/1.1 API Packages
    145     <ul>
    146       <li>{@link android.opengl} - This package provides a static interface to the OpenGL ES
    147         1.0/1.1 classes and better performance than the {@code javax.microedition.khronos} package
    148         interfaces.
    149         <ul>
    150           <li>{@link android.opengl.GLES10}</li>
    151           <li>{@link android.opengl.GLES10Ext}</li>
    152           <li>{@link android.opengl.GLES11}</li>
    153           <li>{@link android.opengl.GLES11Ext}</li>
    154         </ul>
    155       </li>
    156       <li>{@link javax.microedition.khronos.opengles} - This package provides the standard
    157         implementation of OpenGL ES 1.0/1.1.
    158         <ul>
    159           <li>{@link javax.microedition.khronos.opengles.GL10}</li>
    160           <li>{@link javax.microedition.khronos.opengles.GL10Ext}</li>
    161           <li>{@link javax.microedition.khronos.opengles.GL11}</li>
    162           <li>{@link javax.microedition.khronos.opengles.GL11Ext}</li>
    163           <li>{@link javax.microedition.khronos.opengles.GL11ExtensionPack}</li>
    164         </ul>
    165         </li>
    166       </ul>
    167   </li>
    168   <li>OpenGL ES 2.0 API Class
    169     <ul>
    170       <li>{@link android.opengl.GLES20 android.opengl.GLES20} - This package provides the
    171         interface to OpenGL ES 2.0 and is available starting with Android 2.2 (API level 8).</li>
    172     </ul>
    173   </li>
    174   </li>
    175   <li>OpenGL ES 3.0/3.1 API Packages
    176     <ul>
    177       <li>{@link android.opengl} - This package provides the interface to the OpenGL ES 3.0/3.1
    178 classes.
    179       Version 3.0 is available starting with Android 4.3 (API level 18). Version 3.1 is available
    180 starting with Android 5.0 (API level 21).
    181       <ul>
    182       <li>{@link android.opengl.GLES30}</li>
    183       <li>{@link android.opengl.GLES31} </li>
    184       <li>{@link android.opengl.GLES31Ext} (<a href="#aep">Android Extension Pack</a>)</li>
    185       </ul>
    186     </ul>
    187   </li>
    188 </ul>
    189 
    190 <p>If you want to start building an app with OpenGL ES right away, follow the
    191 <a href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a>
    192 class.
    193 </p>
    194 
    195 <h2 id="manifest">Declaring OpenGL Requirements</h2>
    196 <p>If your application uses OpenGL features that are not available on all devices, you must include
    197 these requirements in your <a
    198 href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file.
    199 Here are the most common OpenGL manifest declarations:</p>
    200 
    201 <ul>
    202   <li><strong>OpenGL ES version requirements</strong> - If your application requires a specific
    203 version of
    204   OpenGL ES, you must declare that requirement by adding the following settings to your manifest as
    205 shown below.</li>
    206 
    207 <p>For OpenGL ES 2.0:</p>
    208 
    209 <pre>
    210 &lt;!-- Tell the system this app requires OpenGL ES 2.0. --&gt;
    211 &lt;uses-feature android:glEsVersion="0x00020000" android:required="true" /&gt;
    212 </pre>
    213 
    214     <p>Adding this declaration causes Google Play to restrict your application from being
    215     installed on devices that do not support OpenGL ES 2.0. If your application is exclusively for
    216     devices that support OpenGL ES 3.0, you can also specify this in your manifest:</p>
    217 
    218 <p>For OpenGL ES 3.0:</p>
    219 
    220 <pre>
    221 &lt;!-- Tell the system this app requires OpenGL ES 3.0. --&gt;
    222 &lt;uses-feature android:glEsVersion="0x00030000" android:required="true" /&gt;
    223 </pre>
    224 
    225 <p>For OpenGL ES 3.1:</p>
    226 
    227 <pre>
    228 &lt;!-- Tell the system this app requires OpenGL ES 3.1. --&gt;
    229 &lt;uses-feature android:glEsVersion="0x00030001" android:required="true" /&gt;
    230 </pre>
    231 
    232     <p class="note"><strong>Note:</strong>
    233       The OpenGL ES 3.x API is backwards-compatible with the 2.0 API, which means you can be more
    234       flexible with your implementation of OpenGL ES in your application. By declaring the OpenGL
    235       ES 2.0 API as a requirement in your manifest, you can use that API version as a default, check
    236       for the availability of the 3.x API at run time and then use OpenGL ES 3.x features if the
    237       device supports it. For more information about checking the OpenGL ES version supported by a
    238       device, see <a href="#version-check">Checking OpenGL ES Version</a>.
    239     </p>
    240 
    241   </li>
    242   <li><strong>Texture compression requirements</strong> - If your application uses texture
    243 compression formats, you must declare the formats your application supports in your manifest file
    244 using <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code
    245 <supports-gl-texture>}</a>. For more information about available texture compression
    246 formats, see <a href="#textures">Texture compression support</a>.
    247 
    248 <p>Declaring texture compression requirements in your manifest hides your application from users
    249 with devices that do not support at least one of your declared compression types. For more
    250 information on how Google Play filtering works for texture compressions, see the <a
    251 href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering">
    252 Google Play and texture compression filtering</a> section of the {@code
    253 <supports-gl-texture>} documentation.</p>
    254   </li>
    255 </ul>
    256 
    257 
    258 <h2 id="coordinate-mapping">Mapping Coordinates for Drawn Objects</h2>
    259 
    260 <p>One of the basic problems in displaying graphics on Android devices is that their screens can
    261 vary in size and shape. OpenGL assumes a square, uniform coordinate system and, by default, happily
    262 draws those coordinates onto your typically non-square screen as if it is perfectly square.</p>
    263 
    264 <img src="{@docRoot}images/opengl/coordinates.png">
    265 <p class="img-caption">
    266   <strong>Figure 1.</strong> Default OpenGL coordinate system (left) mapped to a typical Android
    267 device screen (right).
    268 </p>
    269 
    270 <p>The illustration above shows the uniform coordinate system assumed for an OpenGL frame on the
    271 left, and how these coordinates actually map to a typical device screen in landscape orientation
    272 on the right. To solve this problem, you can apply OpenGL projection modes and camera views to
    273 transform coordinates so your graphic objects have the correct proportions on any display.</p>
    274 
    275 <p>In order to apply projection and camera views, you create a projection matrix and a camera view
    276 matrix and apply them to the OpenGL rendering pipeline. The projection matrix recalculates the
    277 coordinates of your graphics so that they map correctly to Android device screens. The camera view
    278 matrix creates a transformation that renders objects from a specific eye position.</p>
    279 
    280 
    281 <h3 id="proj-es1">Projection and camera view in OpenGL ES 1.0</h3>
    282 <p>In the ES 1.0 API, you apply projection and camera view by creating each matrix and then
    283 adding them to the OpenGL environment.</p>
    284 
    285 <ol>
    286 <li><strong>Projection matrix</strong> - Create a projection matrix using the geometry of the
    287 device screen in order to recalculate object coordinates so they are drawn with correct proportions.
    288 The following example code demonstrates how to modify the {@link
    289 android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.microedition.khronos.opengles.GL10,
    290 int, int) onSurfaceChanged()} method of a {@link android.opengl.GLSurfaceView.Renderer}
    291 implementation to create a projection matrix based on the screen's aspect ratio and apply it to the
    292 OpenGL rendering environment.
    293 
    294 <pre>
    295 public void onSurfaceChanged(GL10 gl, int width, int height) {
    296     gl.glViewport(0, 0, width, height);
    297 
    298     // make adjustments for screen ratio
    299     float ratio = (float) width / height;
    300     gl.glMatrixMode(GL10.GL_PROJECTION);        // set matrix to projection mode
    301     gl.glLoadIdentity();                        // reset the matrix to its default state
    302     gl.glFrustumf(-ratio, ratio, -1, 1, 3, 7);  // apply the projection matrix
    303 }
    304 </pre>
    305 </li>
    306 
    307 <li><strong>Camera transformation matrix</strong> - Once you have adjusted the coordinate system
    308 using a projection matrix, you must also apply a camera view. The following example code shows how
    309 to modify the {@link
    310 android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)
    311 onDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer}
    312 implementation to apply a model view and use the
    313 {@link android.opengl.GLU#gluLookAt(javax.microedition.khronos.opengles.GL10, float, float, float,
    314 float, float, float, float, float, float) GLU.gluLookAt()} utility to create a viewing tranformation
    315 which simulates a camera position.
    316 
    317 <pre>
    318 public void onDrawFrame(GL10 gl) {
    319     ...
    320     // Set GL_MODELVIEW transformation mode
    321     gl.glMatrixMode(GL10.GL_MODELVIEW);
    322     gl.glLoadIdentity();                      // reset the matrix to its default state
    323 
    324     // When using GL_MODELVIEW, you must set the camera view
    325     GLU.gluLookAt(gl, 0, 0, -5, 0f, 0f, 0f, 0f, 1.0f, 0.0f);
    326     ...
    327 }
    328 </pre>
    329 </li>
    330 </ol>
    331 
    332 
    333 <h3 id="proj-es2">Projection and camera view in OpenGL ES 2.0 and higher</h3>
    334 
    335 <p>In the ES 2.0 and 3.0 APIs, you apply projection and camera view by first adding a matrix member
    336 to the vertex shaders of your graphics objects. With this matrix member added, you can then
    337 generate and apply projection and camera viewing matrices to your objects.</p>
    338 
    339 <ol>
    340 <li><strong>Add matrix to vertex shaders</strong> - Create a variable for the view projection matrix
    341 and include it as a multiplier of the shader's position. In the following example vertex shader
    342 code, the included {@code uMVPMatrix} member allows you to apply projection and camera viewing
    343 matrices to the coordinates of objects that use this shader.
    344 
    345 <pre>
    346 private final String vertexShaderCode =
    347 
    348     // This matrix member variable provides a hook to manipulate
    349     // the coordinates of objects that use this vertex shader.
    350     "uniform mat4 uMVPMatrix;   \n" +
    351 
    352     "attribute vec4 vPosition;  \n" +
    353     "void main(){               \n" +
    354     // The matrix must be included as part of gl_Position
    355     // Note that the uMVPMatrix factor *must be first* in order
    356     // for the matrix multiplication product to be correct.
    357     " gl_Position = uMVPMatrix * vPosition; \n" +
    358 
    359     "}  \n";
    360 </pre>
    361   <p class="note"><strong>Note:</strong> The example above defines a single transformation matrix
    362 member in the vertex shader into which you apply a combined projection matrix and camera view
    363 matrix. Depending on your application requirements, you may want to define separate projection
    364 matrix and camera viewing matrix members in your vertex shaders so you can change them
    365 independently.</p>
    366 </li>
    367 <li><strong>Access the shader matrix</strong> - After creating a hook in your vertex shaders to
    368 apply projection and camera view, you can then access that variable to apply projection and
    369 camera viewing matrices. The following code shows how to modify the {@link
    370 android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.microedition.khronos.opengles.GL10,
    371 javax.microedition.khronos.egl.EGLConfig) onSurfaceCreated()} method of a {@link
    372 android.opengl.GLSurfaceView.Renderer} implementation to access the matrix
    373 variable defined in the vertex shader above.
    374 
    375 <pre>
    376 public void onSurfaceCreated(GL10 unused, EGLConfig config) {
    377     ...
    378     muMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix");
    379     ...
    380 }
    381 </pre>
    382 </li>
    383 <li><strong>Create projection and camera viewing matrices</strong> - Generate the projection and
    384 viewing matrices to be applied the graphic objects. The following example code shows how to modify
    385 the {@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} and
    386 {@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} methods of a
    387 {@link android.opengl.GLSurfaceView.Renderer} implementation to create camera view matrix and a
    388 projection matrix based on the screen aspect ratio of the device.
    389 
    390 <pre>
    391 public void onSurfaceCreated(GL10 unused, EGLConfig config) {
    392     ...
    393     // Create a camera view matrix
    394     Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f);
    395 }
    396 
    397 public void onSurfaceChanged(GL10 unused, int width, int height) {
    398     GLES20.glViewport(0, 0, width, height);
    399 
    400     float ratio = (float) width / height;
    401 
    402     // create a projection matrix from device screen geometry
    403     Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7);
    404 }
    405 </pre>
    406 </li>
    407 
    408 <li><strong>Apply projection and camera viewing matrices</strong> - To apply the projection and
    409 camera view transformations, multiply the matrices together and then set them into the vertex
    410 shader. The following example code shows how modify the {@link
    411 android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)
    412 onDrawFrame()} method of a {@link android.opengl.GLSurfaceView.Renderer} implementation to combine
    413 the projection matrix and camera view created in the code above and then apply it to the graphic
    414 objects to be rendered by OpenGL.
    415 
    416 <pre>
    417 public void onDrawFrame(GL10 unused) {
    418     ...
    419     // Combine the projection and camera view matrices
    420     Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0);
    421 
    422     // Apply the combined projection and camera view transformations
    423     GLES20.glUniformMatrix4fv(muMVPMatrixHandle, 1, false, mMVPMatrix, 0);
    424 
    425     // Draw objects
    426     ...
    427 }
    428 </pre>
    429 </li>
    430 </ol>
    431 <p>For a complete example of how to apply projection and camera view with OpenGL ES 2.0, see the <a
    432 href="{@docRoot}training/graphics/opengl/index.html">Displaying Graphics with OpenGL ES</a>
    433 class.</p>
    434 
    435 
    436 <h2 id="faces-winding">Shape Faces and Winding</h2>
    437 
    438 <p>In OpenGL, the face of a shape is a surface defined by three or more points in three-dimensional
    439 space. A set of three or more three-dimensional points (called vertices in OpenGL) have a front face
    440 and a back face. How do you know which face is front and which is the back? Good question. The
    441 answer has to do with winding, or, the direction in which you define the points of a shape.</p>
    442 
    443 <img src="{@docRoot}images/opengl/ccw-winding.png">
    444 <p class="img-caption">
    445   <strong>Figure 1.</strong> Illustration of a coordinate list which translates into a
    446 counterclockwise drawing order.</p>
    447 
    448 <p>In this example, the points of the triangle are defined in an order such that they are drawn in a
    449 counterclockwise direction. The order in which these coordinates are drawn defines the winding
    450 direction for the shape. By default, in OpenGL, the face which is drawn counterclockwise is the
    451 front face. The triangle shown in Figure 1 is defined so that you are looking at the front face of
    452 the shape (as interpreted by OpenGL) and the other side is the back face.</p>
    453 
    454 <p>Why is it important to know which face of a shape is the front face? The answer has to do with a
    455 commonly used feature of OpenGL, called face culling. Face culling is an option for the OpenGL
    456 environment which allows the rendering pipeline to ignore (not calculate or draw) the back face of a
    457 shape, saving time, memory and processing cycles:</p>
    458 
    459 <pre>
    460 // enable face culling feature
    461 gl.glEnable(GL10.GL_CULL_FACE);
    462 // specify which faces to not draw
    463 gl.glCullFace(GL10.GL_BACK);
    464 </pre>
    465 
    466 <p>If you try to use the face culling feature without knowing which sides of your shapes are the
    467 front and back, your OpenGL graphics are going to look a bit thin, or possibly not show up at all.
    468 So, always define the coordinates of your OpenGL shapes in a counterclockwise drawing order.</p>
    469 
    470 <p class="note"><strong>Note:</strong> It is possible to set an OpenGL environment to treat the
    471 clockwise face as the front face, but doing so requires more code and is likely to confuse
    472 experienced OpenGL developers when you ask them for help. So dont do that.</p>
    473 
    474 
    475 <h2 id="compatibility">OpenGL Versions and Device Compatibility</h2>
    476 
    477 <p>The OpenGL ES 1.0 and 1.1 API specifications have been supported since Android 1.0.
    478 Beginning with Android 2.2 (API level 8), the framework supports the OpenGL ES 2.0 API
    479 specification. OpenGL ES 2.0 is supported by most Android devices and is recommended for new
    480 applications being developed with OpenGL. OpenGL ES 3.0 is supported with Android 4.3
    481 (API level 18) and higher, on devices that provide an implementation of the OpenGL ES 3.0 API.
    482 For information about the relative number of Android-powered devices
    483 that support a given version of OpenGL ES, see the
    484 <a href="{@docRoot}about/dashboards/index.html#OpenGL">OpenGL ES Version Dashboard</a>.</p>
    485 
    486 <p>Graphics programming with OpenGL ES 1.0/1.1 API is significantly different than using the 2.0
    487 and higher versions. The 1.x version of the API has more convenience methods and a fixed graphics
    488 pipeline, while the OpenGL ES 2.0 and 3.0 APIs provide more direct control of the pipeline through
    489 use of OpenGL shaders. You should carefully consider the graphics requirements and choose the API
    490 version that works best for your application. For more information, see
    491 <a href="#choosing-version">Choosing an OpenGL API Version</a>.</p>
    492 
    493 <p>The OpenGL ES 3.0 API provides additional features and better performance than the 2.0 API and is
    494 also backward compatible. This means that you can potentially write your application targeting
    495 OpenGL ES 2.0 and conditionally include OpenGL ES 3.0 graphics features if they are available. For
    496 more information on checking for availability of the 3.0 API, see
    497 <a href="#version-check">Checking OpenGL ES Version</a></p>
    498 
    499 
    500 <h3 id="textures">Texture compression support</h3>
    501 
    502 <p>Texture compression can significantly increase the performance of your OpenGL application by
    503 reducing memory requirements and making more efficient use of memory bandwidth. The Android
    504 framework provides support for the ETC1 compression format as a standard feature, including a {@link
    505 android.opengl.ETC1Util} utility class and the {@code etc1tool} compression tool (located in the
    506 Android SDK at {@code <sdk>/tools/}). For an example of an Android application that uses
    507 texture compression, see the {@code CompressedTextureActivity} code sample in Android SDK
    508 ({@code <sdk>/samples/<version>/ApiDemos/src/com/example/android/apis/graphics/}).</p>
    509 
    510 <p class="caution"><strong>Caution:</strong> The ETC1 format is supported by most Android devices,
    511 but it not guaranteed to be available. To check if the ETC1 format is supported on a device, call
    512 the {@link android.opengl.ETC1Util#isETC1Supported() ETC1Util.isETC1Supported()} method.</p>
    513 
    514 <p class="note"><b>Note:</b> The ETC1 texture compression format does not support textures with an
    515 transparency (alpha channel). If your application requires textures with transparency, you should
    516 investigate other texture compression formats available on your target devices.</p>
    517 
    518 <p>The ETC2/EAC texture compression formats are guaranteed to be available when using the OpenGL ES
    519 3.0 API. This texture format offers excellent compression ratios with high visual quality and the
    520 format also supports transparency (alpha channel).</p>
    521 
    522 <p>Beyond the ETC formats, Android devices have varied support for texture compression based on
    523 their GPU chipsets and OpenGL implementations. You should investigate texture compression support on
    524 the devices you are are targeting to determine what compression types your application should
    525 support. In order to determine what texture formats are supported on a given device, you must <a
    526 href="#gl-extension-query">query the device</a> and review the <em>OpenGL extension names</em>,
    527 which identify what texture compression formats (and other OpenGL features) are supported by the
    528 device. Some commonly supported texture compression formats are as follows:</p>
    529 
    530 <ul>
    531   <li><strong>ATITC (ATC)</strong> - ATI texture compression (ATITC or ATC) is available on a
    532 wide variety of devices and supports fixed rate compression for RGB textures with and without
    533 an alpha channel. This format may be represented by several OpenGL extension names, for example:
    534     <ul>
    535       <li>{@code GL_AMD_compressed_ATC_texture}</li>
    536       <li>{@code GL_ATI_texture_compression_atitc}</li>
    537     </ul>
    538   </li>
    539   <li><strong>PVRTC</strong> - PowerVR texture compression (PVRTC) is available on a wide
    540 variety of devices and supports 2-bit and 4-bit per pixel textures with or without an alpha channel.
    541 This format is represented by the following OpenGL extension name:
    542     <ul>
    543       <li>{@code GL_IMG_texture_compression_pvrtc}</li>
    544     </ul>
    545   </li>
    546   <li><strong>S3TC (DXT<em>n</em>/DXTC)</strong> - S3 texture compression (S3TC) has several
    547 format variations (DXT1 to DXT5) and is less widely available. The format supports RGB textures with
    548 4-bit alpha or 8-bit alpha channels. These formats are represented by the following OpenGL extension
    549 name:
    550     <ul>
    551       <li>{@code GL_EXT_texture_compression_s3tc}</li>
    552     </ul>
    553     Some devices only support the DXT1 format variation; this limited support is represented by the
    554 following OpenGL extension name:
    555     <ul>
    556       <li>{@code GL_EXT_texture_compression_dxt1}</li>
    557     </ul>
    558   </li>
    559   <li><strong>3DC</strong> - 3DC texture compression (3DC) is a less widely available format that
    560 supports RGB textures with an alpha channel. This format is represented by the following OpenGL
    561 extension name:
    562     <ul>
    563       <li>{@code GL_AMD_compressed_3DC_texture}</li>
    564     </ul>
    565   </li>
    566 </ul>
    567 
    568 <p class="warning"><strong>Warning:</strong> These texture compression formats are <em>not
    569 supported</em> on all devices. Support for these formats can vary by manufacturer and device. For
    570 information on how to determine what texture compression formats are on a particular device, see
    571 the next section.
    572 </p>
    573 
    574 <p class="note"><strong>Note:</strong> Once you decide which texture compression formats your
    575 application will support, make sure you declare them in your manifest using <a
    576 href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;
    577 </a>. Using this declaration enables filtering by external services such as Google Play, so that
    578 your app is installed only on devices that support the formats your app requires. For details, see
    579 <a
    580 href="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p>
    581 
    582 
    583 <h3 id="gl-extension-query">Determining OpenGL extensions</h3>
    584 <p>Implementations of OpenGL vary by Android device in terms of the extensions to the OpenGL ES API
    585 that are supported. These extensions include texture compressions, but typically also include other
    586 extensions to the OpenGL feature set.</p>
    587 
    588 <p>To determine what texture compression formats, and other OpenGL extensions, are supported on a
    589 particular device:</p>
    590 <ol>
    591   <li>Run the following code on your target devices to determine what texture compression
    592 formats are supported:
    593 <pre>
    594 String extensions = javax.microedition.khronos.opengles.GL10.glGetString(
    595         GL10.GL_EXTENSIONS);
    596 </pre>
    597   <p class="warning"><b>Warning:</b> The results of this call <em>vary by device model!</em> You
    598 must run this call on several target devices to determine what compression types are commonly
    599 supported.</p>
    600   </li>
    601   <li>Review the output of this method to determine what OpenGL extensions are supported on the
    602 device.</li>
    603 </ol>
    604 
    605 <h4 id="aep">Android Extension Pack (AEP)</h4>
    606 
    607 <p> The AEP ensures that your application supports a standardized set of OpenGL extensions above
    608 and beyond
    609 the core set described in the OpenGL 3.1 specification. Packaging these extensions together
    610 encourages a consistent set of functionality across devices, while allowing developers to take full
    611 advantage of the latest crop of mobile GPU devices.</p>
    612 
    613 <p>The AEP also improves support for images, shader storage buffers, and atomic counters in
    614 fragment shaders.</p>
    615 
    616 <p>For your app to be able to use the AEP, the app's manifest must declare that the AEP is required.
    617 In addition, the platform version must support it. </p>
    618 
    619 <p>Declare the AEP requirement in the manifest as follows:</p>
    620 
    621 <pre>
    622 &lt;uses feature android:name="android.hardware.opengles.aep"
    623               android:required="true" /&gt;
    624 </pre>
    625 
    626 <p>To verify that the platform version supports the AEP, use the
    627 {@link android.content.pm.PackageManager#hasSystemFeature} method, passing in
    628 {@link android.content.pm.PackageManager#FEATURE_OPENGLES_EXTENSION_PACK} as the argument. The following code snippet
    629 shows an example of how to do so:</p>
    630 
    631 <pre>
    632 boolean deviceSupportsAEP = getPackageManager().hasSystemFeature
    633      (PackageManager.FEATURE_OPENGLES_EXTENSION_PACK);
    634 </pre>
    635 
    636 <p>If the method returns true, AEP is supported.<p>
    637 
    638 <p>For more information about the AEP, visit its page at the <a
    639 href="https://www.khronos.org/registry/gles/extensions/ANDROID/ANDROID_extension_pack_es31a.txt">
    640 Khronos OpenGL ES Registry</a>.
    641 
    642 
    643 <h3 id="version-check">Checking the OpenGL ES Version</h3>
    644 
    645 <p>There are several versions of OpenGL ES available on Android devices. You can specify the
    646 minimum version of the API your application requires in your <a href="#manifest">manifest</a>, but
    647 you may also want to take advantage of features in a newer API at the same time. For example,
    648 the OpenGL ES 3.0 API is backward-compatible with the 2.0 version of the API, so you may want to
    649 write your application so that it uses OpenGL ES 3.0 features, but falls back to the 2.0 API if the
    650 3.0 API is not available.</p>
    651 
    652 <p>Before using OpenGL ES features from a version higher than the minimum required in your
    653 application manifest, your application should check the version of the API available on the device.
    654 You can do this in one of two ways:</p>
    655 
    656 <ol>
    657   <li>Attempt to create the higher-level OpenGL ES context ({@link android.opengl.EGLContext}) and
    658     check the result.</li>
    659   <li>Create a minimum-supported OpenGL ES context and check the version value.</li>
    660 </ol>
    661 
    662 <p>The following example code demonstrates how to check the available OpenGL ES version by creating
    663 an {@link android.opengl.EGLContext} and checking the result. This example shows how to check for
    664 OpenGL ES 3.0 version:</p>
    665 
    666 <pre>
    667 private static double glVersion = 3.0;
    668 
    669 private static class ContextFactory implements GLSurfaceView.EGLContextFactory {
    670 
    671   private static int EGL_CONTEXT_CLIENT_VERSION = 0x3098;
    672 
    673   public EGLContext createContext(
    674           EGL10 egl, EGLDisplay display, EGLConfig eglConfig) {
    675 
    676       Log.w(TAG, "creating OpenGL ES " + glVersion + " context");
    677       int[] attrib_list = {EGL_CONTEXT_CLIENT_VERSION, (int) glVersion,
    678               EGL10.EGL_NONE };
    679       // attempt to create a OpenGL ES 3.0 context
    680       EGLContext context = egl.eglCreateContext(
    681               display, eglConfig, EGL10.EGL_NO_CONTEXT, attrib_list);
    682       return context; // returns null if 3.0 is not supported;
    683   }
    684 }
    685 </pre>
    686 
    687 <p>If the {@code createContext()} method show above returns null, your code should create a OpenGL
    688 ES 2.0 context instead and fall back to using only that API.</p>
    689 
    690 <p>The following code example demonstrates how to check the OpenGL ES version by creating a minimum
    691 supported context first, and then checking the version string:</p>
    692 
    693 <pre>
    694 // Create a minimum supported OpenGL ES context, then check:
    695 String version = javax.microedition.khronos.opengles.GL10.glGetString(
    696         GL10.GL_VERSION);
    697 Log.w(TAG, "Version: " + version );
    698 // The version format is displayed as: "OpenGL ES &lt;major&gt;.&lt;minor&gt;"
    699 // followed by optional content provided by the implementation.
    700 </pre>
    701 
    702 <p>With this approach, if you discover that the device supports a higher-level API version, you
    703 must destroy the minimum OpenGL ES context and create a new context with the higher
    704 available API version.</p>
    705 
    706 
    707 <h2 id="choosing-version">Choosing an OpenGL API Version</h2>
    708 
    709 <p>OpenGL ES 1.0 API version (and the 1.1 extensions), version 2.0, and version 3.0 all provide high
    710 performance graphics interfaces for creating 3D games, visualizations and user interfaces. Graphics
    711 progamming for OpenGL ES 2.0 and 3.0 is largely similar, with version 3.0 representing a superset
    712 of the 2.0 API with additional features. Programming for the OpenGL ES 1.0/1.1 API versus OpenGL ES
    713 2.0 and 3.0 differs significantly, and so developers should carefully consider the following
    714 factors before starting development with these APIs:</p>
    715 
    716 <ul>
    717   <li><strong>Performance</strong> - In general, OpenGL ES 2.0 and 3.0 provide faster graphics
    718     performance than the ES 1.0/1.1 APIs. However, the performance difference can vary depending on
    719     the Android device your OpenGL application is running on, due to differences in hardware
    720     manufacturer's implementation of the OpenGL ES graphics pipeline.</li>
    721   <li><strong>Device Compatibility</strong> - Developers should consider the types of devices,
    722     Android versions and the OpenGL ES versions available to their customers. For more information
    723     on OpenGL compatibility across devices, see the <a href="#compatibility">OpenGL Versions and
    724     Device Compatibility</a> section.</li>
    725   <li><strong>Coding Convenience</strong> - The OpenGL ES 1.0/1.1 API provides a fixed function
    726     pipeline and convenience functions which are not available in the OpenGL ES 2.0 or 3.0 APIs.
    727     Developers who are new to OpenGL ES may find coding for version 1.0/1.1 faster and more
    728     convenient.</li>
    729   <li><strong>Graphics Control</strong> - The OpenGL ES 2.0 and 3.0 APIs provide a higher degree
    730     of control by providing a fully programmable pipeline through the use of shaders. With more
    731     direct control of the graphics processing pipeline, developers can create effects that would be
    732     very difficult to generate using the 1.0/1.1 API.</li>
    733   <li><strong>Texture Support</strong> - The OpenGL ES 3.0 API has the best support for texture
    734     compression because it guarantees availability of the ETC2 compression format, which supports
    735     transparency. The 1.x and 2.0 API implementations usually include support for ETC1, however
    736     this texture format does not support transparency and so you must typically provide resources
    737     in other compression formats supported by the devices you are targeting. For more information,
    738     see <a href="#textures">Texture compression support</a>.</li>
    739 </ul>
    740 
    741 <p>While performance, compatibility, convenience, control and other factors may influence your
    742 decision, you should pick an OpenGL API version based on what you think provides the best experience
    743 for your users.</p>
    744 
    745