2362N/A * Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The <code>BufferStrategy</code> class represents the mechanism with which 0N/A * to organize complex memory on a particular <code>Canvas</code> or 0N/A * <code>Window</code>. Hardware and software limitations determine whether and 0N/A * how a particular buffer strategy can be implemented. These limitations 0N/A * are detectible through the capabilities of the 0N/A * <code>GraphicsConfiguration</code> used when creating the 0N/A * <code>Canvas</code> or <code>Window</code>. 0N/A * It is worth noting that the terms <i>buffer</i> and <i>surface</i> are meant 0N/A * to be synonymous: an area of contiguous memory, either in video device 0N/A * memory or in system memory. 0N/A * There are several types of complex buffer strategies, including 0N/A * sequential ring buffering and blit buffering. 0N/A * Sequential ring buffering (i.e., double or triple 0N/A * buffering) is the most common; an application draws to a single <i>back 0N/A * buffer</i> and then moves the contents to the front (display) in a single 0N/A * step, either by copying the data or moving the video pointer. 0N/A * Moving the video pointer exchanges the buffers so that the first buffer 0N/A * drawn becomes the <i>front buffer</i>, or what is currently displayed on the 0N/A * device; this is called <i>page flipping</i>. 0N/A * Alternatively, the contents of the back buffer can be copied, or 0N/A * <i>blitted</i> forward in a chain instead of moving the video pointer. 0N/A * *********** *********** 0N/A * [To display] <---- * Front B * Show * Back B. * <---- Rendering 0N/A * *********** *********** 0N/A * [To *********** *********** *********** 0N/A * display] * * --------+---------+------> * * 0N/A * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering 0N/A * * * <------ * * <----- * * 0N/A * *********** *********** *********** 0N/A * Here is an example of how buffer strategies can be created and used: 0N/A * // Check the capabilities of the GraphicsConfiguration 0N/A * // Create our component 0N/A * Window w = new Window(gc); 0N/A * // Show our window 0N/A * w.setVisible(true); 0N/A * // Create a general double-buffering strategy 0N/A * w.createBufferStrategy(2); 0N/A * BufferStrategy strategy = w.getBufferStrategy(); 0N/A * // Prepare for rendering the next frame 0N/A * // Render single frame 0N/A * // The following loop ensures that the contents of the drawing buffer 0N/A * // are consistent in case the underlying surface was recreated 0N/A * // Get a new graphics context every time through the loop 0N/A * // to make sure the strategy is validated 0N/A * Graphics graphics = strategy.getDrawGraphics(); 0N/A * // Render to graphics 0N/A * // Dispose the graphics 0N/A * graphics.dispose(); 0N/A * // Repeat the rendering if the drawing buffer contents 0N/A * } while (strategy.contentsRestored()); 0N/A * // Display the buffer 0N/A * // Repeat the rendering if the drawing buffer was lost 0N/A * } while (strategy.contentsLost()); 0N/A * // Dispose the window 0N/A * w.setVisible(false); 0N/A * @see java.awt.Window 0N/A * @see java.awt.Canvas 0N/A * @see java.awt.GraphicsConfiguration 0N/A * @see VolatileImage 0N/A * @author Michael Martak 0N/A * Returns the <code>BufferCapabilities</code> for this 0N/A * <code>BufferStrategy</code>. 0N/A * @return the buffering capabilities of this strategy 0N/A * Creates a graphics context for the drawing buffer. This method may not 0N/A * be synchronized for performance reasons; use of this method by multiple 0N/A * threads should be handled at the application level. Disposal of the 0N/A * graphics object obtained must be handled by the application. 0N/A * @return a graphics context for the drawing buffer 0N/A * Returns whether the drawing buffer was lost since the last call to 0N/A * <code>getDrawGraphics</code>. Since the buffers in a buffer strategy 0N/A * are usually type <code>VolatileImage</code>, they may become lost. 0N/A * For a discussion on lost buffers, see <code>VolatileImage</code>. 0N/A * @return Whether or not the drawing buffer was lost since the last call 0N/A * to <code>getDrawGraphics</code>. 0N/A * @see java.awt.image.VolatileImage 0N/A * Returns whether the drawing buffer was recently restored from a lost 0N/A * state and reinitialized to the default background color (white). 0N/A * Since the buffers in a buffer strategy are usually type 0N/A * <code>VolatileImage</code>, they may become lost. If a surface has 0N/A * been recently restored from a lost state since the last call to 0N/A * <code>getDrawGraphics</code>, it may require repainting. 0N/A * For a discussion on lost buffers, see <code>VolatileImage</code>. 0N/A * @return Whether or not the drawing buffer was restored since the last 0N/A * call to <code>getDrawGraphics</code>. 0N/A * @see java.awt.image.VolatileImage 0N/A * Makes the next available buffer visible by either copying the memory 0N/A * (blitting) or changing the display pointer (flipping). 0N/A * Releases system resources currently consumed by this 0N/A * <code>BufferStrategy</code> and 0N/A * removes it from the associated Component. After invoking this 0N/A * method, <code>getBufferStrategy</code> will return null. Trying 0N/A * to use a <code>BufferStrategy</code> after it has been disposed will 0N/A * result in undefined behavior. 0N/A * @see java.awt.Window#createBufferStrategy 0N/A * @see java.awt.Canvas#createBufferStrategy 0N/A * @see java.awt.Window#getBufferStrategy 0N/A * @see java.awt.Canvas#getBufferStrategy