From 4b9ad2508ff31a03d3bc4482d812a6cbc0c5c33b Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Fri, 3 Dec 2010 21:32:16 +0100 Subject: Cleanup GLDrawableFactory API and platform Implementations - Finish API change using the AbstractGraphicsDevice, which denotes the target device for the desired NativeSurface / GLDrawable. The AbstractGraphicsDevice argument may be null to reflect the platform's default device. Clarified API documentation. This move is necessary to make the API coherent. - createOffscreenDrawable(..) may create a Pbuffer drawable if caps and supported. This unifies the functionality with createGLDrawable(..). Further more, a Pbuffer drawable is an offscreen as well. - added createOffscreenSurface(..) following the same behavior as createOffscreenDrawable(..), this is a convenient native offscreen surface factory entry. - removed createGLPbufferDrawable(..), use createOffscreenDrawable(..), since it is redundant! Implementation Details: - EGLDrawableFactory holds a shared native EGLGraphicsDevice, being used by the offscreen EGL drawable (no more multiple creation). --- .../javax/media/opengl/GLDrawableFactory.java | 85 ++++++++++++++++------ .../classes/javax/media/opengl/awt/GLJPanel.java | 4 +- 2 files changed, 64 insertions(+), 25 deletions(-) (limited to 'src/jogl/classes/javax/media') diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java index fd6aa7859..f9591e84d 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java @@ -224,13 +224,15 @@ public abstract class GLDrawableFactory { protected abstract void shutdownInstance(); /** - * Retrieve the default device {@link AbstractGraphicsDevice#getConnection()}. for this factory
- * The implementation must return a non null default device, which must not be opened, ie. it's native handle may be null. + * Retrieve the default device {@link AbstractGraphicsDevice#getConnection() connection}, + * {@link AbstractGraphicsDevice#getUnitID() unit ID} and {@link AbstractGraphicsDevice#getUniqueID() unique ID name}. for this factory
+ * The implementation must return a non null default device, which must not be opened, ie. it's native handle is null. * @return the default shared device for this factory, eg. :0.0 on X11 desktop. */ public abstract AbstractGraphicsDevice getDefaultDevice(); /** + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @return true if the device is compatible with this factory, ie. if it can be used for creation. Otherwise false. */ public abstract boolean getIsDeviceCompatible(AbstractGraphicsDevice device); @@ -240,7 +242,7 @@ public abstract class GLDrawableFactory { * or if a new shared context could be created and mapped. Otherwise return false.
* Creation of the shared context is tried only once. * - * @param device if null, the platform default device is being used + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. */ public final boolean getIsSharedContextAvailable(AbstractGraphicsDevice device) { return null != getOrCreateSharedContext(device); @@ -251,7 +253,7 @@ public abstract class GLDrawableFactory { * either a preexisting or newly created, or null if creation failed or not supported.
* Creation of the shared context is tried only once. * - * @param device if null, the platform default device is being used + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. */ protected final GLContext getOrCreateSharedContext(AbstractGraphicsDevice device) { if(null==device) { @@ -306,12 +308,12 @@ public abstract class GLDrawableFactory { * The native platform's chosen Capabilties are referenced within the target * NativeSurface's AbstractGraphicsConfiguration.

* - * In case {@link javax.media.nativewindow.Capabilities#isOnscreen()} is true,
+ * In case target's {@link javax.media.nativewindow.Capabilities#isOnscreen()} is true,
* an onscreen GLDrawable will be realized. *

- * In case {@link javax.media.nativewindow.Capabilities#isOnscreen()} is false,
- * either a Pbuffer drawable is created if {@link javax.media.opengl.GLCapabilities#isPBuffer()} is true,
- * or a simple offscreen drawable is creates. The latter is unlikely to be hardware accelerated.
+ * In case target's {@link javax.media.nativewindow.Capabilities#isOnscreen()} is false,
+ * either a Pbuffer drawable is created if target's {@link javax.media.opengl.GLCapabilities#isPBuffer()} is true,
+ * or a simple pixmap/bitmap drawable is created. The latter is unlikely to be hardware accelerated.
*

* * @throws IllegalArgumentException if the passed target is null @@ -324,34 +326,58 @@ public abstract class GLDrawableFactory { throws IllegalArgumentException, GLException; /** - * Creates a Offscreen GLDrawable with the given capabilites and dimensions.

+ * Creates a Offscreen GLDrawable incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions. + *

+ * A Pbuffer drawable/surface is created if both {@link javax.media.opengl.GLCapabilities#isPBuffer() caps.isPBuffer()} + * and {@link #canCreateGLPbuffer(javax.media.nativewindow.AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
+ * Otherwise a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.
+ *

+ * + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be null for the platform's default device. + * @param caps the requested GLCapabilties + * @param chooser the custom chooser, may be null for default + * @param width the requested offscreen width + * @param height the requested offscreen height + * + * @return the created offscreen GLDrawable * * @throws GLException if any window system-specific errors caused * the creation of the Offscreen to fail. */ - public abstract GLDrawable createOffscreenDrawable(GLCapabilitiesImmutable capabilities, + public abstract GLDrawable createOffscreenDrawable(AbstractGraphicsDevice device, + GLCapabilitiesImmutable capabilities, GLCapabilitiesChooser chooser, int width, int height) throws GLException; /** - * Returns true if it is possible to create a GLPbuffer. Some older - * graphics cards do not have this capability. - * @param passing the device for the query, may be null + * Creates an offscreen NativeSurface.
+ * A Pbuffer surface is created if both {@link javax.media.opengl.GLCapabilities#isPBuffer() caps.isPBuffer()} + * and {@link #canCreateGLPbuffer(javax.media.nativewindow.AbstractGraphicsDevice) canCreateGLPbuffer(device)} is true.
+ * Otherwise a simple pixmap/bitmap surface is created. The latter is unlikely to be hardware accelerated.
+ * + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. + * @param caps the requested GLCapabilties + * @param chooser the custom chooser, may be null for default + * @param width the requested offscreen width + * @param height the requested offscreen height + * @return the created offscreen native surface + * + * @throws GLException if any window system-specific errors caused + * the creation of the GLDrawable to fail. */ - public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device); + public abstract NativeSurface createOffscreenSurface(AbstractGraphicsDevice device, + GLCapabilitiesImmutable caps, + GLCapabilitiesChooser chooser, + int width, int height); /** - * Creates a Pbuffer GLDrawable with the given capabilites and dimensions.

+ * Returns true if it is possible to create a GLPbuffer. Some older + * graphics cards do not have this capability. * - * @throws GLException if any window system-specific errors caused - * the creation of the GLPbuffer to fail. + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. */ - public abstract GLDrawable createGLPbufferDrawable(GLCapabilitiesImmutable capabilities, - GLCapabilitiesChooser chooser, - int initialWidth, - int initialHeight) - throws GLException; + public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device); /** * Creates a GLPbuffer with the given capabilites and dimensions.

@@ -359,10 +385,20 @@ public abstract class GLDrawableFactory { * See the note in the overview documentation on * context sharing. * + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. + * @param capabilities the requested capabilities + * @param chooser the custom chooser, may be null for default + * @param initialWidth initial width of pbuffer + * @param initialHeight initial height of pbuffer + * @param shareWith a shared GLContext this GLPbuffer shall use + * + * @return the new {@link GLPbuffer} specific {@link GLAutoDrawable} + * * @throws GLException if any window system-specific errors caused * the creation of the GLPbuffer to fail. */ - public abstract GLPbuffer createGLPbuffer(GLCapabilitiesImmutable capabilities, + public abstract GLPbuffer createGLPbuffer(AbstractGraphicsDevice device, + GLCapabilitiesImmutable capabilities, GLCapabilitiesChooser chooser, int initialWidth, int initialHeight, @@ -400,7 +436,8 @@ public abstract class GLDrawableFactory { /** * Returns true if it is possible to create an external GLDrawable * object via {@link #createExternalGLDrawable}. - * @param passing the device for the query, may be null + * + * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. */ public abstract boolean canCreateExternalGLDrawable(AbstractGraphicsDevice device); diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java index 5c6be8bc4..c8bfe94d8 100644 --- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java +++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java @@ -966,6 +966,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable { public void initialize() { // Fall-through path: create an offscreen context instead offscreenDrawable = (GLDrawableImpl) factory.createOffscreenDrawable( + null /* default platform device */, offscreenCaps, chooser, Math.max(1, panelWidth), @@ -1051,7 +1052,8 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable { throw new InternalError("Creating pbuffer twice without destroying it (memory leak / correctness bug)"); } try { - pbuffer = factory.createGLPbuffer(offscreenCaps, + pbuffer = factory.createGLPbuffer(null /* default platform device */, + offscreenCaps, null, pbufferWidth, pbufferHeight, -- cgit v1.2.3