View Javadoc
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</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   *
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</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 }