1 page.title=Building an OpenGL ES Environment 2 parent.title=Displaying Graphics with OpenGL ES 3 parent.link=index.html 4 5 trainingnavtop=true 6 previous.title=Displaying Graphics with OpenGL ES 7 previous.link=index.html 8 next.title=Defining Shapes 9 next.link=shapes.html 10 11 @jd:body 12 13 <div id="tb-wrapper"> 14 <div id="tb"> 15 16 <h2>This lesson teaches you to</h2> 17 <ol> 18 <li><a href="#manifest">Declare OpenGL ES Use in the Manifest</a></li> 19 <li><a href="#activity">Create an Activity for OpenGL ES Graphics</a></li> 20 <li><a href="#glsurfaceview">Build a GLSurfaceView Object</a></li> 21 <li><a href="#renderer">Build a Renderer Class</a></li> 22 </ol> 23 24 <h2>You should also read</h2> 25 <ul> 26 <li><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL</a></li> 27 </ul> 28 29 <h2>Try it out</h2> 30 31 <div class="download-box"> 32 <a href="{@docRoot}shareables/training/OpenGLES.zip" 33 class="button">Download the sample</a> 34 <p class="filename">OpenGLES.zip</p> 35 </div> 36 37 </div> 38 </div> 39 40 41 <p>In order to draw graphics with OpenGL ES in your Android application, you must create a 42 view container for them. One of the more straight-forward ways to do this is to implement both a 43 {@link android.opengl.GLSurfaceView} and a {@link android.opengl.GLSurfaceView.Renderer}. A {@link 44 android.opengl.GLSurfaceView} is a view container for graphics drawn with OpenGL and {@link 45 android.opengl.GLSurfaceView.Renderer} controls what is drawn within that view. For more information 46 about these classes, see the <a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES</a> 47 developer guide.</p> 48 49 <p>{@link android.opengl.GLSurfaceView} is just one way to incorporate OpenGL ES graphics into your 50 application. For a full-screen or near-full screen graphics view, it is a reasonable choice. 51 Developers who want to incorporate OpenGL ES graphics in a small portion of their layouts should 52 take a look at {@link android.view.TextureView}. For real, do-it-yourself developers, it is also 53 possible to build up an OpenGL ES view using {@link android.view.SurfaceView}, but this requires 54 writing quite a bit of additional code.</p> 55 56 <p>This lesson explains how to complete a minimal implementation of {@link 57 android.opengl.GLSurfaceView} and {@link android.opengl.GLSurfaceView.Renderer} in a simple 58 application activity.</p> 59 60 61 <h2 id="manifest">Declare OpenGL ES Use in the Manifest</h2> 62 63 <p>In order for your application to use the OpenGL ES 2.0 API, you must add the following 64 declaration to your manifest:</p> 65 66 <pre> 67 <uses-feature android:glEsVersion="0x00020000" android:required="true" /> 68 </pre> 69 70 <p>If your application uses texture compression, you must also declare which compression formats 71 your app supports, so that it is only installed on compatible devices.</p> 72 73 <pre> 74 <supports-gl-texture android:name="GL_OES_compressed_ETC1_RGB8_texture" /> 75 <supports-gl-texture android:name="GL_OES_compressed_paletted_texture" /> 76 </pre> 77 78 <p>For more information about texture compression formats, see the 79 <a href="{@docRoot}guide/topics/graphics/opengl.html#textures">OpenGL</a> developer guide.</p> 80 81 82 <h2 id="activity">Create an Activity for OpenGL ES Graphics</h2> 83 84 <p>Android applications that use OpenGL ES have activities just like any other application that has 85 a user interface. The main difference from other applications is what you put in the layout for your 86 activity. While in many applications you might use {@link android.widget.TextView}, {@link 87 android.widget.Button} and {@link android.widget.ListView}, in an app that uses OpenGL ES, you can 88 also add a {@link android.opengl.GLSurfaceView}.</p> 89 90 <p>The following code example shows a minimal implementation of an activity that uses a 91 {@link android.opengl.GLSurfaceView} as its primary view:</p> 92 93 <pre> 94 public class OpenGLES20Activity extends Activity { 95 96 private GLSurfaceView mGLView; 97 98 @Override 99 public void onCreate(Bundle savedInstanceState) { 100 super.onCreate(savedInstanceState); 101 102 // Create a GLSurfaceView instance and set it 103 // as the ContentView for this Activity. 104 mGLView = new MyGLSurfaceView(this); 105 setContentView(mGLView); 106 } 107 } 108 </pre> 109 110 <p class="note"><strong>Note:</strong> OpenGL ES 2.0 requires Android 2.2 (API Level 8) or higher, 111 so make sure your Android project targets that API or higher.</p> 112 113 114 <h2 id="glsurfaceview">Build a GLSurfaceView Object</h2> 115 116 <p>A {@link android.opengl.GLSurfaceView} is a specialized view where you can draw OpenGL ES 117 graphics. 118 It does not do much by itself. The actual drawing of objects is controlled in the {@link 119 android.opengl.GLSurfaceView.Renderer} that you set on this view. In fact, the code for this object 120 is so thin, you may be tempted to skip extending it and just create an unmodified {@link 121 android.opengl.GLSurfaceView} instance, but dont do that. You need to extend this class in 122 order to capture touch events, which is covered in the <a href="#touch.html">Responding to Touch 123 Events</a> lesson.</p> 124 125 <p>The essential code for a {@link android.opengl.GLSurfaceView} is minimal, so for a quick 126 implementation, it is common to 127 just create an inner class in the activity that uses it:</p> 128 129 <pre> 130 class MyGLSurfaceView extends GLSurfaceView { 131 132 public MyGLSurfaceView(Context context){ 133 super(context); 134 135 // Set the Renderer for drawing on the GLSurfaceView 136 setRenderer(new MyRenderer()); 137 } 138 } 139 </pre> 140 141 <p>When using OpenGL ES 2.0, you must add another call to your {@link android.opengl.GLSurfaceView} 142 constructor, specifying that you want to use the 2.0 API:</p> 143 144 <pre> 145 // Create an OpenGL ES 2.0 context 146 setEGLContextClientVersion(2); 147 </pre> 148 149 <p class="note"><strong>Note:</strong> If you are using the OpenGL ES 2.0 API, make sure you declare 150 this in your application manifest. For more information, see <a href="#manifest">Declare OpenGL ES 151 Use 152 in the Manifest</a>.</p> 153 154 <p>One other optional addition to your {@link android.opengl.GLSurfaceView} implementation is to set 155 the render mode to only draw the view when there is a change to your drawing data using the 156 {@link android.opengl.GLSurfaceView#RENDERMODE_WHEN_DIRTY GLSurfaceView.RENDERMODE_WHEN_DIRTY} 157 setting:</p> 158 159 <pre> 160 // Render the view only when there is a change in the drawing data 161 setRenderMode(GLSurfaceView.RENDERMODE_WHEN_DIRTY); 162 </pre> 163 164 <p>This setting prevents the {@link android.opengl.GLSurfaceView} frame from being redrawn until you 165 call {@link android.opengl.GLSurfaceView#requestRender requestRender()}, which is more 166 efficient for this sample app.</p> 167 168 169 <h2 id="renderer">Build a Renderer Class</h2> 170 171 <p>The implementation of the {@link android.opengl.GLSurfaceView.Renderer} class, or renderer, 172 within an application that uses OpenGL ES is where things start to get interesting. This class 173 controls 174 what gets drawn on the {@link android.opengl.GLSurfaceView} with which it is associated. There are 175 three methods in a renderer that are called by the Android system in order to figure out what and 176 how to draw on a {@link android.opengl.GLSurfaceView}:</p> 177 178 <ul> 179 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} - 180 Called once to set up the view's OpenGL ES environment.</li> 181 <li>{@link android.opengl.GLSurfaceView.Renderer#onDrawFrame onDrawFrame()} - Called for each 182 redraw of the view.</li> 183 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} - Called if 184 the geometry of the view changes, for example when the device's screen orientation changes. 185 </li> 186 </ul> 187 188 <p>Here is a very basic implementation of an OpenGL ES renderer, that does nothing more than draw a 189 gray background in the {@link android.opengl.GLSurfaceView}:</p> 190 191 <pre> 192 public class MyGLRenderer implements GLSurfaceView.Renderer { 193 194 public void onSurfaceCreated(GL10 unused, EGLConfig config) { 195 // Set the background frame color 196 GLES20.glClearColor(0.0f, 0.0f, 0.0f, 1.0f); 197 } 198 199 public void onDrawFrame(GL10 unused) { 200 // Redraw background color 201 GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT); 202 } 203 204 public void onSurfaceChanged(GL10 unused, int width, int height) { 205 GLES20.glViewport(0, 0, width, height); 206 } 207 } 208 </pre> 209 210 <p>Thats all there is to it! The code examples above create a simple Android application that 211 displays a gray screen using OpenGL. While this code does not do anything very interesting, by 212 creating these classes, you have laid the foundation you need to start drawing graphic elements with 213 OpenGL.</p> 214 215 <p class="note"><strong>Note:</strong> You may wonder why these methods have a {@link 216 javax.microedition.khronos.opengles.GL10} parameter, when you are using the OpengGL ES 2.0 APIs. 217 These method signatures are simply reused for the 2.0 APIs to keep the Android framework code 218 simpler.</p> 219 220 <p>If you are familiar with the OpenGL ES APIs, you should now be able to set up a OpenGL ES 221 environment in your app and start drawing graphics. However, if you need a bit more help getting 222 started with OpenGL, head on to the next lessons for a few more hints.</p> 223
