1 /*
   2  * Copyright (c) 2000, 2020, 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} class represents the mechanism with which
  34  * to organize complex memory on a particular {@code Canvas} or
  35  * {@code Window}.  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} used when creating the
  39  * {@code Canvas} or {@code Window}.
  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      * Constructor for subclasses to call.
 139      */
 140     protected BufferStrategy() {}
 141 
 142     /**
 143      * Returns the {@code BufferCapabilities} for this
 144      * {@code BufferStrategy}.
 145      *
 146      * @return the buffering capabilities of this strategy
 147      */
 148     public abstract BufferCapabilities getCapabilities();
 149 
 150     /**
 151      * Creates a graphics context for the drawing buffer.  This method may not
 152      * be synchronized for performance reasons; use of this method by multiple
 153      * threads should be handled at the application level.  Disposal of the
 154      * graphics object obtained must be handled by the application.
 155      *
 156      * @return a graphics context for the drawing buffer
 157      */
 158     public abstract Graphics getDrawGraphics();
 159 
 160     /**
 161      * Returns whether the drawing buffer was lost since the last call to
 162      * {@code getDrawGraphics}.  Since the buffers in a buffer strategy
 163      * are usually type {@code VolatileImage}, they may become lost.
 164      * For a discussion on lost buffers, see {@code VolatileImage}.
 165      *
 166      * @return Whether or not the drawing buffer was lost since the last call
 167      * to {@code getDrawGraphics}.
 168      * @see java.awt.image.VolatileImage
 169      */
 170     public abstract boolean contentsLost();
 171 
 172     /**
 173      * Returns whether the drawing buffer was recently restored from a lost
 174      * state and reinitialized to the default background color (white).
 175      * Since the buffers in a buffer strategy are usually type
 176      * {@code VolatileImage}, they may become lost.  If a surface has
 177      * been recently restored from a lost state since the last call to
 178      * {@code getDrawGraphics}, it may require repainting.
 179      * For a discussion on lost buffers, see {@code VolatileImage}.
 180      *
 181      * @return Whether or not the drawing buffer was restored since the last
 182      *         call to {@code getDrawGraphics}.
 183      * @see java.awt.image.VolatileImage
 184      */
 185     public abstract boolean contentsRestored();
 186 
 187     /**
 188      * Makes the next available buffer visible by either copying the memory
 189      * (blitting) or changing the display pointer (flipping).
 190      */
 191     public abstract void show();
 192 
 193     /**
 194      * Releases system resources currently consumed by this
 195      * {@code BufferStrategy} and
 196      * removes it from the associated Component.  After invoking this
 197      * method, {@code getBufferStrategy} will return null.  Trying
 198      * to use a {@code BufferStrategy} after it has been disposed will
 199      * result in undefined behavior.
 200      *
 201      * @see java.awt.Window#createBufferStrategy
 202      * @see java.awt.Canvas#createBufferStrategy
 203      * @see java.awt.Window#getBufferStrategy
 204      * @see java.awt.Canvas#getBufferStrategy
 205      * @since 1.6
 206      */
 207     public void dispose() {
 208     }
 209 }