GLSurfaceView


public class GLSurfaceView
extends SurfaceView implements SurfaceHolder.Callback2

java.lang.Object
   ↳ android.view.View
     ↳ android.view.SurfaceView
       ↳ android.opengl.GLSurfaceView


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 setRenderer(android.opengl.GLSurfaceView.Renderer) call.

Initializing GLSurfaceView

All you have to do to initialize a GLSurfaceView is call setRenderer(android.opengl.GLSurfaceView.Renderer). 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 many 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 setDebugFlags(int), and setGLWrapper(GLWrapper). 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 setRenderer(Renderer) to register a Renderer. 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 setRenderMode(int). The default is continuous rendering.

Activity Life-cycle

A GLSurfaceView must be notified when to pause and resume rendering. GLSurfaceView clients are required to call onPause() when the activity stops and onResume() when the activity starts. 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 queueEvent(java.lang.Runnable). For 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);
     }
 }
 

Summary

Nested classes

interface GLSurfaceView.EGLConfigChooser

An interface for choosing an EGLConfig configuration from a list of potential configurations. 

interface GLSurfaceView.EGLContextFactory

An interface for customizing the eglCreateContext and eglDestroyContext calls. 

interface GLSurfaceView.EGLWindowSurfaceFactory

An interface for customizing the eglCreateWindowSurface and eglDestroySurface calls. 

interface GLSurfaceView.GLWrapper

An interface used to wrap a GL interface. 

interface GLSurfaceView.Renderer

A generic renderer interface. 

Inherited XML attributes

Constants

int DEBUG_CHECK_GL_ERROR

Check glError() after every GL call and throw an exception if glError indicates that an error has occurred.

int DEBUG_LOG_GL_CALLS

Log GL calls to the system log at "verbose" level with tag "GLSurfaceView".

int RENDERMODE_CONTINUOUSLY

The renderer is called continuously to re-render the scene.

int RENDERMODE_WHEN_DIRTY

The renderer only renders when the surface is created, or when requestRender() is called.

Inherited constants

Inherited fields

Public constructors

GLSurfaceView(Context context)

Standard View constructor.

GLSurfaceView(Context context, AttributeSet attrs)

Standard View constructor.

Public methods

int getDebugFlags()

Get the current value of the debug flags.

boolean getPreserveEGLContextOnPause()
int getRenderMode()

Get the current rendering mode.

void onPause()

Pause the rendering thread, optionally tearing down the EGL context depending upon the value of setPreserveEGLContextOnPause(boolean).

void onResume()

Resumes the rendering thread, re-creating the OpenGL context if necessary.

void queueEvent(Runnable r)

Queue a runnable to be run on the GL rendering thread.

void requestRender()

Request that the renderer render a frame.

void setDebugFlags(int debugFlags)

Set the debug flags to a new value.

void setEGLConfigChooser(boolean needDepth)

Install a config chooser which will choose a config as close to 16-bit RGB as possible, with or without an optional depth buffer as close to 16-bits as possible.

void setEGLConfigChooser(GLSurfaceView.EGLConfigChooser configChooser)

Install a custom EGLConfigChooser.

void setEGLConfigChooser(int redSize, int greenSize, int blueSize, int alphaSize, int depthSize, int stencilSize)

Install a config chooser which will choose a config with at least the specified depthSize and stencilSize, and exactly the specified redSize, greenSize, blueSize and alphaSize.

void setEGLContextClientVersion(int version)

Inform the default EGLContextFactory and default EGLConfigChooser which EGLContext client version to pick.

void setEGLContextFactory(GLSurfaceView.EGLContextFactory factory)

Install a custom EGLContextFactory.

void setEGLWindowSurfaceFactory(GLSurfaceView.EGLWindowSurfaceFactory factory)

Install a custom EGLWindowSurfaceFactory.

void setGLWrapper(GLSurfaceView.GLWrapper glWrapper)

Set the glWrapper.

void setPreserveEGLContextOnPause(boolean preserveOnPause)

Control whether the EGL context is preserved when the GLSurfaceView is paused and resumed.

void setRenderMode(int renderMode)

Set the rendering mode.

void setRenderer(GLSurfaceView.Renderer renderer)

Set the renderer associated with this view.

void surfaceChanged(SurfaceHolder holder, int format, int w, int h)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

void surfaceCreated(SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

void surfaceDestroyed(SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

void surfaceRedrawNeeded(SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback2 interface, and is not normally called or subclassed by clients of GLSurfaceView.

void surfaceRedrawNeededAsync(SurfaceHolder holder, Runnable finishDrawing)

This method is part of the SurfaceHolder.Callback2 interface, and is not normally called or subclassed by clients of GLSurfaceView.

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

void onAttachedToWindow()

This method is used as part of the View class and is not normally called or subclassed by clients of GLSurfaceView.

void onDetachedFromWindow()

This is called when the view is detached from a window.

Inherited methods

Constants

DEBUG_CHECK_GL_ERROR

Added in API level 3
public static final int DEBUG_CHECK_GL_ERROR

Check glError() after every GL call and throw an exception if glError indicates that an error has occurred. This can be used to help track down which OpenGL ES call is causing an error.

Constant Value: 1 (0x00000001)

DEBUG_LOG_GL_CALLS

Added in API level 3
public static final int DEBUG_LOG_GL_CALLS

Log GL calls to the system log at "verbose" level with tag "GLSurfaceView".

Constant Value: 2 (0x00000002)

RENDERMODE_CONTINUOUSLY

Added in API level 3
public static final int RENDERMODE_CONTINUOUSLY

The renderer is called continuously to re-render the scene.

Constant Value: 1 (0x00000001)

RENDERMODE_WHEN_DIRTY

Added in API level 3
public static final int RENDERMODE_WHEN_DIRTY

The renderer only renders when the surface is created, or when requestRender() is called.

Constant Value: 0 (0x00000000)

Public constructors

GLSurfaceView

Added in API level 3
public GLSurfaceView (Context context)

Standard View constructor. In order to render something, you must call setRenderer(Renderer) to register a renderer.

Parameters
context Context

GLSurfaceView

Added in API level 3
public GLSurfaceView (Context context, 
                AttributeSet attrs)

Standard View constructor. In order to render something, you must call setRenderer(Renderer) to register a renderer.

Parameters
context Context

attrs AttributeSet

Public methods

getDebugFlags

Added in API level 3
public int getDebugFlags ()

Get the current value of the debug flags.

Returns
int the current value of the debug flags.

getPreserveEGLContextOnPause

Added in API level 11
public boolean getPreserveEGLContextOnPause ()

Returns
boolean true if the EGL context will be preserved when paused

getRenderMode

Added in API level 3
public int getRenderMode ()

Get the current rendering mode. May be called from any thread. Must not be called before a renderer has been set.

Returns
int the current rendering mode.

onPause

Added in API level 3
public void onPause ()

Pause the rendering thread, optionally tearing down the EGL context depending upon the value of setPreserveEGLContextOnPause(boolean). This method should be called when it is no longer desirable for the GLSurfaceView to continue rendering, such as in response to Activity.onStop. Must not be called before a renderer has been set.

onResume

Added in API level 3
public void onResume ()

Resumes the rendering thread, re-creating the OpenGL context if necessary. It is the counterpart to onPause(). This method should typically be called in Activity.onStart. Must not be called before a renderer has been set.

queueEvent

Added in API level 3
public void queueEvent (Runnable r)

Queue a runnable to be run on the GL rendering thread. This can be used to communicate with the Renderer on the rendering thread. Must not be called before a renderer has been set.

Parameters
r Runnable: the runnable to be run on the GL rendering thread.

requestRender

Added in API level 3
public void requestRender ()

Request that the renderer render a frame. This method is typically used when the render mode has been set to RENDERMODE_WHEN_DIRTY, so that frames are only rendered on demand. May be called from any thread. Must not be called before a renderer has been set.

setDebugFlags

Added in API level 3
public void setDebugFlags (int debugFlags)

Set the debug flags to a new value. The value is constructed by OR-together zero or more of the DEBUG_CHECK_* constants. The debug flags take effect whenever a surface is created. The default value is zero.

Parameters
debugFlags int: the new debug flags

setEGLConfigChooser

Added in API level 3
public void setEGLConfigChooser (boolean needDepth)

Install a config chooser which will choose a config as close to 16-bit RGB as possible, with or without an optional depth buffer as close to 16-bits as possible.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

If no setEGLConfigChooser method is called, then by default the view will choose an RGB_888 surface with a depth buffer depth of at least 16 bits.

setEGLConfigChooser

Added in API level 3
public void setEGLConfigChooser (GLSurfaceView.EGLConfigChooser configChooser)

Install a custom EGLConfigChooser.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

If no setEGLConfigChooser method is called, then by default the view will choose an EGLConfig that is compatible with the current android.view.Surface, with a depth buffer depth of at least 16 bits.

setEGLConfigChooser

Added in API level 3
public void setEGLConfigChooser (int redSize, 
                int greenSize, 
                int blueSize, 
                int alphaSize, 
                int depthSize, 
                int stencilSize)

Install a config chooser which will choose a config with at least the specified depthSize and stencilSize, and exactly the specified redSize, greenSize, blueSize and alphaSize.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

If no setEGLConfigChooser method is called, then by default the view will choose an RGB_888 surface with a depth buffer depth of at least 16 bits.

Parameters
redSize int

greenSize int

blueSize int

alphaSize int

depthSize int

stencilSize int

setEGLContextClientVersion

Added in API level 8
public void setEGLContextClientVersion (int version)

Inform the default EGLContextFactory and default EGLConfigChooser which EGLContext client version to pick.

Use this method to create an OpenGL ES 2.0-compatible context. Example:

     public MyView(Context context) {
         super(context);
         setEGLContextClientVersion(2); // Pick an OpenGL ES 2.0 context.
         setRenderer(new MyRenderer());
     }
 

Note: Activities which require OpenGL ES 2.0 should indicate this by setting @lt;uses-feature android:glEsVersion="0x00020000" /> in the activity's AndroidManifest.xml file.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

This method only affects the behavior of the default EGLContexFactory and the default EGLConfigChooser. If setEGLContextFactory(android.opengl.GLSurfaceView.EGLContextFactory) has been called, then the supplied EGLContextFactory is responsible for creating an OpenGL ES 2.0-compatible context. If setEGLConfigChooser(android.opengl.GLSurfaceView.EGLConfigChooser) has been called, then the supplied EGLConfigChooser is responsible for choosing an OpenGL ES 2.0-compatible config.

Parameters
version int: The EGLContext client version to choose. Use 2 for OpenGL ES 2.0

setEGLContextFactory

Added in API level 5
public void setEGLContextFactory (GLSurfaceView.EGLContextFactory factory)

Install a custom EGLContextFactory.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

If this method is not called, then by default a context will be created with no shared context and with a null attribute list.

Parameters
factory GLSurfaceView.EGLContextFactory

setEGLWindowSurfaceFactory

Added in API level 5
public void setEGLWindowSurfaceFactory (GLSurfaceView.EGLWindowSurfaceFactory factory)

Install a custom EGLWindowSurfaceFactory.

If this method is called, it must be called before setRenderer(android.opengl.GLSurfaceView.Renderer) is called.

If this method is not called, then by default a window surface will be created with a null attribute list.

Parameters
factory GLSurfaceView.EGLWindowSurfaceFactory

setGLWrapper

Added in API level 3
public void setGLWrapper (GLSurfaceView.GLWrapper glWrapper)

Set the glWrapper. If the glWrapper is not null, its GLWrapper#wrap(GL) method is called whenever a surface is created. A GLWrapper can be used to wrap the GL object that's passed to the renderer. Wrapping a GL object enables examining and modifying the behavior of the GL calls made by the renderer.

Wrapping is typically used for debugging purposes.

The default value is null.

Parameters
glWrapper GLSurfaceView.GLWrapper: the new GLWrapper

setPreserveEGLContextOnPause

Added in API level 11
public void setPreserveEGLContextOnPause (boolean preserveOnPause)

Control whether the EGL context is preserved when the GLSurfaceView is paused and resumed.

If set to true, then the EGL context may be preserved when the GLSurfaceView is paused.

Prior to API level 11, whether the EGL context is actually preserved or not depends upon whether the Android device can support an arbitrary number of EGL contexts or not. Devices that can only support a limited number of EGL contexts must release the EGL context in order to allow multiple applications to share the GPU.

If set to false, the EGL context will be released when the GLSurfaceView is paused, and recreated when the GLSurfaceView is resumed.

The default is false.

Parameters
preserveOnPause boolean: preserve the EGL context when paused

setRenderMode

Added in API level 3
public void setRenderMode (int renderMode)

Set the rendering mode. When renderMode is RENDERMODE_CONTINUOUSLY, the renderer is called repeatedly to re-render the scene. When renderMode is RENDERMODE_WHEN_DIRTY, the renderer only rendered when the surface is created, or when requestRender() is called. Defaults to RENDERMODE_CONTINUOUSLY.

Using RENDERMODE_WHEN_DIRTY can improve battery life and overall system performance by allowing the GPU and CPU to idle when the view does not need to be updated.

This method can only be called after setRenderer(android.opengl.GLSurfaceView.Renderer)

Parameters
renderMode int: one of the RENDERMODE_X constants

setRenderer

Added in API level 3
public void setRenderer (GLSurfaceView.Renderer renderer)

Set the renderer associated with this view. Also starts the thread that will call the renderer, which in turn causes the rendering to start.

This method should be called once and only once in the life-cycle of a GLSurfaceView.

The following GLSurfaceView methods can only be called before setRenderer is called:

The following GLSurfaceView methods can only be called after setRenderer is called:

Parameters
renderer GLSurfaceView.Renderer: the renderer to use to perform OpenGL drawing.

surfaceChanged

Added in API level 3
public void surfaceChanged (SurfaceHolder holder, 
                int format, 
                int w, 
                int h)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface has changed. This value cannot be null.

format int: The new PixelFormat of the surface. Value is PixelFormat.RGBA_8888, PixelFormat.RGBX_8888, PixelFormat.RGBA_F16, PixelFormat.RGBA_1010102, PixelFormat.RGB_888, PixelFormat.RGB_565, or android.graphics.PixelFormat.R_8

w int: The new width of the surface. Value is 0 or greater

h int: The new height of the surface. Value is 0 or greater

surfaceCreated

Added in API level 3
public void surfaceCreated (SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface is being created. This value cannot be null.

surfaceDestroyed

Added in API level 3
public void surfaceDestroyed (SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface is being destroyed. This value cannot be null.

surfaceRedrawNeeded

Added in API level 24
public void surfaceRedrawNeeded (SurfaceHolder holder)

This method is part of the SurfaceHolder.Callback2 interface, and is not normally called or subclassed by clients of GLSurfaceView.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface has changed. This value cannot be null.

surfaceRedrawNeededAsync

Added in API level 26
public void surfaceRedrawNeededAsync (SurfaceHolder holder, 
                Runnable finishDrawing)

This method is part of the SurfaceHolder.Callback2 interface, and is not normally called or subclassed by clients of GLSurfaceView.

Parameters
holder SurfaceHolder: The SurfaceHolder which needs redrawing. This value cannot be null.

finishDrawing Runnable: A runnable to signal completion. This may be invoked from any thread. This value cannot be null.

Protected methods

finalize

Added in API level 3
protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable

onAttachedToWindow

Added in API level 3
protected void onAttachedToWindow ()

This method is used as part of the View class and is not normally called or subclassed by clients of GLSurfaceView.

onDetachedFromWindow

Added in API level 3
protected void onDetachedFromWindow ()

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.
If you override this method you must call through to the superclass implementation.