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, 15 insertions, 6 deletions

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}