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 }