• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.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
28system.  To allow GLES to work on a variety of platforms, it is designed to be
29combined with a library that knows how to create and access windows through the
30operating system.  The library used for Android is called EGL.  If you want to
31draw textured polygons, you use GLES calls; if you want to put your rendering on
32the 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,
35this means creating an EGLContext and an EGLSurface.  GLES operations apply to
36the current context, which is accessed through thread-local storage rather than
37passed around as an argument.  This means you have to be careful about which
38thread your rendering code executes on, and which context is current on that
39thread.</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")
44or a window allocated by the operating system.  EGL window surfaces are created
45with the <code>eglCreateWindowSurface()</code> call.  It takes a "window object" as an
46argument, which on Android can be a SurfaceView, a SurfaceTexture, a
47SurfaceHolder, or a Surface -- all of which have a BufferQueue underneath.  When
48you make this call, EGL creates a new EGLSurface object, and connects it to the
49producer interface of the window object's BufferQueue.  From that point onward,
50rendering to that EGLSurface results in a buffer being dequeued, rendered into,
51and queued for use by the consumer.  (The term "window" is indicative of the
52expected use, but bear in mind the output might not be destined to appear
53on the display.)</p>
54
55<p>EGL does not provide lock/unlock calls.  Instead, you issue drawing commands and
56then call <code>eglSwapBuffers()</code> to submit the current frame.  The
57method name comes from the traditional swap of front and back buffers, but the actual
58implementation may be very different.</p>
59
60<p>Only one EGLSurface can be associated with a Surface at a time -- you can have
61only one producer connected to a BufferQueue -- but if you destroy the
62EGLSurface it will disconnect from the BufferQueue and allow something else to
63connect.</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
69just another aspect of Surface (like SurfaceHolder).  It's a related but
70independent concept.  You can draw on an EGLSurface that isn't backed by a
71Surface, and you can use a Surface without EGL.  EGLSurface just gives GLES a
72place 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
77equivalent in C/C++ is the ANativeWindow class, semi-exposed by the <a
78href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>.  You
79can get the ANativeWindow from a Surface with the <code>ANativeWindow_fromSurface()</code>
80call.  Just like its Java-language cousin, you can lock it, render in software,
81and unlock-and-post.</p>
82
83<p>To create an EGL window surface from native code, you pass an instance of
84EGLNativeWindowType to <code>eglCreateWindowSurface()</code>.  EGLNativeWindowType is just
85a 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
88BufferQueue should not come as a surprise.</p>
89