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 } |