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

5 files changed, 7 insertions, 610 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index c94d21369..e58d8c64a 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -297,40 +297,6 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
    }
 
    /**
-    * Creates an instance using {@link #GLCanvas(Composite, int, GLCapabilitiesImmutable, GLCapabilitiesChooser, GLContext)}
-    * on the SWT thread.
-    *
-    * @param parent
-    *           Required (non-null) parent Composite.
-    * @param style
-    *           Optional SWT style bit-field. The {@link SWT#NO_BACKGROUND} bit is set before passing this up to the
-    *           Canvas constructor, so OpenGL handles the background.
-    * @param caps
-    *           Optional GLCapabilities. If not provided, the default capabilities for the default GLProfile for the
-    *           graphics device determined by the parent Composite are used. Note that the GLCapabilities that are
-    *           actually used may differ based on the capabilities of the graphics device.
-    * @param chooser
-    *           Optional GLCapabilitiesChooser to customize the selection of the used GLCapabilities based on the
-    *           requested GLCapabilities, and the available capabilities of the graphics device.
-    * @param shareWith
-    *           Optional GLContext to share state (textures, vbos, shaders, etc.) with.
-    * @return a new instance
-    * @deprecated Use {@link #create(Composite, int, GLCapabilitiesImmutable, GLCapabilitiesChooser)}
-    *             and set shared GLContext via {@link #setSharedContext(GLContext)} or {@link #setSharedAutoDrawable(GLAutoDrawable)}.
-    */
-   public static GLCanvas create(final Composite parent, final int style, final GLCapabilitiesImmutable caps,
-                                 final GLCapabilitiesChooser chooser, final GLContext shareWith) {
-       final GLCanvas[] res = new GLCanvas[] { null };
-       parent.getDisplay().syncExec(new Runnable() {
-           @Override
-           public void run() {
-               res[0] = new GLCanvas( parent, style, caps, chooser, shareWith );
-           }
-       });
-       return res[0];
-   }
-
-   /**
     * Creates a new SWT GLCanvas.
     *
     * @param parent
@@ -348,31 +314,6 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
     */
    public GLCanvas(final Composite parent, final int style, final GLCapabilitiesImmutable capsReqUser,
                    final GLCapabilitiesChooser capsChooser) {
-       this(parent, style, capsReqUser, capsChooser, null);
-   }
-
-   /**
-    * Creates a new SWT GLCanvas.
-    *
-    * @param parent
-    *           Required (non-null) parent Composite.
-    * @param style
-    *           Optional SWT style bit-field. The {@link SWT#NO_BACKGROUND} bit is set before passing this up to the
-    *           Canvas constructor, so OpenGL handles the background.
-    * @param capsReqUser
-    *           Optional GLCapabilities. If not provided, the default capabilities for the default GLProfile for the
-    *           graphics device determined by the parent Composite are used. Note that the GLCapabilities that are
-    *           actually used may differ based on the capabilities of the graphics device.
-    * @param capsChooser
-    *           Optional GLCapabilitiesChooser to customize the selection of the used GLCapabilities based on the
-    *           requested GLCapabilities, and the available capabilities of the graphics device.
-    * @param shareWith
-    *           Optional GLContext to share state (textures, vbos, shaders, etc.) with.
-    * @deprecated Use {@link #GLCanvas(Composite, int, GLCapabilitiesImmutable, GLCapabilitiesChooser)}
-    *             and set shared GLContext via {@link #setSharedContext(GLContext)} or {@link #setSharedAutoDrawable(GLAutoDrawable)}.
-    */
-   public GLCanvas(final Composite parent, final int style, GLCapabilitiesImmutable capsReqUser,
-                   final GLCapabilitiesChooser capsChooser, final GLContext shareWith) {
       /* NO_BACKGROUND required to avoid clearing bg in native SWT widget (we do this in the GL display) */
       super(parent, style | SWT.NO_BACKGROUND);
 
@@ -399,16 +340,13 @@ public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextS
           screen = SWTAccessor.getScreen(swtDevice, -1 /* default */);
       }
 
-      /* Select default GLCapabilities if none was provided, otherwise clone provided caps to ensure safety */
+      /* Select default GLCapabilities if none was provided, otherwise use cloned provided caps */
       if(null == capsReqUser) {
-          capsReqUser = new GLCapabilities(GLProfile.getDefault(screen.getDevice()));
+          this.capsRequested = new GLCapabilities(GLProfile.getDefault(screen.getDevice()));
+      } else {
+          this.capsRequested = (GLCapabilitiesImmutable) capsReqUser.cloneMutable();
       }
-
-      this.capsRequested = capsReqUser;
       this.capsChooser = capsChooser;
-      if( null != shareWith ) {
-          helper.setSharedContext(null, shareWith);
-      }
 
       // post create .. when ready
       gdkWindow = 0;
diff --git a/src/jogl/classes/com/jogamp/opengl/util/TGAWriter.java b/src/jogl/classes/com/jogamp/opengl/util/TGAWriter.java
deleted file mode 100644
index 6e31c78a0..000000000
--- a/src/jogl/classes/com/jogamp/opengl/util/TGAWriter.java
+++ /dev/null
@@ -1,116 +0,0 @@
-/*
- * Copyright (c) 2005 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.
- */
-
-package com.jogamp.opengl.util;
-
-import java.io.*;
-import java.nio.*;
-import java.nio.channels.*;
-
-/**
- * Utility class which helps take fast screenshots of OpenGL rendering
- * results into Targa-format files. Used by the {@link com.jogamp.opengl.util.awt.Screenshot}
- * class; can also be used in conjunction with the {@link com.jogamp.opengl.util.gl2.TileRenderer} class.
- */
-public class TGAWriter {
-
-  private static final int TARGA_HEADER_SIZE = 18;
-
-  private FileChannel ch;
-  private ByteBuffer buf;
-
-  /** Constructor for the TGAWriter. */
-  public TGAWriter() {
-  }
-
-  /**
-   * Opens the specified Targa file for writing, overwriting any
-   * existing file, and sets up the header of the file expecting the
-   * data to be filled in before closing it.
-   *
-   * @param file the file to write containing the screenshot
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   * @param alpha whether the alpha channel should be saved. If true,
-   *   requires GL_EXT_abgr extension to be present.
-   *
-   * @throws IOException if an I/O error occurred while writing the
-   *   file
-   */
-  public void open(final File file,
-                   final int width,
-                   final int height,
-                   final boolean alpha) throws IOException {
-    final RandomAccessFile out = new RandomAccessFile(file, "rw");
-    ch = out.getChannel();
-    final int pixelSize = (alpha ? 32 : 24);
-    final int numChannels = (alpha ? 4 : 3);
-
-    final int fileLength = TARGA_HEADER_SIZE + width * height * numChannels;
-    out.setLength(fileLength);
-    final MappedByteBuffer image = ch.map(FileChannel.MapMode.READ_WRITE, 0, fileLength);
-
-    // write the TARGA header
-    image.put(0, (byte) 0).put(1, (byte) 0);
-    image.put(2, (byte) 2); // uncompressed type
-    image.put(12, (byte) (width & 0xFF)); // width
-    image.put(13, (byte) (width >> 8)); // width
-    image.put(14, (byte) (height & 0xFF)); // height
-    image.put(15, (byte) (height >> 8)); // height
-    image.put(16, (byte) pixelSize); // pixel size
-
-    // go to image data position
-    image.position(TARGA_HEADER_SIZE);
-    // jogl needs a sliced buffer
-    buf = image.slice();
-  }
-
-  /**
-   * Returns the ByteBuffer corresponding to the data for the image.
-   * This must be filled in with data in either BGR or BGRA format
-   * depending on whether an alpha channel was specified during
-   * open().
-   */
-  public ByteBuffer getImageData() {
-    return buf;
-  }
-
-  public void close() throws IOException {
-    // close the file channel
-    ch.close();
-    buf = null;
-  }
-}
diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java b/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java
index 6d875fcf5..fd6172e13 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java
@@ -423,20 +423,6 @@ public interface AudioSink {
     public int getFreeFrameCount();
 
     /**
-     * Enqueue the remaining bytes of the given {@link AudioDataFrame}'s direct ByteBuffer to this sink.
-     * <p>
-     * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}.
-     * </p>
-     * <p>
-     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
-     * </p>
-     * @returns the enqueued internal {@link AudioFrame}, which may differ from the input <code>audioDataFrame</code>.
-     * @deprecated User shall use {@link #enqueueData(int, ByteBuffer, int)}, which allows implementation
-     *             to reuse specialized {@link AudioFrame} instances.
-     */
-    public AudioFrame enqueueData(AudioDataFrame audioDataFrame);
-
-    /**
      * Enqueue <code>byteCount</code> bytes of the remaining bytes of the given NIO {@link ByteBuffer} to this sink.
      * <p>
      * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}.
diff --git a/src/jogl/classes/com/jogamp/opengl/util/awt/AWTGLReadBufferUtil.java b/src/jogl/classes/com/jogamp/opengl/util/awt/AWTGLReadBufferUtil.java
index 06e3ccda5..b75ad3b17 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/awt/AWTGLReadBufferUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/awt/AWTGLReadBufferUtil.java
@@ -50,6 +50,9 @@ public class AWTGLReadBufferUtil extends GLReadBufferUtil {
         super(new AWTGLPixelBuffer.AWTGLPixelBufferProvider( glp.isGL2ES3() /* allowRowStride */ ), alpha, false);
     }
 
+    /**
+     * Returns the {@link AWTGLPixelBuffer}, as filled by previous call to {@link #readPixels(GL, int, int, int, int, boolean)}.
+     */
     public AWTGLPixelBuffer getAWTGLPixelBuffer() { return (AWTGLPixelBuffer)this.getPixelBuffer(); }
 
     /**
diff --git a/src/jogl/classes/com/jogamp/opengl/util/awt/Screenshot.java b/src/jogl/classes/com/jogamp/opengl/util/awt/Screenshot.java
deleted file mode 100644
index ac208044b..000000000
--- a/src/jogl/classes/com/jogamp/opengl/util/awt/Screenshot.java
+++ /dev/null
@@ -1,414 +0,0 @@
-/*
- * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
- * Copyright (c) 2013 JogAmp Community. 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.
- */
-
-package com.jogamp.opengl.util.awt;
-
-import java.awt.image.BufferedImage;
-import java.awt.image.DataBufferByte;
-import java.io.File;
-import java.io.IOException;
-import java.nio.ByteBuffer;
-
-import javax.imageio.ImageIO;
-import javax.media.opengl.GL;
-import javax.media.opengl.GL2;
-import javax.media.opengl.GL2GL3;
-import javax.media.opengl.GLContext;
-import javax.media.opengl.GLDrawable;
-import javax.media.opengl.GLException;
-
-import com.jogamp.common.util.IOUtil;
-import com.jogamp.opengl.GLExtensions;
-import com.jogamp.opengl.util.GLPixelStorageModes;
-import com.jogamp.opengl.util.TGAWriter;
-
-/**
- * Utilities for taking screenshots of OpenGL applications.
- * @deprecated Please consider using {@link com.jogamp.opengl.util.GLReadBufferUtil},
- *             which is AWT independent and does not require a CPU based vertical image flip
- *             in case drawable {@link GLDrawable#isGLOriented() is in OpenGL orientation}.
- *             Further more you may use {@link AWTGLReadBufferUtil} to read out
- *             the framebuffer into a BufferedImage for further AWT processing.
- */
-public class Screenshot {
-  private Screenshot() {}
-
-  /**
-   * Takes a fast screenshot of the current OpenGL drawable to a Targa
-   * file. Requires the OpenGL context for the desired drawable to be
-   * current. Takes the screenshot from the last assigned read buffer,
-   * or the OpenGL default read buffer if none has been specified by
-   * the user (GL_FRONT for single-buffered configurations and GL_BACK
-   * for double-buffered configurations). This is the fastest
-   * mechanism for taking a screenshot of an application. Contributed
-   * by Carsten Weisse of Bytonic Software (http://bytonic.de/). <p>
-   *
-   * No alpha channel is written with this variant.
-   *
-   * @param file the file to write containing the screenshot
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   * @throws IOException if an I/O error occurred while writing the
-   *   file
-   */
-  public static void writeToTargaFile(final File file,
-                                      final int width,
-                                      final int height) throws GLException, IOException {
-    writeToTargaFile(file, width, height, false);
-  }
-
-  /**
-   * Takes a fast screenshot of the current OpenGL drawable to a Targa
-   * file. Requires the OpenGL context for the desired drawable to be
-   * current. Takes the screenshot from the last assigned read buffer,
-   * or the OpenGL default read buffer if none has been specified by
-   * the user (GL_FRONT for single-buffered configurations and GL_BACK
-   * for double-buffered configurations). This is the fastest
-   * mechanism for taking a screenshot of an application. Contributed
-   * by Carsten Weisse of Bytonic Software (http://bytonic.de/).
-   *
-   * @param file the file to write containing the screenshot
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   * @param alpha whether the alpha channel should be saved. If true,
-   *   requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   * @throws IOException if an I/O error occurred while writing the
-   *   file
-   */
-  public static void writeToTargaFile(final File file,
-                                      final int width,
-                                      final int height,
-                                      final boolean alpha) throws GLException, IOException {
-    writeToTargaFile(file, 0, 0, width, height, alpha);
-  }
-
-  /**
-   * Takes a fast screenshot of the current OpenGL drawable to a Targa
-   * file. Requires the OpenGL context for the desired drawable to be
-   * current. Takes the screenshot from the last assigned read buffer,
-   * or the OpenGL default read buffer if none has been specified by
-   * the user (GL_FRONT for single-buffered configurations and GL_BACK
-   * for double-buffered configurations). This is the fastest
-   * mechanism for taking a screenshot of an application. Contributed
-   * by Carsten Weisse of Bytonic Software (http://bytonic.de/).
-   *
-   * @param file the file to write containing the screenshot
-   * @param x the starting x coordinate of the screenshot, measured from the lower-left
-   * @param y the starting y coordinate of the screenshot, measured from the lower-left
-   * @param width the width of the desired screenshot area
-   * @param height the height of the desired screenshot area
-   * @param alpha whether the alpha channel should be saved. If true,
-   *   requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   * @throws IOException if an I/O error occurred while writing the
-   *   file
-   */
-  public static void writeToTargaFile(final File file,
-                                      final int x,
-                                      final int y,
-                                      final int width,
-                                      final int height,
-                                      final boolean alpha) throws GLException, IOException {
-    if (alpha) {
-      checkExtABGR();
-    }
-
-    final TGAWriter writer = new TGAWriter();
-    writer.open(file, width, height, alpha);
-    final ByteBuffer bgr = writer.getImageData();
-
-    final GL gl = GLContext.getCurrentGL();
-
-    // Set up pixel storage modes
-    final GLPixelStorageModes psm = new GLPixelStorageModes();
-    psm.setPackAlignment(gl, 1);
-
-    final int readbackType = (alpha ? GL2.GL_ABGR_EXT : GL2GL3.GL_BGR);
-
-    // read the BGR values into the image buffer
-    gl.glReadPixels(x, y, width, height, readbackType,
-                    GL.GL_UNSIGNED_BYTE, bgr);
-
-    // Restore pixel storage modes
-    psm.restore(gl);
-
-    // close the file
-    writer.close();
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to a
-   * BufferedImage. Requires the OpenGL context for the desired
-   * drawable to be current. Takes the screenshot from the last
-   * assigned read buffer, or the OpenGL default read buffer if none
-   * has been specified by the user (GL_FRONT for single-buffered
-   * configurations and GL_BACK for double-buffered configurations).
-   * Note that the scanlines of the resulting image are flipped
-   * vertically in order to correctly match the OpenGL contents, which
-   * takes time and is therefore not as fast as the Targa screenshot
-   * function. <P>
-   *
-   * No alpha channel is read back with this variant.
-   *
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   */
-  public static BufferedImage readToBufferedImage(final int width,
-                                                  final int height) throws GLException {
-    return readToBufferedImage(width, height, false);
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to a
-   * BufferedImage. Requires the OpenGL context for the desired
-   * drawable to be current. Takes the screenshot from the last
-   * assigned read buffer, or the OpenGL default read buffer if none
-   * has been specified by the user (GL_FRONT for single-buffered
-   * configurations and GL_BACK for double-buffered configurations).
-   * Note that the scanlines of the resulting image are flipped
-   * vertically in order to correctly match the OpenGL contents, which
-   * takes time and is therefore not as fast as the Targa screenshot
-   * function.
-   *
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   * @param alpha whether the alpha channel should be read back. If
-   *   true, requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   */
-  public static BufferedImage readToBufferedImage(final int width,
-                                                  final int height,
-                                                  final boolean alpha) throws GLException {
-    return readToBufferedImage(0, 0, width, height, alpha);
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to a
-   * BufferedImage. Requires the OpenGL context for the desired
-   * drawable to be current. Takes the screenshot from the last
-   * assigned read buffer, or the OpenGL default read buffer if none
-   * has been specified by the user (GL_FRONT for single-buffered
-   * configurations and GL_BACK for double-buffered configurations).
-   * Note that the scanlines of the resulting image are flipped
-   * vertically in order to correctly match the OpenGL contents, which
-   * takes time and is therefore not as fast as the Targa screenshot
-   * function.
-   *
-   * @param x the starting x coordinate of the screenshot, measured from the lower-left
-   * @param y the starting y coordinate of the screenshot, measured from the lower-left
-   * @param width the width of the desired screenshot area
-   * @param height the height of the desired screenshot area
-   * @param alpha whether the alpha channel should be read back. If
-   *   true, requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   */
-  public static BufferedImage readToBufferedImage(final int x,
-                                                  final int y,
-                                                  final int width,
-                                                  final int height,
-                                                  final boolean alpha) throws GLException {
-    final int bufImgType = (alpha ? BufferedImage.TYPE_4BYTE_ABGR : BufferedImage.TYPE_3BYTE_BGR);
-    final int readbackType = (alpha ? GL2.GL_ABGR_EXT : GL2GL3.GL_BGR);
-
-    if (alpha) {
-      checkExtABGR();
-    }
-
-    // Allocate necessary storage
-    final BufferedImage image = new BufferedImage(width, height, bufImgType);
-
-    final GLContext glc = GLContext.getCurrent();
-    final GL gl = glc.getGL();
-
-    // Set up pixel storage modes
-    final GLPixelStorageModes psm = new GLPixelStorageModes();
-    psm.setPackAlignment(gl, 1);
-
-    // read the BGR values into the image
-    gl.glReadPixels(x, y, width, height, readbackType,
-                    GL.GL_UNSIGNED_BYTE,
-                    ByteBuffer.wrap(((DataBufferByte) image.getRaster().getDataBuffer()).getData()));
-
-    // Restore pixel storage modes
-    psm.restore(gl);
-
-    if( glc.getGLDrawable().isGLOriented() ) {
-        // Must flip BufferedImage vertically for correct results
-        ImageUtil.flipImageVertically(image);
-    }
-    return image;
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to the
-   * specified file on disk using the ImageIO package. Requires the
-   * OpenGL context for the desired drawable to be current. Takes the
-   * screenshot from the last assigned read buffer, or the OpenGL
-   * default read buffer if none has been specified by the user
-   * (GL_FRONT for single-buffered configurations and GL_BACK for
-   * double-buffered configurations). This is not the fastest
-   * mechanism for taking a screenshot but may be more convenient than
-   * others for getting images for consumption by other packages. The
-   * file format is inferred from the suffix of the given file. <P>
-   *
-   * No alpha channel is saved with this variant.
-   *
-   * @param file the file to write containing the screenshot
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   *
-   * @throws IOException if an I/O error occurred or if the file could
-   *   not be written to disk due to the requested file format being
-   *   unsupported by ImageIO
-   */
-  public static void writeToFile(final File file,
-                                 final int width,
-                                 final int height) throws IOException, GLException {
-    writeToFile(file, width, height, false);
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to the
-   * specified file on disk using the ImageIO package. Requires the
-   * OpenGL context for the desired drawable to be current. Takes the
-   * screenshot from the last assigned read buffer, or the OpenGL
-   * default read buffer if none has been specified by the user
-   * (GL_FRONT for single-buffered configurations and GL_BACK for
-   * double-buffered configurations). This is not the fastest
-   * mechanism for taking a screenshot but may be more convenient than
-   * others for getting images for consumption by other packages. The
-   * file format is inferred from the suffix of the given file. <P>
-   *
-   * Note that some file formats, in particular JPEG, can not handle
-   * an alpha channel properly. If the "alpha" argument is specified
-   * as true for such a file format it will be silently ignored.
-   *
-   * @param file the file to write containing the screenshot
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   * @param alpha whether an alpha channel should be saved. If true,
-   *   requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   *
-   * @throws IOException if an I/O error occurred or if the file could
-   *   not be written to disk due to the requested file format being
-   *   unsupported by ImageIO
-   */
-  public static void writeToFile(final File file,
-                                 final int width,
-                                 final int height,
-                                 final boolean alpha) throws IOException, GLException {
-    writeToFile(file, 0, 0, width, height, alpha);
-  }
-
-  /**
-   * Takes a screenshot of the current OpenGL drawable to the
-   * specified file on disk using the ImageIO package. Requires the
-   * OpenGL context for the desired drawable to be current. Takes the
-   * screenshot from the last assigned read buffer, or the OpenGL
-   * default read buffer if none has been specified by the user
-   * (GL_FRONT for single-buffered configurations and GL_BACK for
-   * double-buffered configurations). This is not the fastest
-   * mechanism for taking a screenshot but may be more convenient than
-   * others for getting images for consumption by other packages. The
-   * file format is inferred from the suffix of the given file. <P>
-   *
-   * Note that some file formats, in particular JPEG, can not handle
-   * an alpha channel properly. If the "alpha" argument is specified
-   * as true for such a file format it will be silently ignored.
-   *
-   * @param file the file to write containing the screenshot
-   * @param x the starting x coordinate of the screenshot, measured from the lower-left
-   * @param y the starting y coordinate of the screenshot, measured from the lower-left
-   * @param width the width of the current drawable
-   * @param height the height of the current drawable
-   * @param alpha whether an alpha channel should be saved. If true,
-   *   requires GL_EXT_abgr extension to be present.
-   *
-   * @throws GLException if an OpenGL context was not current or
-   *   another OpenGL-related error occurred
-   *
-   * @throws IOException if an I/O error occurred or if the file could
-   *   not be written to disk due to the requested file format being
-   *   unsupported by ImageIO
-   */
-  public static void writeToFile(final File file,
-                                 final int x,
-                                 final int y,
-                                 final int width,
-                                 final int height,
-                                 boolean alpha) throws IOException, GLException {
-    final String fileSuffix = IOUtil.getFileSuffix(file);
-    if (alpha && (fileSuffix.equals("jpg") || fileSuffix.equals("jpeg"))) {
-      // JPEGs can't deal properly with alpha channels
-      alpha = false;
-    }
-
-    final BufferedImage image = readToBufferedImage(x, y, width, height, alpha);
-    if (!ImageIO.write(image, fileSuffix, file)) {
-      throw new IOException("Unsupported file format " + fileSuffix);
-    }
-  }
-
-  private static void checkExtABGR() {
-    final GL gl = GLContext.getCurrentGL();
-
-    if (!gl.isExtensionAvailable(GLExtensions.EXT_abgr)) {
-      throw new IllegalArgumentException("Saving alpha channel requires GL_EXT_abgr");
-    }
-  }
-}