Home » openjdk-7 » java » awt » image » [javadoc | source]

    1   /*
    2    * Copyright (c) 2000, 2007, 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</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   }

Home » openjdk-7 » java » awt » image » [javadoc | source]