Package com.jogamp.opengl

Interface GLAutoDrawable

    • Field Detail

      • SCREEN_CHANGE_ACTION_ENABLED

        static final boolean SCREEN_CHANGE_ACTION_ENABLED
        Flag reflecting whether the GLDrawable reconfiguration will be issued in case a screen device change occurred, e.g. in a multihead environment, where you drag the window to another monitor.

    • Method Detail

      • getDelegatedDrawable

        GLDrawable getDelegatedDrawable()
        If the implementation uses delegation, return the delegated GLDrawable instance, otherwise return this instance.

      • getContext

        GLContext getContext()
        Returns the context associated with this drawable. The returned context will be synchronized. Don't rely on it's identity, the context may change.

      • setContext

        GLContext setContext​(GLContext newCtx,
                     boolean destroyPrevCtx)
        Associate the new context, newtCtx, to this auto-drawable.

        Remarks:

        • The currently associated context will be destroyed if destroyPrevCtx is true, otherwise it will be disassociated from this auto-drawable via setGLDrawable(null, true); including glFinish().
        • The new context will be associated with this auto-drawable via newCtx.setGLDrawable(drawable, true);.
        • If the old context was current on this thread, it is being released after disassociating this auto-drawable.
        • If the new context was current on this thread, it is being released before associating this auto-drawable and made current afterwards.
        • Implementation may issue #makeCurrent() and #release() while drawable reassociation.
        • The user shall take extra care of thread synchronization, i.e. lock the involved auto-drawable's upstream-locks and surfaces to avoid a race condition. See GLAutoDrawable Locking.

        Parameters:
        newCtx - the new context, maybe null for dis-association.
        destroyPrevCtx - if true, destroy the previous context if exists
        Returns:
        the previous GLContext, maybe null
        See Also:
        GLContext.setGLDrawable(GLDrawable, boolean), GLContext.setGLReadDrawable(GLDrawable), GLDrawableHelper.switchContext(GLDrawable, GLContext, boolean, GLContext, int)

      • addGLEventListener

        void addGLEventListener​(GLEventListener listener)
        Adds the given listener to the end of this drawable queue. The listeners are notified of events in the order of the queue.

        The newly added listener's init(..) method will be called once before any other of it's callback methods. See getGLEventListenerInitState(GLEventListener) for details.

        Parameters:
        listener - The GLEventListener object to be inserted

      • addGLEventListener

        void addGLEventListener​(int index,
                        GLEventListener listener)
                 throws IndexOutOfBoundsException
        Adds the given listener at the given index of this drawable queue. The listeners are notified of events in the order of the queue.

        The newly added listener's init(..) method will be called once before any other of it's callback methods. See getGLEventListenerInitState(GLEventListener) for details.

        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        listener - The GLEventListener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1

      • getGLEventListenerCount

        int getGLEventListenerCount()
        Returns the number of GLEventListener of this drawable queue.
        Returns:
        The number of GLEventListener objects of this drawable queue.

      • areAllGLEventListenerInitialized

        boolean areAllGLEventListenerInitialized()
        Returns true if all added GLEventListener are initialized, otherwise false.
        Since:
        2.2

      • getGLEventListener

        GLEventListener getGLEventListener​(int index)
                            throws IndexOutOfBoundsException
        Returns the GLEventListener at the given index of this drawable queue.
        Parameters:
        index - Position of the listener to be returned. Should be within (0 <= index && index < size()). An index value of -1 is interpreted as last listener, size()-1.
        Returns:
        The GLEventListener object at the given index.
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index < size()), or -1

      • getGLEventListenerInitState

        boolean getGLEventListenerInitState​(GLEventListener listener)
        Retrieves whether the given listener is initialized or not.

        After adding a GLEventListener it is marked uninitialized and added to a list of to be initialized GLEventListener. If such uninitialized GLEventListener's handler methods (reshape, display) are about to be invoked, it's init(..) method is invoked first. Afterwards the GLEventListener is marked initialized and removed from the list of to be initialized GLEventListener.

        This methods returns the GLEventListener initialized state, i.e. returns false if it is included in the list of to be initialized GLEventListener, otherwise true.

        Parameters:
        listener - the GLEventListener object to query it's initialized state.

      • disposeGLEventListener

        GLEventListener disposeGLEventListener​(GLEventListener listener,
                                       boolean remove)
        Disposes the given listener via dispose(..) if it has been initialized and added to this queue.

        If remove is true, the GLEventListener is removed from this drawable queue before disposal, otherwise marked uninitialized.

        If an GLAnimatorControl is being attached and the current thread is different than the animator's thread, it is paused during the operation.

        Note that this is an expensive operation, since dispose(..) is decorated by GLContext.makeCurrent() and GLContext.release().

        Use removeGLEventListener(listener) instead if you just want to remove the listener and don't care about the disposal of the it's (OpenGL) resources.

        Also note that this is done from within a particular drawable's GLEventListener handler (reshape, display, etc.), that it is not guaranteed that all other listeners will be evaluated properly during this update cycle.

        Parameters:
        listener - The GLEventListener object to be disposed and removed if remove is true
        remove - pass true to have the listener removed from this drawable queue, otherwise pass false
        Returns:
        the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added

      • removeGLEventListener

        GLEventListener removeGLEventListener​(GLEventListener listener)
        Removes the given listener from this drawable queue.

        This is an inexpensive operation, since the removed listener's dispose(..) method will not be called.

        Use disposeGLEventListener(listener, true) instead to ensure disposal of the listener's (OpenGL) resources.

        Note that if this is done from within a particular drawable's GLEventListener handler (reshape, display, etc.), that it is not guaranteed that all other listeners will be evaluated properly during this update cycle.

        Parameters:
        listener - The GLEventListener object to be removed
        Returns:
        the removed GLEventListener, or null if listener was not added

      • setExclusiveContextThread

        Thread setExclusiveContextThread​(Thread t)
                          throws GLException
        Dedicates this instance's GLContext to the given thread.
        The thread will exclusively claim the GLContext via display() and not release it until destroy() or setExclusiveContextThread(null) has been called.

        Default non-exclusive behavior is requested via setExclusiveContextThread(null), which will cause the next call of display() on the exclusive thread to release the GLContext. Only after it's async release, getExclusiveContextThread() will return null.

        To release a previous made exclusive thread, a user issues setExclusiveContextThread(null) and may poll getExclusiveContextThread() until it returns null, while the exclusive thread is still running.

        Note: Setting a new exclusive thread without properly releasing a previous one will throw an GLException.

        Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.

        One scenario could be to dedicate the context to the animator thread and spare redundant context switches, see AnimatorBase.setExclusiveContext(boolean).

        Parameters:
        t - the exclusive thread to claim the context, or null for default operation.
        Returns:
        previous exclusive context thread
        Throws:
        GLException - If an exclusive thread is still active but a new one is attempted to be set
        See Also:
        AnimatorBase.setExclusiveContext(boolean)

      • flushGLRunnables

        void flushGLRunnables()
        Flushes all enqueued GLRunnable of this GLAutoDrawable including notifying waiting executor.

        The executor which might have been blocked until notified will be unblocked and all tasks removed from the queue.

        Since:
        2.2
        See Also:
        invoke(boolean, GLRunnable)

      • destroy

        void destroy()
        Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext. If a window is attached to it's implementation, it shall be closed. Causes disposing of all OpenGL resources by calling dispose(..) for all registered GLEventListeners. Called automatically by the window system toolkit upon receiving a destroy notification. This routine may be called manually.

      • setAutoSwapBufferMode

        void setAutoSwapBufferMode​(boolean enable)
        Enables or disables automatic buffer swapping for this drawable. By default this property is set to true; when true, after all GLEventListeners have been called for a display() event, the front and back buffers are swapped, displaying the results of the render. When disabled, the user is responsible for calling {@link #swapBuffers(..)} manually.

      • getAutoSwapBufferMode

        boolean getAutoSwapBufferMode()
        Indicates whether automatic buffer swapping is enabled for this drawable. See setAutoSwapBufferMode(boolean).

      • getContextCreationFlags

        int getContextCreationFlags()
        Returns:
        Additional context creation flags

      • createContext

        GLContext createContext​(GLContext shareWith)
        Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext.

        The GLContext share need not be associated with this GLDrawable and may be null if sharing of display lists and other objects is not desired. See the note in the overview documentation context sharing as well as GLSharedContextSetter.

        This GLAutoDrawable implementation holds it's own GLContext reference, thus created a GLContext using this methods won't replace it implicitly. To replace or set this GLAutoDrawable's GLContext you need to call setContext(GLContext, boolean).

        The GLAutoDrawable implementation shall also set the context creation flags as customized w/ setContextCreationFlags(int).

        Specified by:
        createContext in interface GLDrawable

      • getGL

        GL getGL()
        Returns the GL pipeline object this GLAutoDrawable uses. If this method is called outside of the GLEventListener's callback methods (init, display, etc.) it may return null. Users should not rely on the identity of the returned GL object; for example, users should not maintain a hash table with the GL object as the key. Additionally, the GL object should not be cached in client code, but should be re-fetched from the GLAutoDrawable at the beginning of each call to init, display, etc.

      • setGL

        GL setGL​(GL gl)
        Sets the GL pipeline object this GLAutoDrawable uses. This should only be called from within the GLEventListener's callback methods, and usually only from within the init() method, in order to install a composable pipeline. See the JOGL demos for examples.
        Returns:
        the set GL pipeline or null if not successful

      • getUpstreamWidget

        Object getUpstreamWidget()
        Method may return the upstream UI toolkit object holding this GLAutoDrawable instance, if exist.

        Currently known Java UI toolkits and it's known return types are:

        Toolkit GLAutoDrawable Implementation ~ Return Type of getUpstreamWidget()
        NEWT GLWindow has a Window
        SWT GLCanvas is a Canvas
        AWT GLCanvas is a Canvas
        AWT GLJPanel is a JPanel
        However, the result may be other object types than the listed above due to new supported toolkits.

        This method may also return null if no UI toolkit is being used, as common for offscreen rendering.

      • isThreadGLCapable

        boolean isThreadGLCapable()
        Indicates whether the current thread is capable of performing OpenGL-related work.

        Implementation utilizes this knowledge to determine whether display() performs the OpenGL commands on the current thread directly or spawns them on the dedicated OpenGL thread.

        Since:
        2.2