KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > image > BufferStrategy


1 /*
2  * @(#)BufferStrategy.java 1.6 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.awt.image;
9
10 import java.awt.BufferCapabilities JavaDoc;
11 import java.awt.Graphics JavaDoc;
12 import java.awt.Image JavaDoc;
13
14 /**
15  * The <code>BufferStrategy</code> class represents the mechanism with which
16  * to organize complex memory on a particular <code>Canvas</code> or
17  * <code>Window</code>. Hardware and software limitations determine whether and
18  * how a particular buffer strategy can be implemented. These limitations
19  * are detectible through the capabilities of the
20  * <code>GraphicsConfiguration</code> used when creating the
21  * <code>Canvas</code> or <code>Window</code>.
22  * <p>
23  * It is worth noting that the terms <i>buffer</i> and <i>surface</i> are meant
24  * to be synonymous: an area of contiguous memory, either in video device
25  * memory or in system memory.
26  * <p>
27  * There are several types of complex buffer strategies;
28  * sequential ring buffering, blit buffering, and stereo buffering are
29  * common types. Sequential ring buffering (i.e., double or triple
30  * buffering) is the most common; an application draws to a single <i>back
31  * buffer</i> and then moves the contents to the front (display) in a single
32  * step, either by copying the data or moving the video pointer.
33  * Moving the video pointer exchanges the buffers so that the first buffer
34  * drawn becomes the <i>front buffer</i>, or what is currently displayed on the
35  * device; this is called <i>page flipping</i>.
36  * <p>
37  * Alternatively, the contents of the back buffer can be copied, or
38  * <i>blitted</i> forward in a chain instead of moving the video pointer.
39  * <p>
40  * <pre>
41  * Double buffering:
42  *
43  * *********** ***********
44  * * * ------> * *
45  * [To display] <---- * Front B * Show * Back B. * <---- Rendering
46  * * * <------ * *
47  * *********** ***********
48  *
49  * Triple buffering:
50  *
51  * [To *********** *********** ***********
52  * display] * * --------+---------+------> * *
53  * <---- * Front B * Show * Mid. B. * * Back B. * <---- Rendering
54  * * * <------ * * <----- * *
55  * *********** *********** ***********
56  *
57  * </pre>
58  * <p>
59  * Stereo buffering is for hardware that supports rendering separate images for
60  * a left and right eye. It is similar to sequential ring buffering, but
61  * there are two buffer chains, one for each eye. Both buffer chains flip
62  * simultaneously:
63  *
64  * <pre>
65  * Stereo buffering:
66  *
67  * *********** ***********
68  * * * ------> * *
69  * [To left eye] <---- * Front B * * Back B. * <---- Rendering
70  * * * <------ * *
71  * *********** ***********
72  * Show
73  * *********** ***********
74  * * * ------> * *
75  * [To right eye] <--- * Front B * * Back B. * <---- Rendering
76  * * * <------ * *
77  * *********** ***********
78  * </pre>
79  * <p>
80  * Here is an example of how buffer strategies can be created and used:
81  * <pre><code>
82  *
83  * // Check the capabilities of the GraphicsConfiguration
84  * ...
85  *
86  * // Create our component
87  * Window w = new Window(gc);
88  *
89  * // Show our window
90  * w.setVisible(true);
91  *
92  * // Create a general double-buffering strategy
93  * w.createBufferStrategy(2);
94  * BufferStrategy strategy = w.getBufferStrategy();
95  *
96  * // Render loop
97  * while (!done) {
98  * Graphics g = strategy.getDrawGraphics();
99  * // Draw to graphics
100  * ...
101  * strategy.show();
102  * }
103  *
104  * // Dispose the window
105  * w.setVisible(false);
106  * w.dispose();
107  * </code></pre>
108  *
109  * @see java.awt.Component
110  * @see java.awt.GraphicsConfiguration
111  * @author Michael Martak
112  * @since 1.4
113  */
114 public abstract class BufferStrategy {
115     
116     /**
117      * @return the buffering capabilities of this strategy
118      */
119     public abstract BufferCapabilities JavaDoc getCapabilities();
120
121     /**
122      * @return the graphics on the drawing buffer. This method may not
123      * be synchronized for performance reasons; use of this method by multiple
124      * threads should be handled at the application level. Disposal of the
125      * graphics object obtained must be handled by the application.
126      */
127     public abstract Graphics JavaDoc getDrawGraphics();
128
129     /**
130      * Returns whether the drawing buffer was lost since the last call to
131      * <code>getDrawGraphics</code>. Since the buffers in a buffer strategy
132      * are usually type <code>VolatileImage</code>, they may become lost.
133      * For a discussion on lost buffers, see <code>VolatileImage</code>.
134      * @see java.awt.image.VolatileImage
135      */
136     public abstract boolean contentsLost();
137
138     /**
139      * Returns whether the drawing buffer was recently restored from a lost
140      * state and reinitialized to the default background color (white).
141      * Since the buffers in a buffer strategy are usually type
142      * <code>VolatileImage</code>, they may become lost. If a surface has
143      * been recently restored from a lost state since the last call to
144      * <code>getDrawGraphics</code>, it may require repainting.
145      * For a discussion on lost buffers, see <code>VolatileImage</code>.
146      * @see java.awt.image.VolatileImage
147      */
148     public abstract boolean contentsRestored();
149
150     /**
151      * Makes the next available buffer visible by either copying the memory
152      * (blitting) or changing the display pointer (flipping).
153      */
154     public abstract void show();
155 }
156
157
Popular Tags