Makefile.am (gtk_awt_peer_sources): Add GtkVolatileImage.java.

2005-05-06  Thomas Fitzsimmons  <fitzsim@redhat.com>

	* Makefile.am (gtk_awt_peer_sources): Add GtkVolatileImage.java.
	* Makefile.in: Regenerate.
	* gnu/java/awt/peer/gtk/GdkGraphicsConfiguration.java
	(createCompatibleVolatileImage(int,int)): Implement.
	(createCompatibleVolatileImage(int,int,ImageCapabilities)):
	Likewise.
	* gnu/java/awt/peer/gtk/GtkComponentPeer.java (backBuffer, caps):
	New fields.
	(createVolatileImage): Implement.
	(createBuffers): Likewise.
	(getBackBuffer): Likewise.
	(flip): Likewise.
	(destroyBuffers): Likewise.
	* gnu/java/awt/peer/gtk/GtkVolatileImage.java: New file.
	* java/awt/Canvas.java (CanvasBltBufferStrategy): New class.
	(CanvasFlipBufferStrategy): Likewise.
	(createBufferStrategy(int)): New method.
	(createBufferStrategy(int,BufferCapabilities)): Likewise.
	* java/awt/Component.java (BltBufferStrategy): Implement and
	document class.
	(FlipBufferStrategy): Likewise.
	* java/awt/Window.java (WindowBltBufferStrategy): New class.
	(WindowFlipBufferStrategy): Likewise.
	(createBufferStrategy(int)): New method.
	(createBufferStrategy(int,BufferCapabilities)): Likewise.
	(getBufferStrategy): Likewise.
	* java/awt/BufferCapabilities.java (BufferCapabilities): Rename
	front to frontCaps and back to backCaps.

From-SVN: r99336

libjava/ChangeLog

+2005-05-06  Thomas Fitzsimmons  <fitzsim@redhat.com>
+
+	* Makefile.am (gtk_awt_peer_sources): Add GtkVolatileImage.java.
+	* Makefile.in: Regenerate.
+	* gnu/java/awt/peer/gtk/GdkGraphicsConfiguration.java
+	(createCompatibleVolatileImage(int,int)): Implement.
+	(createCompatibleVolatileImage(int,int,ImageCapabilities)):
+	Likewise.
+	* gnu/java/awt/peer/gtk/GtkComponentPeer.java (backBuffer, caps):
+	New fields.
+	(createVolatileImage): Implement.
+	(createBuffers): Likewise.
+	(getBackBuffer): Likewise.
+	(flip): Likewise.
+	(destroyBuffers): Likewise.
+	* gnu/java/awt/peer/gtk/GtkVolatileImage.java: New file.
+	* java/awt/Canvas.java (CanvasBltBufferStrategy): New class.
+	(CanvasFlipBufferStrategy): Likewise.
+	(createBufferStrategy(int)): New method.
+	(createBufferStrategy(int,BufferCapabilities)): Likewise.
+	* java/awt/Component.java (BltBufferStrategy): Implement and
+	document class.
+	(FlipBufferStrategy): Likewise.
+	* java/awt/Window.java (WindowBltBufferStrategy): New class.
+	(WindowFlipBufferStrategy): Likewise.
+	(createBufferStrategy(int)): New method.
+	(createBufferStrategy(int,BufferCapabilities)): Likewise.
+	(getBufferStrategy): Likewise.
+	* java/awt/BufferCapabilities.java (BufferCapabilities): Rename
+	front to frontCaps and back to backCaps.
+
 2005-05-06  Michael Koch  <konqueror@gmx.de>
 
 	* java/awt/BufferCapabilities.java

libjava/Makefile.am

@@ -387,6 +387,7 @@ gnu/java/awt/peer/gtk/GtkTextAreaPeer.java \
 gnu/java/awt/peer/gtk/GtkTextComponentPeer.java	\
 gnu/java/awt/peer/gtk/GtkTextFieldPeer.java \
 gnu/java/awt/peer/gtk/GtkToolkit.java \
+gnu/java/awt/peer/gtk/GtkVolatileImage.java \
 gnu/java/awt/peer/gtk/GtkWindowPeer.java \
 gnu/java/awt/peer/gtk/GThreadMutex.java \
 gnu/java/awt/peer/gtk/GThreadNativeMethodRunner.java

libjava/Makefile.in

@@ -4783,6 +4783,7 @@ gnu/java/awt/peer/gtk/GtkTextAreaPeer.java \
 gnu/java/awt/peer/gtk/GtkTextComponentPeer.java	\
 gnu/java/awt/peer/gtk/GtkTextFieldPeer.java \
 gnu/java/awt/peer/gtk/GtkToolkit.java \
+gnu/java/awt/peer/gtk/GtkVolatileImage.java \
 gnu/java/awt/peer/gtk/GtkWindowPeer.java \
 gnu/java/awt/peer/gtk/GThreadMutex.java \
 gnu/java/awt/peer/gtk/GThreadNativeMethodRunner.java

libjava/gnu/java/awt/peer/gtk/GdkGraphicsConfiguration.java

@@ -86,14 +86,14 @@ public class GdkGraphicsConfiguration
 
   public VolatileImage createCompatibleVolatileImage(int w, int h)
   {
-    throw new java.lang.UnsupportedOperationException ();
+    return new GtkVolatileImage(w, h);
   }
 
   public VolatileImage createCompatibleVolatileImage(int w, int h,
                                                      ImageCapabilities caps)
     throws java.awt.AWTException
   {
-    throw new java.lang.UnsupportedOperationException ();
+    return new GtkVolatileImage(w, h, caps);
   }
 
   public ColorModel getColorModel()

libjava/gnu/java/awt/peer/gtk/GtkComponentPeer.java

@@ -39,6 +39,7 @@ exception statement from your version. */
 package gnu.java.awt.peer.gtk;
 
 import java.awt.AWTEvent;
+import java.awt.AWTException;
 import java.awt.BufferCapabilities;
 import java.awt.Color;
 import java.awt.Component;
@@ -71,6 +72,9 @@ import java.awt.peer.ComponentPeer;
 public class GtkComponentPeer extends GtkGenericPeer
   implements ComponentPeer
 {
+  VolatileImage backBuffer;
+  BufferCapabilities caps;
+
   Component awtComponent;
 
   Insets insets;
@@ -596,35 +600,63 @@ public class GtkComponentPeer extends GtkGenericPeer
     
   }
 
-  public VolatileImage createVolatileImage (int width, int height)
-  {
-    return null;
-  }
-
   public boolean handlesWheelScrolling ()
   {
     return false;
   }
 
-  public void createBuffers (int x, BufferCapabilities capabilities)
-    throws java.awt.AWTException
+  // Convenience method to create a new volatile image on the screen
+  // on which this component is displayed.
+  public VolatileImage createVolatileImage (int width, int height)
+  {
+    return new GtkVolatileImage (width, height);
+  }
 
+  // Creates buffers used in a buffering strategy.
+  public void createBuffers (int numBuffers, BufferCapabilities caps)
+    throws AWTException
   {
-    
+    // numBuffers == 2 implies double-buffering, meaning one back
+    // buffer and one front buffer.
+    if (numBuffers == 2)
+      backBuffer = new GtkVolatileImage(awtComponent.getWidth(),
+					awtComponent.getHeight(),
+					caps.getBackBufferCapabilities());
+    else
+      throw new AWTException("GtkComponentPeer.createBuffers:"
+			     + " multi-buffering not supported");
+    this.caps = caps;
   }
 
+  // Return the back buffer.
   public Image getBackBuffer ()
   {
-    return null;
+    return backBuffer;
   }
 
+  // FIXME: flip should be implemented as a fast native operation
   public void flip (BufferCapabilities.FlipContents contents)
   {
-    
+    getGraphics().drawImage(backBuffer,
+			    awtComponent.getWidth(),
+			    awtComponent.getHeight(),
+			    null);
+
+    // create new back buffer and clear it to the background color.
+    if (contents == BufferCapabilities.FlipContents.BACKGROUND)
+	{
+	  backBuffer = createVolatileImage(awtComponent.getWidth(),
+					   awtComponent.getHeight());
+	  backBuffer.getGraphics().clearRect(0, 0,
+					     awtComponent.getWidth(),
+					     awtComponent.getHeight());
+	}
+    // FIXME: support BufferCapabilities.FlipContents.PRIOR
   }
 
+  // Release the resources allocated to back buffers.
   public void destroyBuffers ()
   {
-    
+    backBuffer.flush();
   }
 }

libjava/gnu/java/awt/peer/gtk/GtkVolatileImage.java

+/* GtkVolatileImage.java -- a hardware-accelerated image buffer
+   Copyright (C) 2005  Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package gnu.java.awt.peer.gtk;
+
+import java.awt.ImageCapabilities;
+import java.awt.image.VolatileImage;
+
+public class GtkVolatileImage extends VolatileImage
+{
+  private int width;
+  private int height;
+  private ImageCapabilities caps;
+
+  public GtkVolatileImage(int width, int height)
+  {
+    this(width, height, null);
+  }
+
+  public GtkVolatileImage(int width, int height, ImageCapabilities caps)
+  {
+    this.width = width;
+    this.height = height;
+    this.caps = caps;
+  }
+
+  // FIXME: should return a buffered image snapshot of the accelerated
+  // visual
+  public BufferedImage getSnapshot()
+  {
+    return null;
+  }
+
+  public int getWidth()
+  {
+    return width;
+  }
+
+  public int getHeight()
+  {
+    return height;
+  }
+
+  // FIXME: should return a graphics wrapper around this image's
+  // visual
+  public Graphics2D createGraphics()
+  {
+    return null;
+  }
+
+  public int validate(GraphicsConfiguration gc)
+  {
+    return VolatileImage.IMAGE_OK;
+  }
+
+  public boolean contentsLost()
+  {
+    return false;
+  }
+
+  public ImageCapabilities getCapabilities()
+  {
+    return caps;
+  }
+
+  public synchronized Object getProperty (String name, ImageObserver observer)
+  {
+    return null;
+  }
+
+  public synchronized int getWidth (ImageObserver observer)
+  {
+    return width;
+  }
+  
+  public synchronized int getHeight (ImageObserver observer)
+  {
+    return height;
+  }
+}

libjava/java/awt/BufferCapabilities.java

@@ -132,22 +132,22 @@ public class BufferCapabilities implements Cloneable
   /**
    * Creates a buffer capabilities object.
    *
-   * @param front front buffer capabilities descriptor
-   * @param back back buffer capabilities descriptor
+   * @param frontCaps front buffer capabilities descriptor
+   * @param backCaps back buffer capabilities descriptor
    * @param flip the results of a flip operation or null if
    * flipping is not supported
    *
-   * @exception IllegalArgumentException if front or back is
+   * @exception IllegalArgumentException if frontCaps or backCaps is
    * null
    */
-  public BufferCapabilities(ImageCapabilities front,
-			    ImageCapabilities back,
+  public BufferCapabilities(ImageCapabilities frontCaps,
+			    ImageCapabilities backCaps,
                             FlipContents flip)
   {
-    if (front ==  null || back == null)
+    if (frontCaps ==  null || backCaps == null)
       throw new IllegalArgumentException();
-    this.front = front;
-    this.back = back;
+    this.front = frontCaps;
+    this.back = backCaps;
     this.flip = flip;
   }
 

libjava/java/awt/Canvas.java

@@ -179,6 +179,157 @@ public class Canvas
   }
 
   /**
+   * A BltBufferStrategy for canvases.
+   */
+  private class CanvasBltBufferStrategy extends BltBufferStrategy
+  {
+    /**
+     * Creates a block transfer strategy for this canvas.
+     *
+     * @param numBuffers the number of buffers in this strategy
+     * @param accelerated true if the buffer should be accelerated,
+     * false otherwise
+     */
+    CanvasBltBufferStrategy(int numBuffers, boolean accelerated)
+    {
+      super(numBuffers,
+	    new BufferCapabilities(new ImageCapabilities(accelerated),
+				   new ImageCapabilities(accelerated),
+				   BufferCapabilities.FlipContents.COPIED));
+    }
+  }
+
+  /**
+   * A FlipBufferStrategy for canvases.
+   */
+  private class CanvasFlipBufferStrategy extends FlipBufferStrategy
+  {
+    /**
+     * Creates a flip buffer strategy for this canvas.
+     *
+     * @param numBuffers the number of buffers in this strategy
+     *
+     * @throws AWTException if the requested number of buffers is not
+     * supported
+     */
+    CanvasFlipBufferStrategy(int numBuffers)
+      throws AWTException
+    {
+      super(numBuffers,
+	    new BufferCapabilities(new ImageCapabilities(true),
+				   new ImageCapabilities(true),
+				   BufferCapabilities.FlipContents.COPIED));
+    }
+  }
+
+  /**
+   * Creates a buffering strategy that manages how this canvas is
+   * repainted.  This method attempts to create the optimum strategy
+   * based on the desired number of buffers.  Hardware or software
+   * acceleration may be used.
+   *
+   * createBufferStrategy attempts different levels of optimization,
+   * but guarantees that some strategy with the requested number of
+   * buffers will be created even if it is not optimal.  First it
+   * attempts to create a page flipping strategy, then an accelerated
+   * blitting strategy, then an unaccelerated blitting strategy.
+   *
+   * Calling this method causes any existing buffer strategy to be
+   * destroyed.
+   *
+   * @param numBuffers the number of buffers in this strategy
+   *
+   * @throws IllegalArgumentException if requested number of buffers
+   * is less than one
+   * @throws IllegalStateException if this canvas is not displayable
+   *
+   * @since 1.4
+   */
+  public void createBufferStrategy(int numBuffers)
+  {
+    if (numBuffers < 1)
+      throw new IllegalArgumentException("Canvas.createBufferStrategy: number"
+					 + " of buffers is less than one");
+
+    if (!isDisplayable())
+      throw new IllegalStateException("Canvas.createBufferStrategy: canvas is"
+				      + " not displayable");
+
+    // try a flipping strategy
+    try
+      {
+	bufferStrategy = new CanvasFlipBufferStrategy(numBuffers);
+	return;
+      }
+    catch (AWTException e)
+      {
+      }
+
+    // try an accelerated blitting strategy
+    try
+      {
+	bufferStrategy = new CanvasBltBufferStrategy(numBuffers, true);
+      }
+    catch (AWTException e)
+      {
+      }
+
+    // fall back to an unaccelerated blitting strategy
+    try
+      {
+	bufferStrategy = new CanvasBltBufferStrategy(numBuffers, false);
+      }
+    catch (AWTException e)
+      {
+      }
+  }
+
+  /**
+   * Creates a buffering strategy that manages how this canvas is
+   * repainted.  This method attempts to create a strategy based on
+   * the specified capabilities and throws an exception if the
+   * requested strategy is not supported.
+   *
+   * Calling this method causes any existing buffer strategy to be
+   * destroyed.
+   *
+   * @param numBuffers the number of buffers in this strategy
+   * @param caps the requested buffering capabilities
+   *
+   * @throws AWTException if the requested capabilities are not
+   * supported
+   * @throws IllegalArgumentException if requested number of buffers
+   * is less than one or if caps is null
+   *
+   * @since 1.4
+   */
+  public void createBufferStrategy(int numBuffers,
+				   BufferCapabilities caps)
+  {
+    if (numBuffers < 1)
+      throw new IllegalArgumentException("Canvas.createBufferStrategy: number"
+					 + " of buffers is less than one");
+
+    if (caps == null)
+      throw new IllegalArgumentException("Canvas.createBufferStrategy:"
+					 + " capabilities object is null");
+
+    // a flipping strategy was requested
+    if (caps.isPageFlipping())
+      {
+	try
+	  {
+	    bufferStrategy = new CanvasFlipBufferStrategy(numBuffers);
+	  }
+	catch (AWTException e)
+	  {
+	  }
+      }
+    else
+      bufferStrategy = new CanvasBltBufferStrategy(numBuffers, true);
+  }
+
+  /**
    * Returns the buffer strategy used by the canvas.
    *
    * @return the buffer strategy.
@@ -211,5 +362,4 @@ public class Canvas
     /* Call the paint method */
     paint(graphics);
   }
-
 }

libjava/java/awt/Window.java

@@ -45,6 +45,7 @@ import java.awt.event.WindowEvent;
 import java.awt.event.WindowFocusListener;
 import java.awt.event.WindowListener;
 import java.awt.event.WindowStateListener;
+import java.awt.image.BufferStrategy;
 import java.awt.peer.WindowPeer;
 import java.lang.ref.Reference;
 import java.lang.ref.WeakReference;
@@ -797,6 +798,168 @@ public class Window extends Container implements Accessible
   }
 
   /**
+   * A BltBufferStrategy for windows.
+   */
+  private class WindowBltBufferStrategy extends BltBufferStrategy
+  {
+    /**
+     * Creates a block transfer strategy for this window.
+     *
+     * @param numBuffers the number of buffers in this strategy
+     * @param accelerated true if the buffer should be accelerated,
+     * false otherwise
+     */
+    WindowBltBufferStrategy(int numBuffers, boolean accelerated)
+    {
+      super(numBuffers,
+	    new BufferCapabilities(new ImageCapabilities(accelerated),
+				   new ImageCapabilities(accelerated),
+				   BufferCapabilities.FlipContents.COPIED));
+    }
+  }
+
+  /**
+   * A FlipBufferStrategy for windows.
+   */
+  private class WindowFlipBufferStrategy extends FlipBufferStrategy
+  {
+    /**
+     * Creates a flip buffer strategy for this window.
+     *
+     * @param numBuffers the number of buffers in this strategy
+     *
+     * @throws AWTException if the requested number of buffers is not
+     * supported
+     */
+    WindowFlipBufferStrategy(int numBuffers)
+      throws AWTException
+    {
+      super(numBuffers,
+	    new BufferCapabilities(new ImageCapabilities(true),
+				   new ImageCapabilities(true),
+				   BufferCapabilities.FlipContents.COPIED));
+    }
+  }
+
+  /**
+   * Creates a buffering strategy that manages how this window is
+   * repainted.  This method attempts to create the optimum strategy
+   * based on the desired number of buffers.  Hardware or software
+   * acceleration may be used.
+   *
+   * createBufferStrategy attempts different levels of optimization,
+   * but guarantees that some strategy with the requested number of
+   * buffers will be created even if it is not optimal.  First it
+   * attempts to create a page flipping strategy, then an accelerated
+   * blitting strategy, then an unaccelerated blitting strategy.
+   *
+   * Calling this method causes any existing buffer strategy to be
+   * destroyed.
+   *
+   * @param numBuffers the number of buffers in this strategy
+   *
+   * @throws IllegalArgumentException if requested number of buffers
+   * is less than one
+   * @throws IllegalStateException if this window is not displayable
+   *
+   * @since 1.4
+   */
+  public void createBufferStrategy(int numBuffers)
+  {
+    if (numBuffers < 1)
+      throw new IllegalArgumentException("Window.createBufferStrategy: number"
+					 + " of buffers is less than one");
+
+    if (!isDisplayable())
+      throw new IllegalStateException("Window.createBufferStrategy: window is"
+				      + " not displayable");
+
+    // try a flipping strategy
+    try
+      {
+	bufferStrategy = new WindowFlipBufferStrategy(numBuffers);
+	return;
+      }
+    catch (AWTException e)
+      {
+      }
+
+    // try an accelerated blitting strategy
+    try
+      {
+	bufferStrategy = new WindowBltBufferStrategy(numBuffers, true);
+      }
+    catch (AWTException e)
+      {
+      }
+
+    // fall back to an unaccelerated blitting strategy
+    try
+      {
+	bufferStrategy = new WindowBltBufferStrategy(numBuffers, false);
+      }
+    catch (AWTException e)
+      {
+      }
+  }
+
+  /**
+   * Creates a buffering strategy that manages how this window is
+   * repainted.  This method attempts to create a strategy based on
+   * the specified capabilities and throws an exception if the
+   * requested strategy is not supported.
+   *
+   * Calling this method causes any existing buffer strategy to be
+   * destroyed.
+   *
+   * @param numBuffers the number of buffers in this strategy
+   * @param caps the requested buffering capabilities
+   *
+   * @throws AWTException if the requested capabilities are not
+   * supported
+   * @throws IllegalArgumentException if requested number of buffers
+   * is less than one or if caps is null
+   *
+   * @since 1.4
+   */
+  public void createBufferStrategy(int numBuffers,
+				   BufferCapabilities caps)
+  {
+    if (numBuffers < 1)
+      throw new IllegalArgumentException("Window.createBufferStrategy: number"
+					 + " of buffers is less than one");
+
+    if (caps == null)
+      throw new IllegalArgumentException("Window.createBufferStrategy:"
+					 + " capabilities object is null");
+
+    // a flipping strategy was requested
+    if (caps.isPageFlipping())
+      {
+	try
+	  {
+	    bufferStrategy = new WindowFlipBufferStrategy(numBuffers);
+	  }
+	catch (AWTException e)
+	  {
+	  }
+      }
+    else
+      bufferStrategy = new WindowBltBufferStrategy(numBuffers, true);
+  }
+
+  /**
+   * Returns the buffer strategy used by the window.
+   *
+   * @return the buffer strategy.
+   * @since 1.4
+   */
+  public BufferStrategy getBufferStrategy()
+  {
+    return bufferStrategy;
+  }
+
+  /**
    * @since 1.2
    *
    * @deprecated

libjava/java/awt/image/BufferStrategy.java

@@ -96,23 +96,22 @@ public abstract class BufferStrategy
 
   /**
    * Returns whether or not the buffer's resources have been reclaimed
-   * by the native graphics system since the last call to
-   * getDrawGraphics.  If the buffer resources have been lost then
-   * you'll need to obtain new resources before drawing again.  For
-   * details, see the documentation for VolatileImage.
+   * by the native graphics system.  If the buffer resources have been
+   * lost then you'll need to obtain new resources before drawing
+   * again.  For details, see the documentation for VolatileImage.
    *
-   * @return true if the contents were lost since the last call to
-   * getDrawGraphics, false otherwise
+   * @return true if the contents were lost, false otherwise
    */
   public abstract boolean contentsLost();
 
   /**
    * Returns whether or not the buffer's resources were re-created and
-   * cleared to the default background color since the last call to
-   * getDrawGraphics.  If the buffer's resources have recently been
-   * re-created and initialized then the buffer's image may need to be
-   * re-rendered.  For details, see the documentation for
-   * VolatileImage.
+   * cleared to the default background color.  If the buffer's
+   * resources have recently been re-created and initialized then the
+   * buffer's image may need to be re-rendered.  For details, see the
+   * documentation for VolatileImage.
+   *
+   * @return true if the contents were restored, false otherwise
    */
   public abstract boolean contentsRestored();
 

libjava/java/awt/image/VolatileImage.java

@@ -79,8 +79,7 @@ public abstract class VolatileImage extends Image
    * One of validate's possible return values.  Indicates that the
    * image buffer has been restored, meaning that it is valid and
    * ready-to-use but that its previous contents have been lost.  This
-   * return value implies IMAGE_OK but that the image needs to be
-   * re-rendered.
+   * return value implies that the image needs to be re-rendered.
    */
   public static final int IMAGE_RESTORED = 1;
 
@@ -212,7 +211,7 @@ public abstract class VolatileImage extends Image
    *   <li><code>IMAGE_OK</code> if the image did not need to be
    *   validated and didn't need to be restored</li>
    *   <li><code>IMAGE_RESTORED</code> if the image may need to be
-   *   re-rendered.  This return value implies IMAGE_OK.</li>
+   *   re-rendered.</li>
    *   <li><code>IMAGE_INCOMPATIBLE</code> if this image's
    *   requirements are not fulfilled by the graphics configuration
    *   parameter.  This implies that you need to create a new

libjava/java/awt/peer/ComponentPeer.java

@@ -128,11 +128,60 @@ public interface ComponentPeer
   boolean canDetermineObscurity();
   void coalescePaintEvent(PaintEvent e);
   void updateCursorImmediately();
-  VolatileImage createVolatileImage(int width, int height);
   boolean handlesWheelScrolling();
-  void createBuffers(int x, BufferCapabilities capabilities) throws AWTException;
+
+  /**
+   * A convenience method that creates a volatile image.  The volatile
+   * image is created on the screen device on which this component is
+   * displayed, in the device's current graphics configuration.
+   *
+   * @param width width of the image
+   * @param height height of the image
+   *
+   * @see VolatileImage
+   *
+   * @since 1.2
+   */
+  VolatileImage createVolatileImage(int width, int height);
+
+  /**
+   * Create a number of image buffers that implement a buffering
+   * strategy according to the given capabilities.
+   *
+   * @param numBuffers the number of buffers
+   * @param caps the buffering capabilities
+   *
+   * @throws AWTException if the specified buffering strategy is not
+   * implemented
+   *
+   * @since 1.2
+   */
+  void createBuffers(int numBuffers, BufferCapabilities caps)
+    throws AWTException;
+
+  /**
+   * Return the back buffer of this component.
+   *
+   * @return the back buffer of this component.
+   *
+   * @since 1.2
+   */
   Image getBackBuffer();
+
+  /**
+   * Perform a page flip, leaving the contents of the back buffer in
+   * the specified state.
+   *
+   * @param contents the state in which to leave the back buffer
+   *
+   * @since 1.2
+   */
   void flip(BufferCapabilities.FlipContents contents);
+
+  /**
+   * Destroy the resources created by createBuffers.
+   *
+   * @since 1.2
+   */
   void destroyBuffers();
-  
 }