summaryrefslogtreecommitdiffstats
path: root/src/jogl/classes
diff options
context:
space:
mode:
authorSven Gothel <[email protected]>2013-04-10 03:22:19 +0200
committerSven Gothel <[email protected]>2013-04-10 03:22:19 +0200
commit7978096bdaac4c4bd14187382bb1f8ab9d082ebe (patch)
treea30b3d0384b743b2ff0ad71773ded614dd20bd4f /src/jogl/classes
parenteff09c3545f32f1f481198d57de71a5bf564e797 (diff)
GLDrawable: Refine API doc; GLDrawableImpl: Balance createHandle()/destroyHandle(); Handle LOCK_SURFACE_CHANGED in lockSurface() ; GLContextImpl.makeCurrent(): Fix drawable handle validation.
GLDrawable: Refine API doc (realized/handle) - Lifecycle of the drawable handle was not clear - Ephasizing handle's dependency on NativeSurface's lock state and drawable's realization GLDrawableImpl: Balance createHandle()/destroyHandle() - updateHandle() -> createHandle() - ensure both are balance, see below GLDrawableImpl: Handle LOCK_SURFACE_CHANGED in GLDrawableImpl's lockSurface() - call destroyHandle() and createHandle() GLContextImpl.makeCurrent(): Validate drawable handle if realized only. - it is valid to have an invalid drawable handle if not realized (see above)
Diffstat (limited to 'src/jogl/classes')
-rw-r--r--src/jogl/classes/javax/media/opengl/GLDrawable.java70
-rw-r--r--src/jogl/classes/jogamp/opengl/GLContextImpl.java12
-rw-r--r--src/jogl/classes/jogamp/opengl/GLDrawableImpl.java72
-rw-r--r--src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java4
-rw-r--r--src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java4
5 files changed, 107 insertions, 55 deletions
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index 95c314a48..65c8b2ea5 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -65,29 +65,31 @@ public interface GLDrawable {
public GLContext createContext(GLContext shareWith);
/**
- * Indicates to on-screen GLDrawable implementations whether the
- * underlying window has been created and can be drawn into. End
- * users do not need to call this method; it is not necessary to
- * call <code>setRealized</code> on a GLCanvas, a GLJPanel, or a
- * GLPbuffer, as these perform the appropriate calls on their
- * underlying GLDrawables internally.
- *
- * <P>
- *
+ * Indicates to GLDrawable implementations whether the
+ * underlying {@link NativeSurface surface} has been created and can be drawn into.
+ * <p>
+ * If realized, the {@link #getHandle() drawable handle} may become
+ * valid while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
+ * </p>
+ * <p>
+ * End users do not need to call this method; it is not necessary to
+ * call <code>setRealized</code> on a {@link GLAutoDrawable}
+ * as these perform the appropriate calls on their underlying GLDrawables internally.
+ * </p>
+ * <p>
* Developers implementing new OpenGL components for various window
* toolkits need to call this method against GLDrawables obtained
- * from the GLDrawableFactory via the {@link
- * GLDrawableFactory#getGLDrawable
- * GLDrawableFactory.getGLDrawable()} method. It must typically be
+ * from the GLDrawableFactory via the
+ * {@link GLDrawableFactory#createGLDrawable(NativeSurface)} method.
+ * It must typically be
* called with an argument of <code>true</code> when the component
* associated with the GLDrawable is realized and with an argument
* of <code>false</code> just before the component is unrealized.
* For the AWT, this means calling <code>setRealized(true)</code> in
* the <code>addNotify</code> method and with an argument of
* <code>false</code> in the <code>removeNotify</code> method.
- *
- * <P>
- *
+ * </p>
+ * <p>
* <code>GLDrawable</code> implementations should handle multiple
* cycles of <code>setRealized(true)</code> /
* <code>setRealized(false)</code> calls. Most, if not all, Java
@@ -101,12 +103,11 @@ public interface GLDrawable {
* <code>GLDrawable</code> to re-initialize and destroy any
* associated resources as the component becomes realized and
* unrealized, respectively.
- *
- * <P>
- *
+ * </p>
+ * <p>
* With an argument of <code>true</code>,
* the minimum implementation shall call
- * {@link NativeSurface#lockSurface() NativeSurface's lockSurface()} and if successfull:
+ * {@link NativeSurface#lockSurface() NativeSurface's lockSurface()} and if successful:
* <ul>
* <li> Update the {@link GLCapabilities}, which are associated with
* the attached {@link NativeSurface}'s {@link AbstractGraphicsConfiguration}.</li>
@@ -115,14 +116,17 @@ public interface GLDrawable {
* This is important since {@link NativeSurface#lockSurface() NativeSurface's lockSurface()}
* ensures resolving the window/surface handles, and the drawable's {@link GLCapabilities}
* might have changed.
- *
- * <P>
- *
+ * </p>
+ * <p>
* Calling this method has no other effects. For example, if
* <code>removeNotify</code> is called on a Canvas implementation
* for which a GLDrawable has been created, it is also necessary to
* destroy all OpenGL contexts associated with that GLDrawable. This
* is not done automatically by the implementation.
+ * </p>
+ * @see #isRealized()
+ * @see #getHandle()
+ * @see NativeSurface#lockSurface()
*/
public void setRealized(boolean realized);
@@ -131,6 +135,7 @@ public interface GLDrawable {
* <p>
* A drawable can be realized and unrealized via {@link #setRealized(boolean)}.
* </p>
+ * @see #setRealized(boolean)
*/
public boolean isRealized();
@@ -172,11 +177,22 @@ public interface GLDrawable {
public NativeSurface getNativeSurface();
/**
- * This is the GL/Windowing drawable handle.<br>
- * It is usually the {@link javax.media.nativewindow.NativeSurface#getSurfaceHandle()},
- * ie the native surface handle of the underlying windowing toolkit.<br>
- * However, on X11/GLX this reflects a GLXDrawable, which represents a GLXWindow, GLXPixmap, or GLXPbuffer.<br>
- * On EGL, this represents the EGLSurface.<br>
+ * Returns the GL drawable handle,
+ * guaranteed to be valid after {@link #setRealized(boolean) realization}
+ * <i>and</i> while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
+ * <p>
+ * It is usually identical to the underlying windowing toolkit {@link NativeSurface surface}'s
+ * {@link javax.media.nativewindow.NativeSurface#getSurfaceHandle() handle}
+ * or an intermediate layer to suite GL, e.g. an EGL surface.
+ * </p>
+ * <p>
+ * On EGL it is represented by the EGLSurface.<br>
+ * On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.<br>
+ * On Windows it is represented by the HDC, which may change with each {@link #lockSurface()}.<br>
+ * </p>
+ * @see #setRealized(boolean)
+ * @see NativeSurface#lockSurface()
+ * @see NativeSurface#unlockSurface()
*/
public long getHandle();
diff --git a/src/jogl/classes/jogamp/opengl/GLContextImpl.java b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
index 64ade3eff..90f5a9907 100644
--- a/src/jogl/classes/jogamp/opengl/GLContextImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLContextImpl.java
@@ -258,7 +258,7 @@ public abstract class GLContextImpl extends GLContext {
if(DEBUG) {
String sgl1 = (null!=this.gl)?this.gl.getClass().getSimpleName()+", "+this.gl.toString():"<null>";
String sgl2 = (null!=gl)?gl.getClass().getSimpleName()+", "+gl.toString():"<null>";
- Exception e = new Exception("Info: setGL (OpenGL "+getGLVersion()+"): "+Thread.currentThread().getName()+", "+sgl1+" -> "+sgl2);
+ Exception e = new Exception("Info: setGL (OpenGL "+getGLVersion()+"): "+getThreadName()+", "+sgl1+" -> "+sgl2);
e.printStackTrace();
}
this.gl = gl;
@@ -495,14 +495,10 @@ public abstract class GLContextImpl extends GLContext {
boolean unlockContextAndSurface = true; // Must be cleared if successful, otherwise finally block will release context and surface!
int res = CONTEXT_NOT_CURRENT;
try {
- if (0 == drawable.getHandle()) {
- throw new GLException("drawable has invalid handle: "+drawable);
- }
- if (NativeSurface.LOCK_SURFACE_CHANGED == lockRes) {
- drawable.updateHandle();
- }
-
if ( drawable.isRealized() ) {
+ if ( 0 == drawable.getHandle() ) {
+ throw new GLException("drawable has invalid handle: "+drawable);
+ }
lock.lock();
try {
// One context can only be current by one thread,
diff --git a/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java b/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
index d0c1461a9..a2b99c7da 100644
--- a/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
+++ b/src/jogl/classes/jogamp/opengl/GLDrawableImpl.java
@@ -79,14 +79,11 @@ public abstract class GLDrawableImpl implements GLDrawable {
if( !realized ) { // volatile OK (locked below)
return; // destroyed already
}
- int lockRes = lockSurface(); // it's recursive, so it's ok within [makeCurrent .. release]
+ final int lockRes = lockSurface(); // it's recursive, so it's ok within [makeCurrent .. release]
if (NativeSurface.LOCK_SURFACE_NOT_READY == lockRes) {
return;
}
try {
- if (NativeSurface.LOCK_SURFACE_CHANGED == lockRes) {
- updateHandle();
- }
if( realized ) { // volatile OK
final GLCapabilitiesImmutable caps = (GLCapabilitiesImmutable)surface.getGraphicsConfiguration().getChosenCapabilities();
if ( caps.getDoubleBuffered() ) {
@@ -145,11 +142,21 @@ public abstract class GLDrawableImpl implements GLDrawable {
return surface;
}
- /** called with locked surface @ setRealized(false) */
+ /**
+ * called with locked surface @ setRealized(false) or @ lockSurface(..) when surface changed
+ * <p>
+ * Must be paired w/ {@link #createHandle()}.
+ * </p>
+ */
protected void destroyHandle() {}
- /** called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed */
- protected void updateHandle() {}
+ /**
+ * called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed
+ * <p>
+ * Must be paired w/ {@link #destroyHandle()}.
+ * </p>
+ */
+ protected void createHandle() {}
@Override
public long getHandle() {
@@ -174,7 +181,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
if(isProxySurface) {
((ProxySurface)surface).createNotify();
}
- if(NativeSurface.LOCK_SURFACE_NOT_READY >= lockSurface()) {
+ if(NativeSurface.LOCK_SURFACE_NOT_READY >= surface.lockSurface()) {
throw new GLException("GLDrawableImpl.setRealized(true): Surface not ready (lockSurface)");
}
} else {
@@ -185,7 +192,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
realized = realizedArg;
if(realizedArg) {
setRealizedImpl();
- updateHandle();
+ createHandle();
} else {
destroyHandle();
setRealizedImpl();
@@ -193,7 +200,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
}
} finally {
if(realizedArg) {
- unlockSurface();
+ surface.unlockSurface();
} else {
aDevice.unlock();
if(isProxySurface) {
@@ -276,12 +283,47 @@ public abstract class GLDrawableImpl implements GLDrawable {
return surface.getHeight();
}
- /** @see NativeSurface#lockSurface() */
+ /**
+ * {@link NativeSurface#lockSurface() Locks} the underlying windowing toolkit's {@link NativeSurface surface}.
+ * <p>
+ * <i>If</i> drawable is {@link #setRealized(boolean) realized},
+ * the {@link #getHandle() drawable handle} is valid after successfully {@link NativeSurface#lockSurface() locking}
+ * it's {@link NativeSurface surface} until being {@link #unlockSurface() unlocked}.
+ * </p>
+ * <p>
+ * In case the {@link NativeSurface surface} has changed as indicated by it's
+ * {@link NativeSurface#lockSurface() lock} result {@link NativeSurface#LOCK_SURFACE_CHANGED},
+ * the implementation is required to update this information as needed within it's implementation.
+ * </p>
+ *
+ * @see NativeSurface#lockSurface()
+ * @see #getHandle()
+ */
public final int lockSurface() throws GLException {
- return surface.lockSurface();
+ final int lockRes = surface.lockSurface();
+ if ( NativeSurface.LOCK_SURFACE_CHANGED == lockRes && realized ) {
+ // Update the drawable handle, in case the surface handle has changed.
+ final long _handle1 = getHandle();
+ destroyHandle();
+ createHandle();
+ final long _handle2 = getHandle();
+ if(DEBUG) {
+ if( _handle1 != _handle2) {
+ System.err.println(getThreadName() + ": Drawable handle changed: "+toHexString(_handle1)+" -> "+toHexString(_handle2));
+ }
+ }
+ }
+ return lockRes;
+
}
- /** @see NativeSurface#unlockSurface() */
+ /**
+ * {@link NativeSurface#unlockSurface() Unlocks} the underlying windowing toolkit {@link NativeSurface surface},
+ * which may render the {@link #getHandle() drawable handle} invalid.
+ *
+ * @see NativeSurface#unlockSurface()
+ * @see #getHandle()
+ */
public final void unlockSurface() {
surface.unlockSurface();
}
@@ -294,9 +336,7 @@ public abstract class GLDrawableImpl implements GLDrawable {
",\n\tSurface "+getNativeSurface()+"]";
}
- protected static String getThreadName() {
- return Thread.currentThread().getName();
- }
+ protected static String getThreadName() { return Thread.currentThread().getName(); }
protected GLDrawableFactory factory;
protected NativeSurface surface;
diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java b/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
index 167eebf3a..2edf26145 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLDrawable.java
@@ -100,10 +100,10 @@ public abstract class EGLDrawable extends GLDrawableImpl {
}
@Override
- protected final void updateHandle() {
+ protected final void createHandle() {
final EGLWrappedSurface eglws = (EGLWrappedSurface) surface;
if(DEBUG) {
- System.err.println(getThreadName() + ": updateHandle of "+eglws);
+ System.err.println(getThreadName() + ": createHandle of "+eglws);
}
if( eglws.containsUpstreamOptionBits( ProxySurface.OPT_PROXY_OWNS_UPSTREAM_SURFACE ) ) {
if( EGL.EGL_NO_SURFACE != eglws.getSurfaceHandle() ) {
diff --git a/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java b/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
index c15065cfa..6b239a43d 100644
--- a/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
+++ b/src/jogl/classes/jogamp/opengl/x11/glx/X11OnscreenGLXDrawable.java
@@ -56,7 +56,7 @@ public class X11OnscreenGLXDrawable extends X11GLXDrawable {
glXWindow=0;
useGLXWindow=false;
if(realized) {
- updateHandle();
+ createHandle();
}
}
@@ -82,7 +82,7 @@ public class X11OnscreenGLXDrawable extends X11GLXDrawable {
}
@Override
- protected final void updateHandle() {
+ protected final void createHandle() {
if(USE_GLXWINDOW) {
X11GLXGraphicsConfiguration config = (X11GLXGraphicsConfiguration)getNativeSurface().getGraphicsConfiguration();
if(config.getFBConfig()>=0) {