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.

2 files changed, 13 insertions, 7 deletions

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
          */