From 07fb6ebb3fa95e8d722505883a13c62e13c7f953 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sat, 26 Jan 2013 07:43:08 +0100
Subject: 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.
---
src/jogl/classes/javax/media/opengl/GLDrawable.java | 7 ++++++-
src/jogl/classes/javax/media/opengl/GLDrawableFactory.java | 14 +++++++++-----
2 files changed, 15 insertions(+), 6 deletions(-)
(limited to 'src/jogl/classes/javax/media/opengl')
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}
--
cgit v1.2.3