/*
* @(#)BufferStrategy.java 1.6 03/12/19
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package java.awt.image;
import java.awt.BufferCapabilities;
import java.awt.Graphics;
import java.awt.Image;
/**
* The BufferStrategy
class represents the mechanism with which
* to organize complex memory on a particular Canvas
or
* Window
. Hardware and software limitations determine whether and
* how a particular buffer strategy can be implemented. These limitations
* are detectible through the capabilities of the
* GraphicsConfiguration
used when creating the
* Canvas
or Window
.
*
* It is worth noting that the terms buffer and surface are meant * to be synonymous: an area of contiguous memory, either in video device * memory or in system memory. *
* There are several types of complex buffer strategies; * sequential ring buffering, blit buffering, and stereo buffering are * common types. Sequential ring buffering (i.e., double or triple * buffering) is the most common; an application draws to a single back * buffer and then moves the contents to the front (display) in a single * step, either by copying the data or moving the video pointer. * Moving the video pointer exchanges the buffers so that the first buffer * drawn becomes the front buffer, or what is currently displayed on the * device; this is called page flipping. *
* Alternatively, the contents of the back buffer can be copied, or * blitted forward in a chain instead of moving the video pointer. *
*
* Double buffering: * * *********** *********** * * * ------> * * * [To display] <---- * Front B * Show * Back B. * <---- Rendering * * * <------ * * * *********** *********** * * Triple buffering: * * [To *********** *********** *********** * display] * * --------+---------+------> * * * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering * * * <------ * * <----- * * * *********** *********** *********** * **
* Stereo buffering is for hardware that supports rendering separate images for * a left and right eye. It is similar to sequential ring buffering, but * there are two buffer chains, one for each eye. Both buffer chains flip * simultaneously: * *
* Stereo buffering: * * *********** *********** * * * ------> * * * [To left eye] <---- * Front B * * Back B. * <---- Rendering * * * <------ * * * *********** *********** * Show * *********** *********** * * * ------> * * * [To right eye] <--- * Front B * * Back B. * <---- Rendering * * * <------ * * * *********** *********** **
* Here is an example of how buffer strategies can be created and used: *
*
* // Check the capabilities of the GraphicsConfiguration
* ...
*
* // Create our component
* Window w = new Window(gc);
*
* // Show our window
* w.setVisible(true);
*
* // Create a general double-buffering strategy
* w.createBufferStrategy(2);
* BufferStrategy strategy = w.getBufferStrategy();
*
* // Render loop
* while (!done) {
* Graphics g = strategy.getDrawGraphics();
* // Draw to graphics
* ...
* strategy.show();
* }
*
* // Dispose the window
* w.setVisible(false);
* w.dispose();
*
*
* @see java.awt.Component
* @see java.awt.GraphicsConfiguration
* @author Michael Martak
* @since 1.4
*/
public abstract class BufferStrategy {
/**
* @return the buffering capabilities of this strategy
*/
public abstract BufferCapabilities getCapabilities();
/**
* @return the graphics on the drawing buffer. This method may not
* be synchronized for performance reasons; use of this method by multiple
* threads should be handled at the application level. Disposal of the
* graphics object obtained must be handled by the application.
*/
public abstract Graphics getDrawGraphics();
/**
* Returns whether the drawing buffer was lost since the last call to
* getDrawGraphics
. Since the buffers in a buffer strategy
* are usually type VolatileImage
, they may become lost.
* For a discussion on lost buffers, see VolatileImage
.
* @see java.awt.image.VolatileImage
*/
public abstract boolean contentsLost();
/**
* Returns whether the drawing buffer was recently restored from a lost
* state and reinitialized to the default background color (white).
* Since the buffers in a buffer strategy are usually type
* VolatileImage
, they may become lost. If a surface has
* been recently restored from a lost state since the last call to
* getDrawGraphics
, it may require repainting.
* For a discussion on lost buffers, see VolatileImage
.
* @see java.awt.image.VolatileImage
*/
public abstract boolean contentsRestored();
/**
* Makes the next available buffer visible by either copying the memory
* (blitting) or changing the display pointer (flipping).
*/
public abstract void show();
}