Bug 1031: Remove Deprecated Classes and Methods (JOGL)

Removed Deprecated Class:
  - com/jogamp/opengl/util/TGAWriter.java
    - Use TextureIO w/ .tga suffix

  - com/jogamp/opengl/util/awt/Screenshot.java
    - Use:
      - com.jogamp.opengl.util.GLReadBufferUtil, or
      - com.jogamp.opengl.util.awt.AWTGLReadBufferUtil
      The latter for reading into AWT BufferedImage

      See: TestBug461FBOSupersamplingSwingAWT, TestBug605FlippedImageAWT

  - javax/media/opengl/GLPbuffer.java
    - Use:
      caps.setPBuffer(true);
      final GLAutoDrawable pbuffer = GLDrawableFactory.getFactory( caps.getGLProfile() ).createOffscreenAutoDrawable(null, caps, null, 512, 512);
    - See: TestPBufferDeadlockAWT, ..

Removed Deprecated Methods:
  - Constructor of AWT-GLCanvas, SWT-GLCanvas, AWT-GLJPanel
    with argument 'final GLContext shareWith'
    See GLSharedContextSetter, i.e. glCanvas.setSharedContext(..) !

  - GLDrawableFactory.createOffscreenAutoDrawable(..)
    with argument 'final GLContext shareWith'
    See GLSharedContextSetter, i.e. offscreenAutoDrawable.setSharedContext(..) !

  - GLDrawableFactory.createGLPbuffer(..),
    see above!

  - com.jogamp.opengl.util.av.AudioSink 'enqueueData(AudioDataFrame audioDataFrame)',
    use 'enqueueData(int, ByteBuffer, int)'

  - GLSharedContextSetter.areAllGLEventListenerInitialized(),
    migrated to GLAutoDrawable !

  - GLBase's
    - glGetBoundBuffer(int), use getBoundBuffer(int)
    - glGetBufferSize(int), use getBufferStorage(int).getSize()
    - glIsVBOArrayBound(), use isVBOArrayBound()
    - glIsVBOElementArrayBound(), use isVBOElementArrayBound()

  - NEWT MouseEvent.BUTTON_NUMBER, use BUTTON_COUNT

8 files changed, 59 insertions, 258 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index bf8fe65ac..377dce190 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -199,6 +199,11 @@ public interface GLAutoDrawable extends GLDrawable {
   public int getGLEventListenerCount();
 
   /**
+   * Returns true if all added {@link GLEventListener} are initialized, otherwise false.
+   */
+  boolean areAllGLEventListenerInitialized();
+
+  /**
    * Returns the {@link GLEventListener} at the given index of this drawable queue.
    * @param index Position of the listener to be returned.
    *              Should be within (0 <= index && index < size()).
diff --git a/src/jogl/classes/javax/media/opengl/GLBase.java b/src/jogl/classes/javax/media/opengl/GLBase.java
index c808399b8..48455c525 100644
--- a/src/jogl/classes/javax/media/opengl/GLBase.java
+++ b/src/jogl/classes/javax/media/opengl/GLBase.java
@@ -505,10 +505,6 @@ public interface GLBase {
    public void glDepthRange(double zNear, double zFar);
 
    /**
-    * @deprecated Avoid original GL API namespace conflict. Use {@link #getBoundBuffer(int)}
-    */
-   public int glGetBoundBuffer(int target);
-   /**
     * @param target a GL buffer (VBO) target as used in {@link GL#glBindBuffer(int, int)}, ie {@link GL#GL_ELEMENT_ARRAY_BUFFER}, {@link GL#GL_ARRAY_BUFFER}, ..
     * @return the GL buffer name bound to a target via {@link GL#glBindBuffer(int, int)} or 0 if unbound.
     * @see #getBufferStorage(int)
@@ -516,10 +512,6 @@ public interface GLBase {
    public int getBoundBuffer(int target);
 
    /**
-    * @deprecated Use {@link #getBufferStorage(int)}.
-    */
-   public long glGetBufferSize(int bufferName);
-   /**
     * @param bufferName a GL buffer name, generated with e.g. {@link GL#glGenBuffers(int, int[], int)} and used in {@link GL#glBindBuffer(int, int)}, {@link GL#glBufferData(int, long, java.nio.Buffer, int)} or {@link GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int)}.
     * @return the size of the given GL buffer storage, see {@link GLBufferStorage}
     * @see #getBoundBuffer(int)
@@ -580,19 +572,11 @@ public interface GLBase {
    public GLBufferStorage mapBufferRange(final int target, final long offset, final long length, final int access) throws GLException;
 
    /**
-    * @deprecated Avoid original GL API namespace conflict. Use {@link #isVBOArrayBound()}
-    */
-   public boolean glIsVBOArrayBound();
-   /**
     * @return true if a VBO is bound to {@link GL#GL_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
     */
    public boolean isVBOArrayBound();
 
    /**
-    * @deprecated Avoid original GL API namespace conflict. Use {@link #isVBOElementArrayBound()}
-    */
-   public boolean glIsVBOElementArrayBound();
-   /**
     * @return true if a VBO is bound to {@link GL#GL_ELEMENT_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
     */
    public boolean isVBOElementArrayBound();
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index 6e7caf8f8..82808a3cb 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -59,10 +59,10 @@ import javax.media.nativewindow.UpstreamSurfaceHook;
 
 import jogamp.opengl.Debug;
 
-/** <P> Provides a virtual machine- and operating system-independent
-    mechanism for creating {@link GLDrawable}s. </P>
-
-    <P> The {@link javax.media.opengl.GLCapabilities} objects passed
+/** <p> Provides a virtual machine- and operating system-independent
+    mechanism for creating {@link GLDrawable}s.
+    </p>
+    <p> The {@link javax.media.opengl.GLCapabilities} objects passed
     in to the various factory methods are used as a hint for the
     properties of the returned drawable. The default capabilities
     selection algorithm (equivalent to passing in a null {@link
@@ -72,9 +72,10 @@ import jogamp.opengl.Debug;
     GLCapabilitiesChooser} which can select from the available pixel
     formats. The GLCapabilitiesChooser mechanism may not be supported
     by all implementations or on all platforms, in which case any
-    passed GLCapabilitiesChooser will be ignored. </P>
+    passed GLCapabilitiesChooser will be ignored.
+    </p>
 
-    <P> Because of the multithreaded nature of the Java platform's
+    <p> Because of the multithreaded nature of the Java platform's
     Abstract Window Toolkit, it is typically not possible to immediately
     reject a given {@link GLCapabilities} as being unsupportable by
     either returning <code>null</code> from the creation routines or
@@ -83,14 +84,15 @@ import jogamp.opengl.Debug;
     implementation will cause a {@link GLException} to be raised
     during the first repaint of the {@link javax.media.opengl.awt.GLCanvas} or {@link
     javax.media.opengl.awt.GLJPanel} if the capabilities can not be met.<br>
-    {@link javax.media.opengl.GLPbuffer} are always
-    created immediately and their creation will fail with a
-    {@link javax.media.opengl.GLException} if errors occur. </P>
+    {@link GLOffscreenAutoDrawable} are created lazily,
+    see {@link #createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int) createOffscreenAutoDrawable(..)}.
+    </p>
 
-    <P> The concrete GLDrawableFactory subclass instantiated by {@link
+    <p> The concrete GLDrawableFactory subclass instantiated by {@link
     #getFactory getFactory} can be changed by setting the system
     property <code>opengl.factory.class.name</code> to the
-    fully-qualified name of the desired class. </P>
+    fully-qualified name of the desired class.
+    </p>
 */
 public abstract class GLDrawableFactory {
 
@@ -474,57 +476,11 @@ public abstract class GLDrawableFactory {
    * incl it's offscreen {@link NativeSurface} with the given capabilites and dimensions.
    * <p>
    * 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.
-   * {@link GLCapabilitiesImmutable#isOnscreen() caps.isOnscreen()} <code> == true</code>,
-   * it is auto-configured. Auto configuration will set {@link GLCapabilitiesImmutable caps} to offscreen
-   * and FBO <i>or</i> Pbuffer, whichever is available in that order.
-   * </p>
-   * <p>
-   * A FBO based auto drawable, {@link GLOffscreenAutoDrawable.FBO}, is created if both {@link GLCapabilitiesImmutable#isFBO() caps.isFBO()}
-   * and {@link GLContext#isFBOAvailable(AbstractGraphicsDevice, GLProfile) canCreateFBO(device, caps.getGLProfile())} is true.
-   * </p>
-   * <p>
-   * A Pbuffer based auto drawable is created if both {@link GLCapabilitiesImmutable#isPBuffer() caps.isPBuffer()}
-   * and {@link #canCreateGLPbuffer(AbstractGraphicsDevice, GLProfile) canCreateGLPbuffer(device)} is true.
-   * </p>
-   * <p>
-   * If neither FBO nor Pbuffer is available,
-   * a simple pixmap/bitmap auto drawable is created, which is unlikely to be hardware accelerated.
-   * </p>
-   * <p>
-   * The resulting {@link GLOffscreenAutoDrawable} has it's own independent device instance using <code>device</code> details.
-   * </p>
-   *
-   * @param device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared device to be used, may be <code>null</code> 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
-   *
-   * @throws GLException if any window system-specific errors caused
-   *         the creation of the Offscreen to fail.
-   *
-   * @see #createOffscreenDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int)
-   * @deprecated Use {@link #createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int)
-   */
-  public abstract GLOffscreenAutoDrawable createOffscreenAutoDrawable(AbstractGraphicsDevice device,
-                                                                      GLCapabilitiesImmutable caps,
-                                                                      GLCapabilitiesChooser chooser,
-                                                                      int width, int height,
-                                                                      GLContext shareWith) throws GLException;
-
-  /**
-   * Creates a {@link GLDrawable#isRealized() realized} {@link GLOffscreenAutoDrawable}
-   * incl it's offscreen {@link NativeSurface} with the given capabilites and dimensions.
-   * <p>
-   * The {@link GLOffscreenAutoDrawable}'s {@link GLDrawable} is {@link GLDrawable#isRealized() realized}
    * <i>without</i> an assigned {@link GLContext}, hence not initialized completely.<br>
+   *
    * The {@link GLContext} can be assigned later manually via {@link GLAutoDrawable#setContext(GLContext, boolean) setContext(ctx)}
    * <i>or</i> it will be created <i>lazily</i> at the 1st {@link GLAutoDrawable#display() display()} method call.<br>
+   *
    * <i>Lazy</i> {@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}.
@@ -716,38 +672,6 @@ public abstract class GLDrawableFactory {
    */
   public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device, GLProfile glp);
 
-  /**
-   * Creates a GLPbuffer {@link GLAutoDrawable} with the given capabilites and dimensions.
-   * <p>
-   * The GLPbuffer drawable is realized and initialized eagerly.
-   * </p>
-   *
-   * See the note in the overview documentation in {@link GLSharedContextSetter} and on
-   * <a href="../../../spec-overview.html#SHARING">context sharing</a>.
-   *
-   * @param device which {@link AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> 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 created and initialized {@link GLPbuffer} instance
-   *
-   * @throws GLException if any window system-specific errors caused
-   *         the creation of the GLPbuffer to fail.
-   *
-   * @deprecated {@link GLPbuffer} is deprecated, use {@link #createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext)}
-   */
-  public abstract GLPbuffer createGLPbuffer(AbstractGraphicsDevice device,
-                                            GLCapabilitiesImmutable capabilities,
-                                            GLCapabilitiesChooser chooser,
-                                            int initialWidth,
-                                            int initialHeight,
-                                            GLContext shareWith)
-    throws GLException;
-
-
   //----------------------------------------------------------------------
   // Methods for interacting with third-party OpenGL libraries
 
diff --git a/src/jogl/classes/javax/media/opengl/GLPbuffer.java b/src/jogl/classes/javax/media/opengl/GLPbuffer.java
deleted file mode 100644
index f36a4bf29..000000000
--- a/src/jogl/classes/javax/media/opengl/GLPbuffer.java
+++ /dev/null
@@ -1,62 +0,0 @@
-/*
- * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are
- * met:
- *
- * - Redistribution of source code must retain the above copyright
- *   notice, this list of conditions and the following disclaimer.
- *
- * - Redistribution in binary form must reproduce the above copyright
- *   notice, this list of conditions and the following disclaimer in the
- *   documentation and/or other materials provided with the distribution.
- *
- * Neither the name of Sun Microsystems, Inc. or the names of
- * contributors may be used to endorse or promote products derived from
- * this software without specific prior written permission.
- *
- * This software is provided "AS IS," without a warranty of any kind. ALL
- * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
- * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
- * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
- * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
- * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
- * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
- * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
- * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
- * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
- * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
- * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
- *
- * You acknowledge that this software is not designed or intended for use
- * in the design, construction, operation or maintenance of any nuclear
- * facility.
- *
- * Sun gratefully acknowledges that this software was originally authored
- * and developed by Kenneth Bradley Russell and Christopher John Kline.
- */
-
-package javax.media.opengl;
-
-/** Provides offscreen rendering support via pbuffers. The principal
-    addition of this interface is a {@link #destroy} method to
-    deallocate the pbuffer and its associated resources. It also
-    contains experimental methods for accessing the pbuffer's contents
-    as a texture map and enabling rendering to floating-point frame
-    buffers. These methods are not guaranteed to be supported on all
-    platforms and may be deprecated in a future release.
-
-    @deprecated Use {@link GLOffscreenAutoDrawable} w/ {@link GLCapabilities#setFBO(boolean)}
-                via {@link GLDrawableFactory#createOffscreenAutoDrawable(javax.media.nativewindow.AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext) GLDrawableFactory.createOffscreenAutoDrawable(..)}.
-  */
-public interface GLPbuffer extends GLAutoDrawable {
-  /** Destroys the native resources associated with this pbuffer. It
-      is not valid to call display() or any other routines on this
-      pbuffer after it has been destroyed. Before destroying the
-      pbuffer, the application must destroy any additional OpenGL
-      contexts which have been created for the pbuffer via {@link
-      #createContext}. */
-  @Override
-  public void destroy();
-}
diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
index 2ea4e4cd6..11ed648c2 100644
--- a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
+++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
@@ -99,12 +99,6 @@ package javax.media.opengl;
  */
 public interface GLSharedContextSetter extends GLAutoDrawable {
     /**
-     * Returns true if all {@link GLEventListener} are initialized, otherwise false.
-     * @deprecated Promote method to {@link GLAutoDrawable}
-     */
-    boolean areAllGLEventListenerInitialized();
-
-    /**
      * Specifies an {@link GLContext OpenGL context}, which shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
      * <p>
      * Since the {@link GLDrawable drawable} and {@link GLContext context} is created
diff --git a/src/jogl/classes/javax/media/opengl/Threading.java b/src/jogl/classes/javax/media/opengl/Threading.java
index 3ee233303..6c64cbe31 100644
--- a/src/jogl/classes/javax/media/opengl/Threading.java
+++ b/src/jogl/classes/javax/media/opengl/Threading.java
@@ -129,8 +129,8 @@ public class Threading {
         consequences and are prepared to enforce some amount of
         threading restrictions in their applications. Disabling
         single-threading, for example, may have unintended consequences
-        on GLAutoDrawable implementations such as GLCanvas, GLJPanel and
-        GLPbuffer. Currently there is no supported way to re-enable it
+        on GLAutoDrawable implementations such as GLCanvas and GLJPanel.
+        Currently there is no supported way to re-enable it
         once disabled, partly to discourage careless use of this
         method. This method should be called as early as possible in an
         application. */
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index ec834e02f..2d5e12429 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -155,6 +155,11 @@ import jogamp.opengl.awt.AWTTilePainter;
  * <ul>
  *   <li><pre>sun.awt.noerasebackground=true</pre></li>
  * </ul>
+ *
+ * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+ * To share a {@link GLContext} see the following note in the documentation overview:
+ * <a href="../../../spec-overview.html#SHARING">context sharing</a>
+ * as well as {@link GLSharedContextSetter}.
  */
 
 @SuppressWarnings("serial")
@@ -200,6 +205,9 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
   /** Creates a new GLCanvas component with a default set of OpenGL
       capabilities, using the default OpenGL capabilities selection
       mechanism, on the default screen device.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
    * @throws GLException if no default profile is available for the default desktop device.
    */
   public GLCanvas() throws GLException {
@@ -209,27 +217,14 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
   /** Creates a new GLCanvas component with the requested set of
       OpenGL capabilities, using the default OpenGL capabilities
       selection mechanism, on the default screen device.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
    * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
    * @see GLCanvas#GLCanvas(javax.media.opengl.GLCapabilitiesImmutable, javax.media.opengl.GLCapabilitiesChooser, javax.media.opengl.GLContext, java.awt.GraphicsDevice)
    */
   public GLCanvas(final GLCapabilitiesImmutable capsReqUser) throws GLException {
-    this(capsReqUser, null, null, null);
-  }
-
-  /** Creates a new GLCanvas component with the requested set of
-      OpenGL capabilities, using the default OpenGL capabilities
-      selection mechanism, on the default screen device.
-   *  This constructor variant also supports using a shared GLContext.
-   *
-   * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
-   * @see GLCanvas#GLCanvas(javax.media.opengl.GLCapabilitiesImmutable, javax.media.opengl.GLCapabilitiesChooser, javax.media.opengl.GLContext, java.awt.GraphicsDevice)
-   * @deprecated Use {@link #GLCanvas(GLCapabilitiesImmutable)}
-   *             and set shared GLContext via {@link #setSharedContext(GLContext)} or {@link #setSharedAutoDrawable(GLAutoDrawable)}.
-   */
-  public GLCanvas(final GLCapabilitiesImmutable capsReqUser, final GLContext shareWith)
-          throws GLException
-  {
-    this(capsReqUser, null, shareWith, null);
+    this(capsReqUser, null, null);
   }
 
   /** Creates a new GLCanvas component. The passed GLCapabilities
@@ -242,6 +237,9 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
       which to create the GLCanvas; the GLDrawableFactory uses the
       default screen device of the local GraphicsEnvironment if null
       is passed for this argument.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
    * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
    */
   public GLCanvas(final GLCapabilitiesImmutable capsReqUser,
@@ -249,34 +247,6 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
                   final GraphicsDevice device)
       throws GLException
   {
-      this(capsReqUser, chooser, null, device);
-  }
-
-  /** Creates a new GLCanvas component. The passed GLCapabilities
-      specifies the OpenGL capabilities for the component; if null, a
-      default set of capabilities is used. The GLCapabilitiesChooser
-      specifies the algorithm for selecting one of the available
-      GLCapabilities for the component; a DefaultGLCapabilitesChooser
-      is used if null is passed for this argument. The passed
-      GLContext specifies an OpenGL context with which to share
-      textures, display lists and other OpenGL state, and may be null
-      if sharing is not desired. See the note in the overview
-      documentation on <a
-      href="../../../spec-overview.html#SHARING">context
-      sharing</a>. The passed GraphicsDevice indicates the screen on
-      which to create the GLCanvas; the GLDrawableFactory uses the
-      default screen device of the local GraphicsEnvironment if null
-      is passed for this argument.
-   * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
-   * @deprecated Use {@link #GLCanvas(GLCapabilitiesImmutable, GLCapabilitiesChooser, GraphicsDevice)}
-   *             and set shared GLContext via {@link #setSharedContext(GLContext)} or {@link #setSharedAutoDrawable(GLAutoDrawable)}.
-   */
-  public GLCanvas(GLCapabilitiesImmutable capsReqUser,
-                  final GLCapabilitiesChooser chooser,
-                  final GLContext shareWith,
-                  GraphicsDevice device)
-      throws GLException
-  {
     /*
      * Determination of the native window is made in 'super.addNotify()',
      * which creates the native peer using AWT's GraphicsConfiguration.
@@ -287,29 +257,28 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
     super();
 
     if(null==capsReqUser) {
-        capsReqUser = new GLCapabilities(GLProfile.getDefault(GLProfile.getDefaultDevice()));
+        this.capsReqUser = new GLCapabilities(GLProfile.getDefault(GLProfile.getDefaultDevice()));
     } else {
         // don't allow the user to change data
-        capsReqUser = (GLCapabilitiesImmutable) capsReqUser.cloneMutable();
+        this.capsReqUser = (GLCapabilitiesImmutable) capsReqUser.cloneMutable();
     }
-    if(!capsReqUser.isOnscreen()) {
+    if( !this.capsReqUser.isOnscreen() ) {
         setShallUseOffscreenLayer(true); // trigger offscreen layer - if supported
     }
 
     if(null==device) {
         final GraphicsConfiguration gc = super.getGraphicsConfiguration();
         if(null!=gc) {
-            device = gc.getDevice();
+            this.device = gc.getDevice();
+        } else {
+            this.device = null;
         }
+    } else {
+        this.device = device;
     }
 
     // instantiation will be issued in addNotify()
-    this.capsReqUser = capsReqUser;
     this.chooser = chooser;
-    if( null != shareWith ) {
-        helper.setSharedContext(null, shareWith);
-    }
-    this.device = device;
 
     this.addHierarchyListener(hierarchyListener);
     this.isShowing = isShowing();
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index eca99c6c0..549b6e96f 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -170,6 +170,10 @@ import com.jogamp.opengl.util.texture.TextureState;
     It is recommended to reset those states to default when leaving the {@link GLEventListener#display(GLAutoDrawable)} method!
     We may change this behavior in the future, i.e. preserve all influencing states.
     </p>
+    <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+    To share a {@link GLContext} see the following note in the documentation overview:
+    <a href="../../../spec-overview.html#SHARING">context sharing</a>
+    as well as {@link GLSharedContextSetter}.
 */
 
 @SuppressWarnings("serial")
@@ -298,6 +302,9 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
   /** Creates a new GLJPanel component with a default set of OpenGL
       capabilities and using the default OpenGL capabilities selection
       mechanism.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
    * @throws GLException if no default profile is available for the default desktop device.
    */
   public GLJPanel() throws GLException {
@@ -307,10 +314,13 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
   /** Creates a new GLJPanel component with the requested set of
       OpenGL capabilities, using the default OpenGL capabilities
       selection mechanism.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
    * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
    */
   public GLJPanel(final GLCapabilitiesImmutable userCapsRequest) throws GLException {
-    this(userCapsRequest, null, null);
+    this(userCapsRequest, null);
   }
 
   /** Creates a new GLJPanel component. The passed GLCapabilities
@@ -319,34 +329,14 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
       specifies the algorithm for selecting one of the available
       GLCapabilities for the component; a DefaultGLCapabilitesChooser
       is used if null is passed for this argument.
+      <p>
+      See details about <a href="#contextSharing">OpenGL context sharing</a>.
+      </p>
     * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
   */
   public GLJPanel(final GLCapabilitiesImmutable userCapsRequest, final GLCapabilitiesChooser chooser)
           throws GLException
   {
-      this(userCapsRequest, chooser, null);
-  }
-
-  /** Creates a new GLJPanel component. The passed GLCapabilities
-      specifies the OpenGL capabilities for the component; if null, a
-      default set of capabilities is used. The GLCapabilitiesChooser
-      specifies the algorithm for selecting one of the available
-      GLCapabilities for the component; a DefaultGLCapabilitesChooser
-      is used if null is passed for this argument. The passed
-      GLContext specifies an OpenGL context with which to share
-      textures, display lists and other OpenGL state, and may be null
-      if sharing is not desired. See the note in the overview documentation on
-      <a href="../../../spec-overview.html#SHARING">context sharing</a>.
-      <P>
-      Note: Sharing cannot be enabled using J2D OpenGL FBO sharing,
-      since J2D GL Context must be shared and we can only share one context.
-    * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
-    * @deprecated Use {@link #GLJPanel(GLCapabilitiesImmutable, GLCapabilitiesChooser)}
-    *             and set shared GLContext via {@link #setSharedContext(GLContext)} or {@link #setSharedAutoDrawable(GLAutoDrawable)}.
-    */
-  public GLJPanel(final GLCapabilitiesImmutable userCapsRequest, final GLCapabilitiesChooser chooser, final GLContext shareWith)
-          throws GLException
-  {
     super();
 
     // Works around problems on many vendors' cards; we don't need a
@@ -366,9 +356,6 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
     this.chooser = chooser;
 
     helper = new GLDrawableHelper();
-    if( null != shareWith ) {
-        helper.setSharedContext(null, shareWith);
-    }
     autoSwapBufferMode = helper.getAutoSwapBufferMode();
 
     this.setFocusable(true); // allow keyboard input!