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 you support so that devices that do not support theses formats do not try to run your 72 application:</p> 73 74 <pre> 75 <supports-gl-texture android:name="GL_OES_compressed_ETC1_RGB8_texture" /> 76 <supports-gl-texture android:name="GL_OES_compressed_paletted_texture" /> 77 </pre> 78 79 <p>For more information about texture compression formats, see the 80 <a href="{@docRoot}guide/topics/graphics/opengl.html#textures">OpenGL</a> developer guide.</p> 81 82 83 <h2 id="activity">Create an Activity for OpenGL ES Graphics</h2> 84 85 <p>Android applications that use OpenGL ES have activities just like any other application that has 86 a user interface. The main difference from other applications is what you put in the layout for your 87 activity. While in many applications you might use {@link android.widget.TextView}, {@link 88 android.widget.Button} and {@link android.widget.ListView}, in an app that uses OpenGL ES, you can 89 also add a {@link android.opengl.GLSurfaceView}.</p> 90 91 <p>The following code example shows a minimal implementation of an activity that uses a 92 {@link android.opengl.GLSurfaceView} as its primary view:</p> 93 94 <pre> 95 public class OpenGLES20 extends Activity { 96 97 private GLSurfaceView mGLView; 98 99 @Override 100 public void onCreate(Bundle savedInstanceState) { 101 super.onCreate(savedInstanceState); 102 103 // Create a GLSurfaceView instance and set it 104 // as the ContentView for this Activity. 105 mGLView = new MyGLSurfaceView(this); 106 setContentView(mGLView); 107 } 108 } 109 </pre> 110 111 <p class="note"><strong>Note:</strong> OpenGL ES 2.0 requires Android 2.2 (API Level 8) or higher, 112 so make sure your Android project targets that API or higher.</p> 113 114 115 <h2 id="glsurfaceview">Build a GLSurfaceView Object</h2> 116 117 <p>A {@link android.opengl.GLSurfaceView} is a specialized view where you can draw OpenGL ES 118 graphics. 119 It does not do much by itself. The actual drawing of objects is controlled in the {@link 120 android.opengl.GLSurfaceView.Renderer} that you set on this view. In fact, the code for this object 121 is so thin, you may be tempted to skip extending it and just create an unmodified {@link 122 android.opengl.GLSurfaceView} instance, but dont do that. You need to extend this class in 123 order to capture touch events, which is covered in the <a href="#touch.html">Responding to Touch 124 Events</a> lesson.</p> 125 126 <p>The essential code for a {@link android.opengl.GLSurfaceView} is minimal, so for a quick 127 implementation, it is common to 128 just create an inner class in the activity that uses it:</p> 129 130 <pre> 131 class MyGLSurfaceView extends GLSurfaceView { 132 133 public MyGLSurfaceView(Context context){ 134 super(context); 135 136 // Set the Renderer for drawing on the GLSurfaceView 137 setRenderer(new MyRenderer()); 138 } 139 } 140 </pre> 141 142 <p>When using OpenGL ES 2.0, you must add another call to your {@link android.opengl.GLSurfaceView} 143 constructor, specifying that you want to use the 2.0 API:</p> 144 145 <pre> 146 // Create an OpenGL ES 2.0 context 147 setEGLContextClientVersion(2); 148 </pre> 149 150 <p class="note"><strong>Note:</strong> If you are using the OpenGL ES 2.0 API, make sure you declare 151 this in your application manifest. For more information, see <a href="#manifest">Declare OpenGL ES 152 Use 153 in the Manifest</a>.</p> 154 155 <p>One other optional addition to your {@link android.opengl.GLSurfaceView} implementation is to set 156 the render mode to only draw the view when there is a change to your drawing data using the 157 {@link android.opengl.GLSurfaceView#RENDERMODE_WHEN_DIRTY GLSurfaceView.RENDERMODE_WHEN_DIRTY} 158 setting:</p> 159 160 <pre> 161 // Render the view only when there is a change in the drawing data 162 setRenderMode(GLSurfaceView.RENDERMODE_WHEN_DIRTY); 163 </pre> 164 165 <p>This setting prevents the {@link android.opengl.GLSurfaceView} frame from being redrawn until you 166 call {@link android.opengl.GLSurfaceView#requestRender requestRender()}, which is more 167 efficient for this sample app.</p> 168 169 170 <h2 id="renderer">Build a Renderer Class</h2> 171 172 <p>The implementation of the {@link android.opengl.GLSurfaceView.Renderer} class, or renderer, 173 within an application that uses OpenGL ES is where things start to get interesting. This class 174 controls 175 what gets drawn on the {@link android.opengl.GLSurfaceView} with which it is associated. There are 176 three methods in a renderer that are called by the Android system in order to figure out what and 177 how to draw on a {@link android.opengl.GLSurfaceView}:</p> 178 179 <ul> 180 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceCreated onSurfaceCreated()} - 181 Called once to set up the view's OpenGL ES environment.</li> 182 <li>{@link android.opengl.GLSurfaceView.Renderer#onDrawFrame onDrawFrame()} - Called for each 183 redraw of the view.</li> 184 <li>{@link android.opengl.GLSurfaceView.Renderer#onSurfaceChanged onSurfaceChanged()} - Called if 185 the geometry of the view changes, for example when the device's screen orientation changes. 186 </li> 187 </ul> 188 189 <p>Here is a very basic implementation of an OpenGL ES renderer, that does nothing more than draw a 190 gray background in the {@link android.opengl.GLSurfaceView}:</p> 191 192 <pre> 193 public class MyGL20Renderer implements GLSurfaceView.Renderer { 194 195 public void onSurfaceCreated(GL10 unused, EGLConfig config) { 196 // Set the background frame color 197 GLES20.glClearColor(0.5f, 0.5f, 0.5f, 1.0f); 198 } 199 200 public void onDrawFrame(GL10 unused) { 201 // Redraw background color 202 GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT); 203 } 204 205 public void onSurfaceChanged(GL10 unused, int width, int height) { 206 GLES20.glViewport(0, 0, width, height); 207 } 208 } 209 </pre> 210 211 <p>Thats all there is to it! The code examples above create a simple Android application that 212 displays a gray screen using OpenGL. While this code does not do anything very interesting, by 213 creating these classes, you have laid the foundation you need to start drawing graphic elements with 214 OpenGL.</p> 215 216 <p class="note"><strong>Note:</strong> You may wonder why these methods have a {@link 217 javax.microedition.khronos.opengles.GL10} parameter, when you are using the OpengGL ES 2.0 APIs. 218 These method signatures are simply reused for the 2.0 APIs to keep the Android framework code 219 simpler.</p> 220 221 <p>If you are familiar with the OpenGL ES APIs, you should now be able to set up a OpenGL ES 222 environment in your app and start drawing graphics. However, if you need a bit more help getting 223 started with OpenGL, head on to the next lessons for a few more hints.</p> 224
