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 private final MyGLRenderer mRenderer; 133 134 public MyGLSurfaceView(Context context){ 135 super(context); 136 137 // Create an OpenGL ES 2.0 context 138 setEGLContextClientVersion(2); 139 140 mRenderer = new MyGLRenderer(); 141 142 // Set the Renderer for drawing on the GLSurfaceView 143 setRenderer(mRenderer); 144 } 145 } 146 </pre> 147 148 <p>One other optional addition to your {@link android.opengl.GLSurfaceView} implementation is to set 149 the render mode to only draw the view when there is a change to your drawing data using the 150 {@link android.opengl.GLSurfaceView#RENDERMODE_WHEN_DIRTY GLSurfaceView.RENDERMODE_WHEN_DIRTY} 151 setting:</p> 152 153 <pre> 154 // Render the view only when there is a change in the drawing data 155 setRenderMode(GLSurfaceView.RENDERMODE_WHEN_DIRTY); 156 </pre> 157 158 <p>This setting prevents the {@link android.opengl.GLSurfaceView} frame from being redrawn until you 159 call {@link android.opengl.GLSurfaceView#requestRender requestRender()}, which is more 160 efficient for this sample app.</p> 161 162 163 <h2 id="renderer">Build a Renderer Class</h2> 164 165 <p>The implementation of the {@link android.opengl.GLSurfaceView.Renderer} class, or renderer, 166 within an application that uses OpenGL ES is where things start to get interesting. This class 167 controls 168 what gets drawn on the {@link android.opengl.GLSurfaceView} with which it is associated. There are 169 three methods in a renderer that are called by the Android system in order to figure out what and 170 how to draw on a {@link android.opengl.GLSurfaceView}:</p> 171 172 <ul> 173 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} - 174 Called once to set up the view's OpenGL ES environment.</li> 175 <li>{@link android.opengl.GLSurfaceView.Renderer#onDrawFrame onDrawFrame()} - Called for each 176 redraw of the view.</li> 177 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} - Called if 178 the geometry of the view changes, for example when the device's screen orientation changes. 179 </li> 180 </ul> 181 182 <p>Here is a very basic implementation of an OpenGL ES renderer, that does nothing more than draw a 183 black background in the {@link android.opengl.GLSurfaceView}:</p> 184 185 <pre> 186 public class MyGLRenderer implements GLSurfaceView.Renderer { 187 188 public void onSurfaceCreated(GL10 unused, EGLConfig config) { 189 // Set the background frame color 190 GLES20.glClearColor(0.0f, 0.0f, 0.0f, 1.0f); 191 } 192 193 public void onDrawFrame(GL10 unused) { 194 // Redraw background color 195 GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT); 196 } 197 198 public void onSurfaceChanged(GL10 unused, int width, int height) { 199 GLES20.glViewport(0, 0, width, height); 200 } 201 } 202 </pre> 203 204 <p>Thats all there is to it! The code examples above create a simple Android application that 205 displays a black screen using OpenGL. While this code does not do anything very interesting, by 206 creating these classes, you have laid the foundation you need to start drawing graphic elements with 207 OpenGL.</p> 208 209 <p class="note"><strong>Note:</strong> You may wonder why these methods have a {@link 210 javax.microedition.khronos.opengles.GL10} parameter, when you are using the OpengGL ES 2.0 APIs. 211 These method signatures are simply reused for the 2.0 APIs to keep the Android framework code 212 simpler.</p> 213 214 <p>If you are familiar with the OpenGL ES APIs, you should now be able to set up a OpenGL ES 215 environment in your app and start drawing graphics. However, if you need a bit more help getting 216 started with OpenGL, head on to the next lessons for a few more hints.</p> 217
