Android Guides | Samples

Android.Opengl.GLSurfaceView Class

An implementation of SurfaceView that uses the dedicated surface for displaying OpenGL rendering.

See Also: GLSurfaceView

Syntax

[Android.Runtime.Register("android/opengl/GLSurfaceView", DoNotGenerateAcw=true)]
public class GLSurfaceView : SurfaceView, ISurfaceHolderCallback, IDisposable

Remarks

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(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]

Requirements

Namespace: Android.Opengl
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 3

The members of Android.Opengl.GLSurfaceView are listed below.

See Also: SurfaceView

Public Constructors

Standard View constructor.
Standard View constructor.

Protected Constructors

A constructor used when creating managed representations of JNI objects; called by the runtime.

Public Fields

const
DebugCheckGlErrorDebugFlags (1). Check glError() after every GL call and throw an exception if glError indicates that an error has occurred.
const
DebugLogGlCallsDebugFlags (2). Log GL calls to the system log at "verbose" level with tag "GLSurfaceView".
const
RendermodeContinuouslyRendermode (1). The renderer is called continuously to re-render the scene.
const
RendermodeWhenDirtyRendermode (0). The renderer only renders when the surface is created, or when GLSurfaceView.RequestRender is called.

Public Properties

DebugFlagsDebugFlags. Get the current value of the debug flags.
PreserveEGLContextOnPauseBoolean.
RenderModeRendermode. Get the current rendering mode.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

OnPause()
Inform the view that the activity is paused.
OnResume()
Inform the view that the activity is resumed.
QueueEvent(IRunnable)
Queue a runnable to be run on the GL rendering thread.
QueueEvent(Action)
RequestRender()
Request that the renderer render a frame.
SetEGLConfigChooser(GLSurfaceView+IEGLConfigChooser)
Install a custom EGLConfigChooser.
SetEGLConfigChooser(Boolean)
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.
SetEGLConfigChooser(Int32, Int32, Int32, Int32, Int32, Int32)
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.
SetEGLContextClientVersion(Int32)
Inform the default EGLContextFactory and default EGLConfigChooser which EGLContext client version to pick.
SetEGLContextFactory(GLSurfaceView+IEGLContextFactory)
Install a custom EGLContextFactory.
SetEGLWindowSurfaceFactory(GLSurfaceView+IEGLWindowSurfaceFactory)
Install a custom EGLWindowSurfaceFactory.
SetGLWrapper(GLSurfaceView+IGLWrapper)
Set the glWrapper.
SetRenderer(GLSurfaceView+IRenderer)
Set the renderer associated with this view.
SurfaceChanged(ISurfaceHolder, Format, Int32, Int32)
This method is part of the SurfaceHolder.
SurfaceCreated(ISurfaceHolder)
This method is part of the SurfaceHolder.
SurfaceDestroyed(ISurfaceHolder)
This method is part of the SurfaceHolder.