< prev index next >

src/java.desktop/share/classes/java/awt/image/BufferStrategy.java

Print this page




  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.image;
  27 
  28 import java.awt.BufferCapabilities;
  29 import java.awt.Graphics;
  30 import java.awt.Image;
  31 
  32 /**
  33  * The <code>BufferStrategy</code> class represents the mechanism with which
  34  * to organize complex memory on a particular <code>Canvas</code> or
  35  * <code>Window</code>.  Hardware and software limitations determine whether and
  36  * how a particular buffer strategy can be implemented.  These limitations
  37  * are detectable through the capabilities of the
  38  * <code>GraphicsConfiguration</code> used when creating the
  39  * <code>Canvas</code> or <code>Window</code>.
  40  * <p>
  41  * It is worth noting that the terms <i>buffer</i> and <i>surface</i> are meant
  42  * to be synonymous: an area of contiguous memory, either in video device
  43  * memory or in system memory.
  44  * <p>
  45  * There are several types of complex buffer strategies, including
  46  * sequential ring buffering and blit buffering.
  47  * Sequential ring buffering (i.e., double or triple
  48  * buffering) is the most common; an application draws to a single <i>back
  49  * buffer</i> and then moves the contents to the front (display) in a single
  50  * step, either by copying the data or moving the video pointer.
  51  * Moving the video pointer exchanges the buffers so that the first buffer
  52  * drawn becomes the <i>front buffer</i>, or what is currently displayed on the
  53  * device; this is called <i>page flipping</i>.
  54  * <p>
  55  * Alternatively, the contents of the back buffer can be copied, or
  56  * <i>blitted</i> forward in a chain instead of moving the video pointer.
  57  * <pre>{@code
  58  * Double buffering:
  59  *


 118  *
 119  *         // Repeat the rendering if the drawing buffer was lost
 120  *     } while (strategy.contentsLost());
 121  * }
 122  *
 123  * // Dispose the window
 124  * w.setVisible(false);
 125  * w.dispose();
 126  * </code></pre>
 127  *
 128  * @see java.awt.Window
 129  * @see java.awt.Canvas
 130  * @see java.awt.GraphicsConfiguration
 131  * @see VolatileImage
 132  * @author Michael Martak
 133  * @since 1.4
 134  */
 135 public abstract class BufferStrategy {
 136 
 137     /**
 138      * Returns the <code>BufferCapabilities</code> for this
 139      * <code>BufferStrategy</code>.
 140      *
 141      * @return the buffering capabilities of this strategy
 142      */
 143     public abstract BufferCapabilities getCapabilities();
 144 
 145     /**
 146      * Creates a graphics context for the drawing buffer.  This method may not
 147      * be synchronized for performance reasons; use of this method by multiple
 148      * threads should be handled at the application level.  Disposal of the
 149      * graphics object obtained must be handled by the application.
 150      *
 151      * @return a graphics context for the drawing buffer
 152      */
 153     public abstract Graphics getDrawGraphics();
 154 
 155     /**
 156      * Returns whether the drawing buffer was lost since the last call to
 157      * <code>getDrawGraphics</code>.  Since the buffers in a buffer strategy
 158      * are usually type <code>VolatileImage</code>, they may become lost.
 159      * For a discussion on lost buffers, see <code>VolatileImage</code>.
 160      *
 161      * @return Whether or not the drawing buffer was lost since the last call
 162      * to <code>getDrawGraphics</code>.
 163      * @see java.awt.image.VolatileImage
 164      */
 165     public abstract boolean contentsLost();
 166 
 167     /**
 168      * Returns whether the drawing buffer was recently restored from a lost
 169      * state and reinitialized to the default background color (white).
 170      * Since the buffers in a buffer strategy are usually type
 171      * <code>VolatileImage</code>, they may become lost.  If a surface has
 172      * been recently restored from a lost state since the last call to
 173      * <code>getDrawGraphics</code>, it may require repainting.
 174      * For a discussion on lost buffers, see <code>VolatileImage</code>.
 175      *
 176      * @return Whether or not the drawing buffer was restored since the last
 177      *         call to <code>getDrawGraphics</code>.
 178      * @see java.awt.image.VolatileImage
 179      */
 180     public abstract boolean contentsRestored();
 181 
 182     /**
 183      * Makes the next available buffer visible by either copying the memory
 184      * (blitting) or changing the display pointer (flipping).
 185      */
 186     public abstract void show();
 187 
 188     /**
 189      * Releases system resources currently consumed by this
 190      * <code>BufferStrategy</code> and
 191      * removes it from the associated Component.  After invoking this
 192      * method, <code>getBufferStrategy</code> will return null.  Trying
 193      * to use a <code>BufferStrategy</code> after it has been disposed will
 194      * result in undefined behavior.
 195      *
 196      * @see java.awt.Window#createBufferStrategy
 197      * @see java.awt.Canvas#createBufferStrategy
 198      * @see java.awt.Window#getBufferStrategy
 199      * @see java.awt.Canvas#getBufferStrategy
 200      * @since 1.6
 201      */
 202     public void dispose() {
 203     }
 204 }


  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.image;
  27 
  28 import java.awt.BufferCapabilities;
  29 import java.awt.Graphics;
  30 import java.awt.Image;
  31 
  32 /**
  33  * The {@code BufferStrategy} class represents the mechanism with which
  34  * to organize complex memory on a particular {@code Canvas} or
  35  * {@code Window}.  Hardware and software limitations determine whether and
  36  * how a particular buffer strategy can be implemented.  These limitations
  37  * are detectable through the capabilities of the
  38  * {@code GraphicsConfiguration} used when creating the
  39  * {@code Canvas} or {@code Window}.
  40  * <p>
  41  * It is worth noting that the terms <i>buffer</i> and <i>surface</i> are meant
  42  * to be synonymous: an area of contiguous memory, either in video device
  43  * memory or in system memory.
  44  * <p>
  45  * There are several types of complex buffer strategies, including
  46  * sequential ring buffering and blit buffering.
  47  * Sequential ring buffering (i.e., double or triple
  48  * buffering) is the most common; an application draws to a single <i>back
  49  * buffer</i> and then moves the contents to the front (display) in a single
  50  * step, either by copying the data or moving the video pointer.
  51  * Moving the video pointer exchanges the buffers so that the first buffer
  52  * drawn becomes the <i>front buffer</i>, or what is currently displayed on the
  53  * device; this is called <i>page flipping</i>.
  54  * <p>
  55  * Alternatively, the contents of the back buffer can be copied, or
  56  * <i>blitted</i> forward in a chain instead of moving the video pointer.
  57  * <pre>{@code
  58  * Double buffering:
  59  *


 118  *
 119  *         // Repeat the rendering if the drawing buffer was lost
 120  *     } while (strategy.contentsLost());
 121  * }
 122  *
 123  * // Dispose the window
 124  * w.setVisible(false);
 125  * w.dispose();
 126  * </code></pre>
 127  *
 128  * @see java.awt.Window
 129  * @see java.awt.Canvas
 130  * @see java.awt.GraphicsConfiguration
 131  * @see VolatileImage
 132  * @author Michael Martak
 133  * @since 1.4
 134  */
 135 public abstract class BufferStrategy {
 136 
 137     /**
 138      * Returns the {@code BufferCapabilities} for this
 139      * {@code BufferStrategy}.
 140      *
 141      * @return the buffering capabilities of this strategy
 142      */
 143     public abstract BufferCapabilities getCapabilities();
 144 
 145     /**
 146      * Creates a graphics context for the drawing buffer.  This method may not
 147      * be synchronized for performance reasons; use of this method by multiple
 148      * threads should be handled at the application level.  Disposal of the
 149      * graphics object obtained must be handled by the application.
 150      *
 151      * @return a graphics context for the drawing buffer
 152      */
 153     public abstract Graphics getDrawGraphics();
 154 
 155     /**
 156      * Returns whether the drawing buffer was lost since the last call to
 157      * {@code getDrawGraphics}.  Since the buffers in a buffer strategy
 158      * are usually type {@code VolatileImage}, they may become lost.
 159      * For a discussion on lost buffers, see {@code VolatileImage}.
 160      *
 161      * @return Whether or not the drawing buffer was lost since the last call
 162      * to {@code getDrawGraphics}.
 163      * @see java.awt.image.VolatileImage
 164      */
 165     public abstract boolean contentsLost();
 166 
 167     /**
 168      * Returns whether the drawing buffer was recently restored from a lost
 169      * state and reinitialized to the default background color (white).
 170      * Since the buffers in a buffer strategy are usually type
 171      * {@code VolatileImage}, they may become lost.  If a surface has
 172      * been recently restored from a lost state since the last call to
 173      * {@code getDrawGraphics}, it may require repainting.
 174      * For a discussion on lost buffers, see {@code VolatileImage}.
 175      *
 176      * @return Whether or not the drawing buffer was restored since the last
 177      *         call to {@code getDrawGraphics}.
 178      * @see java.awt.image.VolatileImage
 179      */
 180     public abstract boolean contentsRestored();
 181 
 182     /**
 183      * Makes the next available buffer visible by either copying the memory
 184      * (blitting) or changing the display pointer (flipping).
 185      */
 186     public abstract void show();
 187 
 188     /**
 189      * Releases system resources currently consumed by this
 190      * {@code BufferStrategy} and
 191      * removes it from the associated Component.  After invoking this
 192      * method, {@code getBufferStrategy} will return null.  Trying
 193      * to use a {@code BufferStrategy} after it has been disposed will
 194      * result in undefined behavior.
 195      *
 196      * @see java.awt.Window#createBufferStrategy
 197      * @see java.awt.Canvas#createBufferStrategy
 198      * @see java.awt.Window#getBufferStrategy
 199      * @see java.awt.Canvas#getBufferStrategy
 200      * @since 1.6
 201      */
 202     public void dispose() {
 203     }
 204 }
< prev index next >