An implementation of SurfaceView that uses the dedicated surface for
displaying OpenGL rendering.
An implementation of SurfaceView that uses the dedicated surface for
displaying OpenGL rendering.
A GLSurfaceView provides the following features:
- Manages a surface, which is a special piece of memory that can be
composited into the Android view system.
- Manages an EGL display, which enables OpenGL to render into a surface.
- Accepts a user-provided Renderer object that does the actual rendering.
- Renders on a dedicated thread to decouple rendering performance from the
UI thread.
- Supports both on-demand and continuous rendering.
- Optionally wraps, traces, and/or error-checks the renderer's OpenGL calls.
Developer Guides
For more information about how to use OpenGL, read the
OpenGL developer guide.
Using GLSurfaceView
Typically you use GLSurfaceView by subclassing it and overriding one or more of the
View system input event methods. If your application does not need to override event
methods then GLSurfaceView can be used as-is. For the most part
GLSurfaceView behavior is customized by calling "set" methods rather than by subclassing.
For example, unlike a regular View, drawing is delegated to a separate Renderer object which
is registered with the GLSurfaceView
using the GLSurfaceView.SetRenderer(.IRenderer) call.
Initializing GLSurfaceView
All you have to do to initialize a GLSurfaceView is call
GLSurfaceView.SetRenderer(.IRenderer).
However, if desired, you can modify the default behavior of GLSurfaceView by calling one or
more of these methods before calling setRenderer:
Specifying the android.view.Surface
By default GLSurfaceView will create a PixelFormat.RGB_888 format surface. If a translucent
surface is required, call getHolder().setFormat(PixelFormat.TRANSLUCENT).
The exact format of a TRANSLUCENT surface is device dependent, but it will be
a 32-bit-per-pixel surface with 8 bits per component.
Choosing an EGL Configuration
A given Android device may support multiple EGLConfig rendering configurations.
The available configurations may differ in how may channels of data are present, as
well as how many bits are allocated to each channel. Therefore, the first thing
GLSurfaceView has to do when starting to render is choose what EGLConfig to use.
By default GLSurfaceView chooses a EGLConfig that has an RGB_888 pixel format,
with at least a 16-bit depth buffer and no stencil.
If you would prefer a different EGLConfig
you can override the default behavior by calling one of the
setEGLConfigChooser methods.
Debug Behavior
You can optionally modify the behavior of GLSurfaceView by calling
one or more of the debugging methods
GLSurfaceView.DebugFlags,
and
GLSurfaceView.SetGLWrapper(.IGLWrapper). These methods may be called before and/or after setRenderer, but
typically they are called before setRenderer so that they take effect immediately.
Setting a Renderer
Finally, you must call
GLSurfaceView.SetRenderer(.IRenderer) to register a
NoType:android/opengl/GLSurfaceView$Renderer;Href=../../../reference/android/opengl/GLSurfaceView.Renderer.html.
The renderer is
responsible for doing the actual OpenGL rendering.
Rendering Mode
Once the renderer is set, you can control whether the renderer draws
continuously or on-demand by calling
GLSurfaceView.RenderMode. The default is continuous rendering.
Activity Life-cycle
A GLSurfaceView must be notified when the activity is paused and resumed. GLSurfaceView clients
are required to call
GLSurfaceView.OnPause when the activity pauses and
GLSurfaceView.OnResume when the activity resumes. These calls allow GLSurfaceView to
pause and resume the rendering thread, and also allow GLSurfaceView to release and recreate
the OpenGL display.
Handling events
To handle an event you will typically subclass GLSurfaceView and override the
appropriate method, just as you would with any other View. However, when handling
the event, you may need to communicate with the Renderer object
that's running in the rendering thread. You can do this using any
standard Java cross-thread communication mechanism. In addition,
one relatively easy way to communicate with your renderer is
to call
GLSurfaceView.QueueEvent(Java.Lang.IRunnable). For example:
java Example
class MyGLSurfaceView extends GLSurfaceView {
private MyRenderer mMyRenderer;
public void start() {
mMyRenderer = ...;
setRenderer(mMyRenderer);
}
public boolean onKeyDown(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_DPAD_CENTER) {
queueEvent(new Runnable() {
// This method will be called on the rendering
// thread:
public void run() {
mMyRenderer.handleDpadCenter();
}});
return true;
}
return super.onKeyDown(keyCode, event);
}
}
[Android Documentation]