diff options
author | Sven Gothel <sgothel@jausoft.com> | 2013-04-10 03:22:19 +0200 |
---|---|---|
committer | Sven Gothel <sgothel@jausoft.com> | 2013-04-10 03:22:19 +0200 |
commit | 7978096bdaac4c4bd14187382bb1f8ab9d082ebe (patch) | |
tree | a30b3d0384b743b2ff0ad71773ded614dd20bd4f | |
parent | eff09c3545f32f1f481198d57de71a5bf564e797 (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)
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) { |