1 /* 2 * Copyright (c) 2000, 2020, 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 * Constructor for subclasses to call. 139 */ 140 protected BufferStrategy() {} 141 142 /** 143 * Returns the {@code BufferCapabilities} for this 144 * {@code BufferStrategy}. 145 * 146 * @return the buffering capabilities of this strategy 147 */ 148 public abstract BufferCapabilities getCapabilities(); 149 150 /** 151 * Creates a graphics context for the drawing buffer. This method may not 152 * be synchronized for performance reasons; use of this method by multiple 153 * threads should be handled at the application level. Disposal of the 154 * graphics object obtained must be handled by the application. 155 * 156 * @return a graphics context for the drawing buffer 157 */ 158 public abstract Graphics getDrawGraphics(); 159 160 /** 161 * Returns whether the drawing buffer was lost since the last call to 162 * {@code getDrawGraphics}. Since the buffers in a buffer strategy 163 * are usually type {@code VolatileImage}, they may become lost. 164 * For a discussion on lost buffers, see {@code VolatileImage}. 165 * 166 * @return Whether or not the drawing buffer was lost since the last call 167 * to {@code getDrawGraphics}. 168 * @see java.awt.image.VolatileImage 169 */ 170 public abstract boolean contentsLost(); 171 172 /** 173 * Returns whether the drawing buffer was recently restored from a lost 174 * state and reinitialized to the default background color (white). 175 * Since the buffers in a buffer strategy are usually type 176 * {@code VolatileImage}, they may become lost. If a surface has 177 * been recently restored from a lost state since the last call to 178 * {@code getDrawGraphics}, it may require repainting. 179 * For a discussion on lost buffers, see {@code VolatileImage}. 180 * 181 * @return Whether or not the drawing buffer was restored since the last 182 * call to {@code getDrawGraphics}. 183 * @see java.awt.image.VolatileImage 184 */ 185 public abstract boolean contentsRestored(); 186 187 /** 188 * Makes the next available buffer visible by either copying the memory 189 * (blitting) or changing the display pointer (flipping). 190 */ 191 public abstract void show(); 192 193 /** 194 * Releases system resources currently consumed by this 195 * {@code BufferStrategy} and 196 * removes it from the associated Component. After invoking this 197 * method, {@code getBufferStrategy} will return null. Trying 198 * to use a {@code BufferStrategy} after it has been disposed will 199 * result in undefined behavior. 200 * 201 * @see java.awt.Window#createBufferStrategy 202 * @see java.awt.Canvas#createBufferStrategy 203 * @see java.awt.Window#getBufferStrategy 204 * @see java.awt.Canvas#getBufferStrategy 205 * @since 1.6 206 */ 207 public void dispose() { 208 } 209 }