This is the mail archive of the
java-patches@gcc.gnu.org
mailing list for the Java project.
[patch] document BufferStrategy
- From: Thomas Fitzsimmons <fitzsim at redhat dot com>
- To: classpath-patches at gnu dot org
- Cc: java-patches at gcc dot gnu dot org
- Date: Wed, 04 May 2005 21:23:06 -0400
- Subject: [patch] document BufferStrategy
Hi,
I committed this patch to GNU Classpath and libgcj mainline.
Tom
2005-05-04 Thomas Fitzsimmons <fitzsim@redhat.com>
* java/awt/image/BufferStrategy.java: Document.
Index: java/awt/image/BufferStrategy.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/awt/image/BufferStrategy.java,v
retrieving revision 1.1
diff -u -u -r1.1 BufferStrategy.java
--- java/awt/image/BufferStrategy.java 9 Aug 2002 04:26:16 -0000 1.1
+++ java/awt/image/BufferStrategy.java 5 May 2005 01:21:51 -0000
@@ -1,5 +1,5 @@
-/* BufferStrategy.java --
- Copyright (C) 2002 Free Software Foundation, Inc.
+/* BufferStrategy.java -- describes image buffering resources
+ Copyright (C) 2002, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -41,15 +41,85 @@
import java.awt.BufferCapabilities;
import java.awt.Graphics;
-/** STUBS ONLY */
+/**
+ * This class describes a strategy for managing image buffering
+ * resources on a Canvas or Window. A given buffer strategy may make
+ * use of hardware acceleration or take advantage of features of the
+ * native graphics system. Examples of buffering strategies are
+ * double or triple buffering using either flipping or blitting. For
+ * the details of these algorithms see BufferCapabilities.
+ *
+ * To use a buffer strategy, you retrieve it from either the current
+ * GraphicsConfiguration or from the Component on which you'd like to
+ * draw. Then you can query the strategy's capabilities to make sure
+ * they're suitable.
+ *
+ * If the strategy's capabilities are suitable, you can obtain a
+ * graphics object and use it to draw with this strategy. Drawing
+ * with a buffer strategy requires extra care, however. You'll need
+ * to manually cause the next buffer to be shown on the output device.
+ * And since buffer strategies are usually implemented with a
+ * VolatileImage, you must frequently check that the contents of the
+ * buffer are valid and that the buffer still exists.
+ *
+ * A buffer strategy is usually implemented using a VolatileImage.
+ *
+ * @see VolatileImage
+ * @since 1.4
+ */
public abstract class BufferStrategy
{
+ /**
+ * Creates a new buffer strategy.
+ */
public BufferStrategy()
{
}
+
+ /**
+ * Retrieves the capabilities of this buffer strategy.
+ *
+ * @return this buffer strategy's capabilities
+ */
public abstract BufferCapabilities getCapabilities();
+
+ /**
+ * Retrieves a graphics object that can be used to draw using this
+ * buffer strategy. This method may not be synchronized so be
+ * careful when calling it from multiple threads. You also must
+ * manually dispose of this graphics object.
+ *
+ * @return a graphics object that can be used to draw using this
+ * buffer strategy
+ */
public abstract Graphics getDrawGraphics();
+
+ /**
+ * 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.
+ *
+ * @return true if the contents were lost since the last call to
+ * getDrawGraphics, 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.
+ */
public abstract boolean contentsRestored();
+
+ /**
+ * Applies this buffer strategy. In other words, this method brings
+ * the contents of the back or intermediate buffers to the front
+ * buffer.
+ */
public abstract void show();
-} // class BufferStrategy
+}