001 /*
002 * Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.image;
027
028 import java.awt.BufferCapabilities;
029 import java.awt.Graphics;
030 import java.awt.Image;
031
032 /**
033 * The <code>BufferStrategy</code> class represents the mechanism with which
034 * to organize complex memory on a particular <code>Canvas</code> or
035 * <code>Window</code>. Hardware and software limitations determine whether and
036 * how a particular buffer strategy can be implemented. These limitations
037 * are detectible through the capabilities of the
038 * <code>GraphicsConfiguration</code> used when creating the
039 * <code>Canvas</code> or <code>Window</code>.
040 * <p>
041 * It is worth noting that the terms <i>buffer</i> and <i>surface</i> are meant
042 * to be synonymous: an area of contiguous memory, either in video device
043 * memory or in system memory.
044 * <p>
045 * There are several types of complex buffer strategies, including
046 * sequential ring buffering and blit buffering.
047 * Sequential ring buffering (i.e., double or triple
048 * buffering) is the most common; an application draws to a single <i>back
049 * buffer</i> and then moves the contents to the front (display) in a single
050 * step, either by copying the data or moving the video pointer.
051 * Moving the video pointer exchanges the buffers so that the first buffer
052 * drawn becomes the <i>front buffer</i>, or what is currently displayed on the
053 * device; this is called <i>page flipping</i>.
054 * <p>
055 * Alternatively, the contents of the back buffer can be copied, or
056 * <i>blitted</i> forward in a chain instead of moving the video pointer.
057 * <p>
058 * <pre>
059 * Double buffering:
060 *
061 * *********** ***********
062 * * * ------> * *
063 * [To display] <---- * Front B * Show * Back B. * <---- Rendering
064 * * * <------ * *
065 * *********** ***********
066 *
067 * Triple buffering:
068 *
069 * [To *********** *********** ***********
070 * display] * * --------+---------+------> * *
071 * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering
072 * * * <------ * * <----- * *
073 * *********** *********** ***********
074 *
075 * </pre>
076 * <p>
077 * Here is an example of how buffer strategies can be created and used:
078 * <pre><code>
079 *
080 * // Check the capabilities of the GraphicsConfiguration
081 * ...
082 *
083 * // Create our component
084 * Window w = new Window(gc);
085 *
086 * // Show our window
087 * w.setVisible(true);
088 *
089 * // Create a general double-buffering strategy
090 * w.createBufferStrategy(2);
091 * BufferStrategy strategy = w.getBufferStrategy();
092 *
093 * // Main loop
094 * while (!done) {
095 * // Prepare for rendering the next frame
096 * // ...
097 *
098 * // Render single frame
099 * 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 }
|