1 page.title=EGLSurfaces and OpenGL ES 2 @jd:body 3 4 <!-- 5 Copyright 2014 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <p>OpenGL ES defines an API for rendering graphics. It does not define a windowing 28 system. To allow GLES to work on a variety of platforms, it is designed to be 29 combined with a library that knows how to create and access windows through the 30 operating system. The library used for Android is called EGL. If you want to 31 draw textured polygons, you use GLES calls; if you want to put your rendering on 32 the screen, you use EGL calls.</p> 33 34 <p>Before you can do anything with GLES, you need to create a GL context. In EGL, 35 this means creating an EGLContext and an EGLSurface. GLES operations apply to 36 the current context, which is accessed through thread-local storage rather than 37 passed around as an argument. This means you have to be careful about which 38 thread your rendering code executes on, and which context is current on that 39 thread.</p> 40 41 <h2 id=egl_surface>EGLSurfaces</h2> 42 43 <p>The EGLSurface can be an off-screen buffer allocated by EGL (called a "pbuffer") 44 or a window allocated by the operating system. EGL window surfaces are created 45 with the <code>eglCreateWindowSurface()</code> call. It takes a "window object" as an 46 argument, which on Android can be a SurfaceView, a SurfaceTexture, a 47 SurfaceHolder, or a Surface -- all of which have a BufferQueue underneath. When 48 you make this call, EGL creates a new EGLSurface object, and connects it to the 49 producer interface of the window object's BufferQueue. From that point onward, 50 rendering to that EGLSurface results in a buffer being dequeued, rendered into, 51 and queued for use by the consumer. (The term "window" is indicative of the 52 expected use, but bear in mind the output might not be destined to appear 53 on the display.)</p> 54 55 <p>EGL does not provide lock/unlock calls. Instead, you issue drawing commands and 56 then call <code>eglSwapBuffers()</code> to submit the current frame. The 57 method name comes from the traditional swap of front and back buffers, but the actual 58 implementation may be very different.</p> 59 60 <p>Only one EGLSurface can be associated with a Surface at a time -- you can have 61 only one producer connected to a BufferQueue -- but if you destroy the 62 EGLSurface it will disconnect from the BufferQueue and allow something else to 63 connect.</p> 64 65 <p>A given thread can switch between multiple EGLSurfaces by changing what's 66 "current." An EGLSurface must be current on only one thread at a time.</p> 67 68 <p>The most common mistake when thinking about EGLSurface is assuming that it is 69 just another aspect of Surface (like SurfaceHolder). It's a related but 70 independent concept. You can draw on an EGLSurface that isn't backed by a 71 Surface, and you can use a Surface without EGL. EGLSurface just gives GLES a 72 place to draw.</p> 73 74 <h2 id="anativewindow">ANativeWindow</h2> 75 76 <p>The public Surface class is implemented in the Java programming language. The 77 equivalent in C/C++ is the ANativeWindow class, semi-exposed by the <a 78 href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>. You 79 can get the ANativeWindow from a Surface with the <code>ANativeWindow_fromSurface()</code> 80 call. Just like its Java-language cousin, you can lock it, render in software, 81 and unlock-and-post.</p> 82 83 <p>To create an EGL window surface from native code, you pass an instance of 84 EGLNativeWindowType to <code>eglCreateWindowSurface()</code>. EGLNativeWindowType is just 85 a synonym for ANativeWindow, so you can freely cast one to the other.</p> 86 87 <p>The fact that the basic "native window" type just wraps the producer side of a 88 BufferQueue should not come as a surprise.</p> 89
