diff options
| -rw-r--r-- | libjava/ChangeLog | 2 | ||||
| -rw-r--r-- | libjava/java/awt/image/BufferStrategy.java | 78 |
2 files changed, 76 insertions, 4 deletions
diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 428d2fc1366..8b196b5e3ec 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,5 +1,7 @@ 2005-05-04 Thomas Fitzsimmons <fitzsim@redhat.com> + * java/awt/image/BufferStrategy.java: Document. + * java/awt/BufferCapabilities.java: Document. 2005-05-04 Tom Tromey <tromey@redhat.com> diff --git a/libjava/java/awt/image/BufferStrategy.java b/libjava/java/awt/image/BufferStrategy.java index 88d4912307f..d0e74c0795e 100644 --- a/libjava/java/awt/image/BufferStrategy.java +++ b/libjava/java/awt/image/BufferStrategy.java @@ -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 @@ package java.awt.image; 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 +} |