From d8074fb1df1bdb63fdb97585c797c15d34695e9c Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Tue, 29 Oct 2013 11:13:01 +0100 Subject: GLDrawableFactory: Add 'GLAutoDrawable createDummyAutoDrawable(..)' for convenience Added: GLAutoDrawable createDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp) --- .../javax/media/opengl/GLDrawableFactory.java | 67 +++++++++++++++------- 1 file changed, 45 insertions(+), 22 deletions(-) (limited to 'src/jogl/classes/javax') diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java index 98eb9bdde..3e53a1819 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java @@ -270,7 +270,7 @@ public abstract class GLDrawableFactory { 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. + * @param device which {@link 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 GLDrawable creation. Otherwise false. * This implies validation whether the implementation is functional. * @@ -316,7 +316,7 @@ public abstract class GLDrawableFactory { * This does not imply a shared resource is mapped (ie. made persistent), but is available in general
. *

* - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @return true if a shared resource could been created, otherwise false. */ protected final boolean createSharedResource(AbstractGraphicsDevice device) { @@ -334,7 +334,7 @@ public abstract class GLDrawableFactory { * *

* - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @param quirk the quirk to be tested, e.g. {@link GLRendererQuirks#NoDoubleBufferedPBuffer}. * @throws IllegalArgumentException if the quirk is out of range * @see #getRendererQuirks(AbstractGraphicsDevice) @@ -354,7 +354,7 @@ public abstract class GLDrawableFactory { * In case no shared device exist yet or the implementation doesn't support tracking quirks, * the result is always 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. + * @param device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @see GLContext#getRendererQuirks() * @see GLRendererQuirks */ @@ -413,7 +413,7 @@ public abstract class GLDrawableFactory { * The chosen GLProfile statement in the result may not refer to the maximum available profile * due to implementation constraints, ie using the shared resource. * - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @return A list of {@link javax.media.opengl.GLCapabilitiesImmutable}'s, maybe empty if none is available. */ public final List getAvailableCapabilities(AbstractGraphicsDevice device) { @@ -460,14 +460,14 @@ public abstract class GLDrawableFactory { * @see javax.media.opengl.GLCapabilities#isOnscreen() * @see javax.media.opengl.GLCapabilities#isFBO() * @see javax.media.opengl.GLCapabilities#isPBuffer() - * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, javax.media.nativewindow.CapabilitiesChooser, AbstractGraphicsScreen, int) + * @see GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int) */ public abstract GLDrawable createGLDrawable(NativeSurface target) throws IllegalArgumentException, GLException; /** * Creates a {@link GLDrawable#isRealized() realized} {@link GLOffscreenAutoDrawable} - * incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions. + * incl it's offscreen {@link NativeSurface} with the given capabilites and dimensions. *

* The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is {@link GLDrawable#isRealized() realized} * and it's {@link GLContext} assigned but not yet made current. @@ -491,7 +491,7 @@ public abstract class GLDrawableFactory { * a simple pixmap/bitmap auto drawable 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 device which {@link 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 @@ -512,10 +512,10 @@ public abstract class GLDrawableFactory { /** * Creates a {@link GLDrawable#isRealized() realized} {@link GLOffscreenAutoDrawable} - * incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions. + * incl it's offscreen {@link NativeSurface} with the given capabilites and dimensions. *

* The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is {@link GLDrawable#isRealized() realized} - * without an assigned {@link GLContext}.
+ * without an assigned {@link GLContext}, hence not initialized completely.
* The {@link GLContext} can be assigned later manually via {@link GLAutoDrawable#setContext(GLContext, boolean) setContext(ctx)} * or it will be created lazily at the 1st {@link GLAutoDrawable#display() display()} method call.
* Lazy {@link GLContext} creation will take a shared {@link GLContext} into account @@ -541,12 +541,12 @@ public abstract class GLDrawableFactory { * a simple pixmap/bitmap auto drawable 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 device which {@link 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 and initialized offscreen {@link GLOffscreenAutoDrawable} instance + * @return the created and realized offscreen {@link GLOffscreenAutoDrawable} instance * * @throws GLException if any window system-specific errors caused * the creation of the Offscreen to fail. @@ -558,9 +558,32 @@ public abstract class GLDrawableFactory { GLCapabilitiesChooser chooser, int width, int height) throws GLException; + /** + * Creates a {@link GLDrawable#isRealized() realized} dummy {@link GLAutoDrawable} + * incl it's dummy, invisible {@link NativeSurface} + * as created with {@link #createDummyDrawable(AbstractGraphicsDevice, boolean, GLProfile)}. + *

+ * The dummy {@link GLAutoDrawable}'s {@link GLDrawable} is {@link GLDrawable#isRealized() realized} + * without an assigned {@link GLContext}, hence not initialized completely.
+ * The {@link GLContext} can be assigned later manually via {@link GLAutoDrawable#setContext(GLContext, boolean) setContext(ctx)} + * or it will be created lazily at the 1st {@link GLAutoDrawable#display() display()} method call.
+ * Lazy {@link GLContext} creation will take a shared {@link GLContext} into account + * which has been set {@link GLOffscreenAutoDrawable#setSharedContext(GLContext) directly} + * or {@link GLOffscreenAutoDrawable#setSharedAutoDrawable(GLAutoDrawable) via another GLAutoDrawable}. + *

+ * + * @param deviceReq which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be null for the platform's default device. + * @param createNewDevice if true a new independent device instance is created from the deviceReq, otherwise deviceReq is used as-is and must be valid! + * @param glp the desired {@link GLProfile} + * @return the created and realized dummy {@link GLAutoDrawable} instance + * + * @see #createDummyDrawable(AbstractGraphicsDevice, boolean, GLProfile) + */ + public abstract GLAutoDrawable createDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp); + /** * Creates an {@link GLDrawable#isRealized() unrealized} offscreen {@link GLDrawable} - * incl it's offscreen {@link javax.media.nativewindow.NativeSurface} with the given capabilites and dimensions. + * incl it's offscreen {@link NativeSurface} with the given capabilites and dimensions. *

* In case the passed {@link GLCapabilitiesImmutable} contains default values, i.e. * {@link GLCapabilitiesImmutable#isOnscreen() caps.isOnscreen()} == true, @@ -579,13 +602,13 @@ public abstract class GLDrawableFactory { * a simple pixmap/bitmap drawable 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 device which {@link 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 {@link GLDrawable} + * @return the created unrealized offscreen {@link GLDrawable} * * @throws GLException if any window system-specific errors caused * the creation of the Offscreen to fail. @@ -604,10 +627,10 @@ public abstract class GLDrawableFactory { * It is used to allow the creation of a {@link GLContext} to query information. * It also allows creation of framebuffer objects which are used for rendering or creating a shared GLContext w/o actually rendering to this dummy drawable's framebuffer. *

- * @param deviceReq 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 deviceReq which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be null for the platform's default device. * @param createNewDevice if true a new independent device instance is created from the deviceReq, otherwise deviceReq is used as-is and must be valid! * @param glp the desired {@link GLProfile} - * @return the created dummy {@link GLDrawable} + * @return the created unrealized dummy {@link GLDrawable} */ public abstract GLDrawable createDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp); @@ -628,7 +651,7 @@ public abstract class GLDrawableFactory { * see {@link com.jogamp.opengl.swt.GLCanvas}. *

* - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * Caller has to ensure it is compatible w/ the given windowHandle * @param screenIdx matching screen index of given windowHandle * @param windowHandle the native window handle @@ -651,7 +674,7 @@ public abstract class GLDrawableFactory { * FBO support is queried as described in {@link GLContext#hasBasicFBOSupport()}. *

* - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @param glp {@link GLProfile} to check for FBO capabilities * @see GLContext#hasBasicFBOSupport() */ @@ -664,7 +687,7 @@ public abstract class GLDrawableFactory { * as well as some new GL implementation, i.e. OpenGL 3 core on OSX. *

* - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. * @param glp {@link GLProfile} to check for FBO capabilities */ public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device, GLProfile glp); @@ -678,7 +701,7 @@ public abstract class GLDrawableFactory { * See the note in the overview documentation in {@link GLSharedContextSetter} and 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 device which {@link 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 @@ -733,7 +756,7 @@ public abstract class GLDrawableFactory { * Returns true if it is possible to create an external GLDrawable * object via {@link #createExternalGLDrawable}. * - * @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 device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be null for the platform's default device. */ public abstract boolean canCreateExternalGLDrawable(AbstractGraphicsDevice device); -- cgit v1.2.3