1 /* 2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 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 * 60 * *********** *********** 61 * * * ------> * * 62 * [To display] <---- * Front B * Show * Back B. * <---- Rendering 63 * * * <------ * * 64 * *********** *********** 65 * 66 * Triple buffering: 67 * 68 * [To *********** *********** *********** 69 * display] * * --------+---------+------> * * 70 * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering 71 * * * <------ * * <----- * * 72 * *********** *********** *********** 73 * 74 * }</pre> 75 * <p> 76 * Here is an example of how buffer strategies can be created and used: 77 * <pre><code> 78 * 79 * // Check the capabilities of the GraphicsConfiguration 80 * ... 81 * 82 * // Create our component 83 * Window w = new Window(gc); 84 * 85 * // Show our window 86 * w.setVisible(true); 87 * 88 * // Create a general double-buffering strategy 89 * w.createBufferStrategy(2); 90 * BufferStrategy strategy = w.getBufferStrategy(); 91 * 92 * // Main loop 93 * while (!done) { 94 * // Prepare for rendering the next frame 95 * // ... 96 * 97 * // Render single frame 98 * do { 99 * // The following loop ensures that the contents of the drawing buffer 100 * // are consistent in case the underlying surface was recreated 101 * do { 102 * // Get a new graphics context every time through the loop 103 * // to make sure the strategy is validated 104 * Graphics graphics = strategy.getDrawGraphics(); 105 * 106 * // Render to graphics 107 * // ... 108 * 109 * // Dispose the graphics 110 * graphics.dispose(); 111 * 112 * // Repeat the rendering if the drawing buffer contents 113 * // were restored 114 * } while (strategy.contentsRestored()); 115 * 116 * // Display the buffer 117 * strategy.show(); 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 }