java.lang.Object | |||
↳ | android.view.View | ||
↳ | android.view.SurfaceView | ||
↳ | org.anddev.andengine.opengl.view.GLSurfaceView |
Known Direct Subclasses |
An implementation of SurfaceView that uses the dedicated surface for displaying OpenGL rendering.
A GLSurfaceView provides the following features:
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(Renderer)
call.
setRenderer(Renderer)
. However, if desired, you can modify the
default behavior of GLSurfaceView by calling one or more of these methods
before calling setRenderer:
setDebugFlags(int)
setEGLConfigChooser(boolean)
setEGLConfigChooser(EGLConfigChooser)
setEGLConfigChooser(int, int, int, int, int, int)
setGLWrapper(GLWrapper)
By default GLSurfaceView chooses an available surface that'MAGIC_CONSTANT closest to a 16-bit R5G6B5 surface with a 16-bit depth buffer and no stencil. If you would prefer a different surface (for example, if you do not need a depth buffer) you can override the default behavior by calling one of the setEGLConfigChooser 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.
setRenderer(GLSurfaceView.Renderer)
to register a GLSurfaceView.Renderer
.
The renderer is responsible for doing the actual OpenGL rendering.
setRenderMode(int)
. The default is
continuous rendering.
onPause()
when the
activity pauses and 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.
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'MAGIC_CONSTANT 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(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); } }
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
GLSurfaceView.Renderer | A generic renderer interface. |
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. |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.view.View
|
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.view.View
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Standard View constructor.
| |||||||||||
Standard View constructor.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Get the current value of the debug flags.
| |||||||||||
Get the current rendering mode.
| |||||||||||
Inform the view that the activity is paused.
| |||||||||||
Inform the view that the activity is resumed.
| |||||||||||
Queue a runnable to be run on the GL rendering thread.
| |||||||||||
Request that the renderer render a frame.
| |||||||||||
Set the debug flags to a new value.
| |||||||||||
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.
| |||||||||||
Install a config chooser which will choose a config with at least the
specified component sizes, and as close to the specified component sizes
as possible.
| |||||||||||
Install a custom EGLConfigChooser.
| |||||||||||
Set the glWrapper.
| |||||||||||
Set the rendering mode.
| |||||||||||
Set the renderer associated with this view.
| |||||||||||
This method is part of the SurfaceHolder.Callback interface, and is not
normally called or subclassed by clients of GLSurfaceView.
| |||||||||||
This method is part of the SurfaceHolder.Callback interface, and is not
normally called or subclassed by clients of GLSurfaceView.
| |||||||||||
This method is part of the SurfaceHolder.Callback interface, and is not
normally called or subclassed by clients of GLSurfaceView.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.view.SurfaceView
| |||||||||||
From class
android.view.View
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
android.graphics.drawable.Drawable.Callback
| |||||||||||
From interface
android.view.KeyEvent.Callback
| |||||||||||
From interface
android.view.SurfaceHolder.Callback
| |||||||||||
From interface
android.view.accessibility.AccessibilityEventSource
|
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.
Log GL calls to the system log at "verbose" level with tag "GLSurfaceView".
The renderer is called continuously to re-render the scene.
The renderer only renders when the surface is created, or when
requestRender()
is called.
Standard View constructor. In order to render something, you must call
setRenderer(GLSurfaceView.Renderer)
to register a renderer.
Standard View constructor. In order to render something, you must call
setRenderer(GLSurfaceView.Renderer)
to register a renderer.
Get the current value of the debug flags.
Get the current rendering mode. May be called from any thread. Must not be called before a renderer has been set.
Inform the view that the activity is paused. The owner of this view must call this method when the activity is paused. Calling this method will pause the rendering thread. Must not be called before a renderer has been set.
Inform the view that the activity is resumed. The owner of this view must call this method when the activity is resumed. Calling this method will recreate the OpenGL display and resume the rendering thread. Must not be called before a renderer has been set.
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 be called after onResume() and before onPause().
r | the runnable to be run on the GL rendering thread. |
---|
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 be called after onResume() and before onPause().
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.
debugFlags | the new debug flags |
---|
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(Renderer)
is called.
If no setEGLConfigChooser method is called, then by default the view will choose a config as close to 16-bit RGB as possible, with a depth buffer as close to 16 bits as possible.
Install a config chooser which will choose a config with at least the specified component sizes, and as close to the specified component sizes as possible.
If this method is called, it must be called before
setRenderer(Renderer)
is called.
If no setEGLConfigChooser method is called, then by default the view will choose a config as close to 16-bit RGB as possible, with a depth buffer as close to 16 bits as possible.
Install a custom EGLConfigChooser.
If this method is called, it must be called before
setRenderer(Renderer)
is called.
If no setEGLConfigChooser method is called, then by default the view will choose a config as close to 16-bit RGB as possible, with a depth buffer as close to 16 bits as possible.
Set the glWrapper. If the glWrapper is not null, its
wrap(GL)
method is called whenever a surface is
created. A GLWrapper can be used to wrap the GL object that'MAGIC_CONSTANT 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.
glWrapper | the new GLWrapper |
---|
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(Renderer)
renderMode | one of the RENDERMODE_X constants |
---|
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:
setEGLConfigChooser(boolean)
setEGLConfigChooser(EGLConfigChooser)
setEGLConfigChooser(int, int, int, int, int, int)
The following GLSurfaceView methods can only be called after setRenderer is called:
renderer | the renderer to use to perform OpenGL drawing. |
---|
This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.
This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.
This method is part of the SurfaceHolder.Callback interface, and is not normally called or subclassed by clients of GLSurfaceView.