1 /*
2 * Copyright 2000-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 detectible 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 * <p>
58 * <pre>
59 * Double buffering:
60 *
61 * *********** ***********
62 * * * ------> * *
63 * [To display] <---- * Front B * Show * Back B. * <---- Rendering
64 * * * <------ * *
65 * *********** ***********
66 *
67 * Triple buffering:
68 *
69 * [To *********** *********** ***********
70 * display] * * --------+---------+------> * *
71 * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering
72 * * * <------ * * <----- * *
73 * *********** *********** ***********
74 *
75 * </pre>
76 * <p>
77 * Here is an example of how buffer strategies can be created and used:
78 * <pre><code>
79 *
80 * // Check the capabilities of the GraphicsConfiguration
81 * ...
82 *
83 * // Create our component
84 * Window w = new Window(gc);
85 *
86 * // Show our window
87 * w.setVisible(true);
88 *
89 * // Create a general double-buffering strategy
90 * w.createBufferStrategy(2);
91 * BufferStrategy strategy = w.getBufferStrategy();
92 *
93 * // Main loop
94 * while (!done) {
95 * // Prepare for rendering the next frame
96 * // ...
97 *
98 * // Render single frame
99 * do {
100 * // The following loop ensures that the contents of the drawing buffer
101 * // are consistent in case the underlying surface was recreated
102 * do {
103 * // Get a new graphics context every time through the loop
104 * // to make sure the strategy is validated
105 * Graphics graphics = strategy.getDrawGraphics();
106 *
107 * // Render to graphics
108 * // ...
109 *
110 * // Dispose the graphics
111 * graphics.dispose();
112 *
113 * // Repeat the rendering if the drawing buffer contents
114 * // were restored
115 * } while (strategy.contentsRestored());
116 *
117 * // Display the buffer
118 * strategy.show();
119 *
120 * // Repeat the rendering if the drawing buffer was lost
121 * } while (strategy.contentsLost());
122 * }
123 *
124 * // Dispose the window
125 * w.setVisible(false);
126 * w.dispose();
127 * </code></pre>
128 *
129 * @see java.awt.Window
130 * @see java.awt.Canvas
131 * @see java.awt.GraphicsConfiguration
132 * @see VolatileImage
133 * @author Michael Martak
134 * @since 1.4
135 */
136 public abstract class BufferStrategy {
137
138 /**
139 * Returns the <code>BufferCapabilities</code> for this
140 * <code>BufferStrategy</code>.
141 *
142 * @return the buffering capabilities of this strategy
143 */
144 public abstract BufferCapabilities getCapabilities();
145
146 /**
147 * Creates a graphics context for the drawing buffer. This method may not
148 * be synchronized for performance reasons; use of this method by multiple
149 * threads should be handled at the application level. Disposal of the
150 * graphics object obtained must be handled by the application.
151 *
152 * @return a graphics context for the drawing buffer
153 */
154 public abstract Graphics getDrawGraphics();
155
156 /**
157 * Returns whether the drawing buffer was lost since the last call to
158 * <code>getDrawGraphics</code>. Since the buffers in a buffer strategy
159 * are usually type <code>VolatileImage</code>, they may become lost.
160 * For a discussion on lost buffers, see <code>VolatileImage</code>.
161 *
162 * @return Whether or not the drawing buffer was lost since the last call
163 * to <code>getDrawGraphics</code>.
164 * @see java.awt.image.VolatileImage
165 */
166 public abstract boolean contentsLost();
167
168 /**
169 * Returns whether the drawing buffer was recently restored from a lost
170 * state and reinitialized to the default background color (white).
171 * Since the buffers in a buffer strategy are usually type
172 * <code>VolatileImage</code>, they may become lost. If a surface has
173 * been recently restored from a lost state since the last call to
174 * <code>getDrawGraphics</code>, it may require repainting.
175 * For a discussion on lost buffers, see <code>VolatileImage</code>.
176 *
177 * @return Whether or not the drawing buffer was restored since the last
178 * call to <code>getDrawGraphics</code>.
179 * @see java.awt.image.VolatileImage
180 */
181 public abstract boolean contentsRestored();
182
183 /**
184 * Makes the next available buffer visible by either copying the memory
185 * (blitting) or changing the display pointer (flipping).
186 */
187 public abstract void show();
188
189 /**
190 * Releases system resources currently consumed by this
191 * <code>BufferStrategy</code> and
192 * removes it from the associated Component. After invoking this
193 * method, <code>getBufferStrategy</code> will return null. Trying
194 * to use a <code>BufferStrategy</code> after it has been disposed will
195 * result in undefined behavior.
196 *
197 * @see java.awt.Window#createBufferStrategy
198 * @see java.awt.Canvas#createBufferStrategy
199 * @see java.awt.Window#getBufferStrategy
200 * @see java.awt.Canvas#getBufferStrategy
201 * @since 1.6
202 */
203 public void dispose() {
204 }
205 }
Save This Page