Refine GL[Auto]Drawable 'realized' state in API doc, and relax it's realized requirement in GL[Offscreen]AutoDrawableDelegate*

Compatible w/ 'before'.

TODO: Contemplate about GLDrawableFactory.createOffscreenAutoDrawable(..) whether it:
  - should better return an unrealized [auto]drawable
  - or adding another API method for such case

  Goal: Allow passing vector of [device/context/..] for use cases
        such as re-using an onscreen destructed surface and on-/offscreen hopping.

5 files changed, 31 insertions, 18 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
index 38315dc72..24116f199 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
@@ -64,10 +64,10 @@ import jogamp.opengl.GLDrawableImpl;
  */
 public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAutoDrawable {
     /**
-     * @param drawable a valid and already realized {@link GLDrawable}
+     * @param drawable a valid {@link GLDrawable}, may not be {@link GLDrawable#isRealized() realized} yet.
      * @param context a valid {@link GLContext}, 
      *                may not have been made current (created) yet,
-     *                may not be associated w/ <code>drawable<code> yet, 
+     *                may not be associated w/ <code>drawable<code> yet,
      *                may be <code>null</code> for lazy initialization
      * @param upstreamWidget optional UI element holding this instance, see {@link #getUpstreamWidget()}.
      * @param ownDevice pass <code>true</code> if {@link AbstractGraphicsDevice#close()} shall be issued,
@@ -81,9 +81,6 @@ public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAuto
         if(null == drawable) {
             throw new IllegalArgumentException("null drawable");
         }
-        if(!drawable.isRealized()) {
-            throw new IllegalArgumentException("drawable not realized");
-        }
         this.upstreamWidget = upstreamWidget;
         this.lock = ( null != lock ) ? lock : LockFactory.createRecursiveLock() ;
     }
@@ -174,6 +171,7 @@ public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAuto
     
     @Override
     public final void setRealized(boolean realized) {
+        drawable.setRealized(realized);
     }
 
     @Override
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index c0910eb0f..95c314a48 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -126,7 +126,12 @@ public interface GLDrawable {
    */
   public void setRealized(boolean realized);
 
-  /** @return true if this drawable is realized, otherwise false */
+  /** 
+   * Returns <code>true</code> if this drawable is realized, otherwise <code>true</code>.
+   * <p>
+   * A drawable can be realized and unrealized via {@link #setRealized(boolean)}.
+   * </p>
+   */
   public boolean isRealized();
 
   /** Returns the current width of this GLDrawable. */
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index 70480e728..7fcd913cf 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -436,7 +436,7 @@ public abstract class GLDrawableFactory {
   // Methods to create high-level objects
 
   /**
-   * Returns a GLDrawable according to it's chosen {@link GLCapabilitiesImmutable},<br>
+   * Returns an {@link GLDrawable#isRealized() unrealized} GLDrawable according to it's chosen {@link GLCapabilitiesImmutable},<br>
    * which determines pixel format, on- and offscreen incl. PBuffer type.
    * <p>
    * The chosen {@link GLCapabilitiesImmutable} are referenced within the target
@@ -473,9 +473,11 @@ public abstract class GLDrawableFactory {
     throws IllegalArgumentException, GLException;
   
   /**
-   * Creates an {@link GLOffscreenAutoDrawable} incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
+   * Creates a {@link GLDrawable#isRealized() realized} {@link GLOffscreenAutoDrawable} 
+   * incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
    * <p>
-   * The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is realized and it's {@link GLContext} assigned but not yet made current.
+   * The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is {@link GLDrawable#isRealized() realized} 
+   * and it's {@link GLContext} assigned but not yet made current.
    * </p>
    * <p>
    * In case the passed {@link GLCapabilitiesImmutable} contains default values, i.e.
@@ -513,7 +515,8 @@ public abstract class GLDrawableFactory {
                                                                       int width, int height,
                                                                       GLContext shareWith) throws GLException;
   /**
-   * Creates a offscreen {@link GLDrawable} incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
+   * Creates an {@link GLDrawable#isRealized() unrealized} offscreen {@link GLDrawable} 
+   * incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions.
    * <p>
    * In case the passed {@link GLCapabilitiesImmutable} contains default values, i.e.
    * {@link GLCapabilitiesImmutable#isOnscreen() caps.isOnscreen()} <code> == true</code>,
@@ -557,7 +560,8 @@ public abstract class GLDrawableFactory {
    * <code>windowHandle</code>'s native visualID if set or the given {@link GLCapabilitiesImmutable}.
    * </p>
    * <p>
-   * Lifecycle (destruction) of the given surface handle shall be handled by the caller.
+   * Lifecycle (creation and destruction) of the given surface handle shall be handled by the caller
+   * via {@link ProxySurface#createNotify()} and {@link ProxySurface#destroyNotify()}.  
    * </p>
    * <p>
    * Such surface can be used to instantiate a GLDrawable. With the help of {@link GLAutoDrawableDelegate}
diff --git a/src/jogl/classes/jogamp/opengl/GLDrawableFactoryImpl.java b/src/jogl/classes/jogamp/opengl/GLDrawableFactoryImpl.java
index 5c5db6d31..92ec96ad7 100644
--- a/src/jogl/classes/jogamp/opengl/GLDrawableFactoryImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLDrawableFactoryImpl.java
@@ -273,7 +273,7 @@ public abstract class GLDrawableFactoryImpl extends GLDrawableFactory {
                                                              GLCapabilitiesChooser chooser,
                                                              int width, int height,
                                                              GLContext shareWith) {
-    final GLDrawable drawable = createOffscreenDrawable( deviceReq, capsRequested, chooser, width, height ); 
+    final GLDrawable drawable = createOffscreenDrawable( deviceReq, capsRequested, chooser, width, height );
     drawable.setRealized(true);
     final GLContext context = drawable.createContext(shareWith);
     if(drawable instanceof GLFBODrawableImpl) {
@@ -318,13 +318,13 @@ public abstract class GLDrawableFactoryImpl extends GLDrawableFactory {
     }
   }
 
-  /** Creates a platform independent FBO offscreen GLDrawable */ 
+  /** Creates a platform independent unrealized FBO offscreen GLDrawable */ 
   protected GLFBODrawable createFBODrawableImpl(NativeSurface dummySurface, GLCapabilitiesImmutable fboCaps, int textureUnit) {
     final GLDrawableImpl dummyDrawable = createOnscreenDrawableImpl(dummySurface);
     return new GLFBODrawableImpl(this, dummyDrawable, dummySurface, fboCaps, textureUnit);
   }
   
-  /** Creates a platform dependent offscreen pbuffer/pixmap GLDrawable implementation */  
+  /** Creates a platform dependent unrealized offscreen pbuffer/pixmap GLDrawable instance */  
   protected abstract GLDrawableImpl createOffscreenDrawableImpl(NativeSurface target) ;
 
   /**
diff --git a/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
index 59a00170d..6d9116303 100644
--- a/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLOffscreenAutoDrawableImpl.java
@@ -44,8 +44,11 @@ import jogamp.opengl.GLFBODrawableImpl;
 public class GLOffscreenAutoDrawableImpl extends GLAutoDrawableDelegate implements GLOffscreenAutoDrawable {
   
     /**
-     * @param drawable a valid and already realized {@link GLDrawable}
-     * @param context a valid {@link GLContext}, may not be made current (created) yet.
+     * @param drawable a valid {@link GLDrawable}, may not be {@link GLDrawable#isRealized() realized} yet.
+     * @param context a valid {@link GLContext}, 
+     *                may not have been made current (created) yet,
+     *                may not be associated w/ <code>drawable<code> yet,
+     *                may be <code>null</code> for lazy initialization
      * @param upstreamWidget optional UI element holding this instance, see {@link #getUpstreamWidget()}.
      * @param lock optional upstream lock, may be null
      */
@@ -60,8 +63,11 @@ public class GLOffscreenAutoDrawableImpl extends GLAutoDrawableDelegate implemen
     
     public static class FBOImpl extends GLOffscreenAutoDrawableImpl implements GLOffscreenAutoDrawable.FBO {      
         /**
-         * @param drawable a valid and already realized {@link GLDrawable}
-         * @param context a valid {@link GLContext}, may not be made current (created) yet.
+         * @param drawable a valid {@link GLDrawable}, may not be {@link GLDrawable#isRealized() realized} yet.
+         * @param context a valid {@link GLContext}, 
+         *                may not have been made current (created) yet,
+         *                may not be associated w/ <code>drawable<code> yet,
+         *                may be <code>null</code> for lazy initialization
          * @param upstreamWidget optional UI element holding this instance, see {@link #getUpstreamWidget()}.
          * @param lock optional upstream lock, may be null
          */