IT. Expert System.

Android Reference

GLSurfaceView


android.opengl

Class GLSurfaceView

  • All Implemented Interfaces:
    Drawable.Callback, AccessibilityEventSource, KeyEvent.Callback, SurfaceHolder.Callback, ViewTreeObserver.OnPreDrawListener

    public class GLSurfaceView
extends SurfaceView
implements SurfaceHolder.Callback
    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(Renderer) call.

    Initializing GLSurfaceView

    All you have to do to initialize a GLSurfaceView is 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:

    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 setDebugFlags(int), and setGLWrapper(android.opengl.GLSurfaceView.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(android.opengl.GLSurfaceView.Renderer) to register a GLSurfaceView.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 the activity is paused and resumed. GLSurfaceView clients are required to call 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.

    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(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);
     }
 }

    • Method Detail

      • finalize

        protected void finalize()
                 throws Throwable
        Description copied from class: Object
        Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

        Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

        If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

        Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

        Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

        Overrides:
        finalize in class Object
        Throws:
        Throwable

      • setGLWrapper

        public void setGLWrapper(GLSurfaceView.GLWrapper glWrapper)
        Set the glWrapper. If the glWrapper is not null, its GLSurfaceView.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 - the new GLWrapper

      • setDebugFlags

        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 - the new debug flags
        See Also:
        DEBUG_CHECK_GL_ERROR, DEBUG_LOG_GL_CALLS

      • getDebugFlags

        public int getDebugFlags()
        Get the current value of the debug flags.
        Returns:
        the current value of the debug flags.

      • setPreserveEGLContextOnPause

        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. Whether the EGL context is actually preserved or not depends upon whether the Android device that the program is running on 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 - preserve the EGL context when paused

      • getPreserveEGLContextOnPause

        public boolean getPreserveEGLContextOnPause()
        Returns:
        true if the EGL context will be preserved when paused

      • setEGLContextFactory

        public void setEGLContextFactory(GLSurfaceView.EGLContextFactory factory)
        Install a custom EGLContextFactory.

        If this method is called, it must be called before setRenderer(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.

      • setEGLWindowSurfaceFactory

        public void setEGLWindowSurfaceFactory(GLSurfaceView.EGLWindowSurfaceFactory factory)
        Install a custom EGLWindowSurfaceFactory.

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

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

      • setEGLConfigChooser

        public void setEGLConfigChooser(GLSurfaceView.EGLConfigChooser configChooser)
        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 an EGLConfig that is compatible with the current android.view.Surface, with a depth buffer depth of at least 16 bits.

        Parameters:
        configChooser -

      • setEGLConfigChooser

        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(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:
        needDepth -

      • setEGLConfigChooser

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

      • setEGLContextClientVersion

        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(Renderer) is called.

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

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

      • setRenderMode

        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(Renderer)

        Parameters:
        renderMode - one of the RENDERMODE_X constants
        See Also:
        RENDERMODE_CONTINUOUSLY, RENDERMODE_WHEN_DIRTY

      • getRenderMode

        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:
        the current rendering mode.
        See Also:
        RENDERMODE_CONTINUOUSLY, RENDERMODE_WHEN_DIRTY

      • requestRender

        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.

      • surfaceCreated

        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.
        Specified by:
        surfaceCreated in interface SurfaceHolder.Callback
        Parameters:
        holder - The SurfaceHolder whose surface is being created.

      • surfaceDestroyed

        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.
        Specified by:
        surfaceDestroyed in interface SurfaceHolder.Callback
        Parameters:
        holder - The SurfaceHolder whose surface is being destroyed.

      • surfaceChanged

        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.
        Specified by:
        surfaceChanged in interface SurfaceHolder.Callback
        Parameters:
        holder - The SurfaceHolder whose surface has changed.
        format - The new PixelFormat of the surface.
        w - The new width of the surface.
        h - The new height of the surface.

      • onPause

        public void onPause()
        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.

      • onResume

        public void onResume()
        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.

      • queueEvent

        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 - the runnable to be run on the GL rendering thread.

      • onDetachedFromWindow

        protected void onDetachedFromWindow()
        This method is used as part of the View class and is not normally called or subclassed by clients of GLSurfaceView. Must not be called before a renderer has been set.
        Overrides:
        onDetachedFromWindow in class TextView
        See Also:
        View.onAttachedToWindow()


Content

Android Reference

Java basics

Java Enterprise Edition (EE)

Java Standard Edition (SE)

SQL

HTML

PHP

CSS

Java Script

MYSQL

JQUERY

VBS

REGEX

C

C++

C#

Design patterns

RFC (standard status)

RFC (proposed standard status)

RFC (draft standard status)

RFC (informational status)

RFC (experimental status)

RFC (best current practice status)

RFC (historic status)

RFC (unknown status)

IT dictionary

License.
All information of this service is derived from the free sources and is provided solely in the form of quotations. This service provides information and interfaces solely for the familiarization (not ownership) and under the "as is" condition.
Copyright 2016 © ELTASK.COM. All rights reserved.
Site is optimized for mobile devices.
Downloads: 416 / 159226363. Delta: 0.06478 с