RFC: GLAutoDrawable API Change regarding control of GLEventListener

Hi All,

I have made some API changes in GLAutoDrawable.

At least I want to give you the heads up about them instead of
bumping your heads on it later on w/ bad feelings.

At best you may review it and find inconsistencies,
so we can better the API.

Note that even though I have pushed the commit, it is not written in stone [yet].

I dump the commit log below, allowing you to comment it in place.

Motivation of the commit is sourced after reviewing a few JOGL use cases (read user apps)
and validating our own.

Even our GearsES2/RedSquareES2 GLEventListener contained a 'lifecycle' hack,
which has been removed w/ this patch.

+++

<http://jogamp.org/git/?p=jogl.git;a=commit;h=c002e04f848116922a1ed7bd96ead54961649bbd>

commit c002e04f848116922a1ed7bd96ead54961649bbd
Author: Sven Gothel <[hidden email]>
Date:   Sun Nov 4 07:09:39 2012 +0100

    GLAutoDrawable: Fix GLEventListener lifecycle and expose more user control (API Change) ; Added GLDrawableUtil

    A GLEventListener resides in two states, initialized and uninitialized.
    When added to a GLAutoDrawable, it is uninitialized.
    A first 'display()' will issue GLEventListener's 'init(..)' which renders it initialized.
    This is usually accompanied by 'reshape(..)' propagating the drawable's dimension.

    Destruction of the GLAutoDrawable will issue GLEventListener's 'dispose(..)' which renders it uninitialized.

    It turns our these means of GLEventListener controls are not sufficient in case
    the user requires to remove and add them during the lifecycle and rendering of their GLAutoDrawable host.
    GLAutoDrawable 'removeGLEventListener(..)' merely removes the GLEventListener from the list,
    but does not complete it's lifecycle, i.e. issues 'dispose(..)' if initialized to realease GL related resources.

    Hence the following essential API changes are made to complete the lifecycle:

    +  public GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove);

       disposing a single GLEventListener, allowing it's removal from the list being optional

    This is demonstrated via GLDrawableUtil.swapGLContextAndAllGLEventListener(GLAutoDrawable a, GLAutoDrawable b), see below.

    ++++++++

    Further more the following API changes were made to expose complete control of
    GLEventListener to the user:

    -  public void removeGLEventListener(GLEventListener listener);
    +  public GLEventListener removeGLEventListener(GLEventListener listener);

       The return value allows simple pipelining, and also delivers information whether
       the passed listener was actually removed.

    -  public GLEventListener removeGLEventListener(int index) throws IndexOutOfBoundsException;
    +  public int getGLEventListenerCount();
    +  public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException;

       Dropping the redundant removal by index, while adding count and get methods.

    +  public boolean getGLEventListenerInitState(GLEventListener listener);
    +  public void setGLEventListenerInitState(GLEventListener listener, boolean initialized);

       Allows retrieving and setting of listener states.

    All in all these API changes allows a user to experience all freedoms in dealing w/
    GLEventListeners hosted by GLAutoDrawable impl. and shall be future proof.

    Note that we have avoided the Iterator pattern due to it's overhead of temporal objects creation.
    The simple indexed access allows us to implement each method as an atomic operation.

    +++++++++++

    Further more a simple enqueue(..) method has been added, allowing to just enqueue a GLRunnable
    w/o provoking it's execution - as invoke(..) does.
    This method pleases a use case where GLRunnables are batched and shall be executed later on..

       public boolean invoke(boolean wait, GLRunnable glRunnable);
    +  public void enqueue(GLRunnable glRunnable);

    +++++++++++

    Added GLDrawableUtil, exposes utility function to rearrange GLEventListener, modifiy GLAutoDrawable, etc.

    GLDrawableUtil.swapGLContextAndAllGLEventListener(GLAutoDrawable a, GLAutoDrawable b)
    is tested and demonstrated w/ TestGLContextDrawableSwitchNEWT.

    Manually tested on X11, OSX and Windows.

I don't understand the last change, invoke() already has a parameter to indicate whether or not the runnable has to be executed now or later. Personally, I find the enqueue() method useless and confusing.

On 11/04/2012 08:42 PM, gouessej [via jogamp] wrote:
> I don't understand the last change, invoke() already has a parameter to
> indicate whether or not the runnable has to be executed now or later.
> Personally, I find the enqueue() method useless and confusing.

I agree.

However invoke(..) does provoke display() even if wait==false
in case no animator is running.

'invoke()' will only return early if wait==false _and_ an animator is running,
in all other cases it either waits for the result or triggers display() itself.

'invoke' shall make clear that the GLRunnable will be invoked w/o further action 'soon'.
'enqueue' may not invoke the GLRunnable w/o further interaction,
but if an animator is running and attached.

Alternatively, instead of enqueue(..), we could add a method:
  + boolean invoke(boolean wait, List<GLRunnable> glRunnables)

this way batching GLRunnables can be left to the user
while not introducing new semantics.

Pro:
Such method would also offer a better determination of the GLRunnable
queue-in time, i.e. not processed by an animator while adding to the queue.
Using 'enqueue(GLEventListener)' would require to pause the animator
to ensure non got executed while feeding the queue.

Con:
This would require to create a temporary List object and perform more
operations.

What do you think ? Everybody ?


~Sven

I prefer creating a list but when I need to pass a single object, it should just make a singleton with it and do the same thing.