1 /*

     2  * Copyright 2000-2006 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;

    27 

    28 /**

    29  * Capabilities and properties of buffers.

    30  *

    31  * @see java.awt.image.BufferStrategy#getCapabilities()

    32  * @see GraphicsConfiguration#getBufferCapabilities

    33  * @author Michael Martak

    34  * @since 1.4

    35  */

    36 public class BufferCapabilities implements Cloneable {

    37 

    38     private ImageCapabilities frontCaps;

    39     private ImageCapabilities backCaps;

    40     private FlipContents flipContents;

    41 

    42     /**

    43      * Creates a new object for specifying buffering capabilities

    44      * @param frontCaps the capabilities of the front buffer; cannot be

    45      * <code>null</code>

    46      * @param backCaps the capabilities of the back and intermediate buffers;

    47      * cannot be <code>null</code>

    48      * @param flipContents the contents of the back buffer after page-flipping,

    49      * <code>null</code> if page flipping is not used (implies blitting)

    50      * @exception IllegalArgumentException if frontCaps or backCaps are

    51      * <code>null</code>

    52      */

    53     public BufferCapabilities(ImageCapabilities frontCaps,

    54         ImageCapabilities backCaps, FlipContents flipContents) {

    55         if (frontCaps == null || backCaps == null) {

    56             throw new IllegalArgumentException(

    57                 "Image capabilities specified cannot be null");

    58         }

    59         this.frontCaps = frontCaps;

    60         this.backCaps = backCaps;

    61         this.flipContents = flipContents;

    62     }

    63 

    64     /**

    65      * @return the image capabilities of the front (displayed) buffer

    66      */

    67     public ImageCapabilities getFrontBufferCapabilities() {

    68         return frontCaps;

    69     }

    70 

    71     /**

    72      * @return the image capabilities of all back buffers (intermediate buffers

    73      * are considered back buffers)

    74      */

    75     public ImageCapabilities getBackBufferCapabilities() {

    76         return backCaps;

    77     }

    78 

    79     /**

    80      * @return whether or not the buffer strategy uses page flipping; a set of

    81      * buffers that uses page flipping

    82      * can swap the contents internally between the front buffer and one or

    83      * more back buffers by switching the video pointer (or by copying memory

    84      * internally).  A non-flipping set of

    85      * buffers uses blitting to copy the contents from one buffer to

    86      * another; when this is the case, <code>getFlipContents</code> returns

    87      * <code>null</code>

    88      */

    89     public boolean isPageFlipping() {

    90         return (getFlipContents() != null);

    91     }

    92 

    93     /**

    94      * @return the resulting contents of the back buffer after page-flipping.

    95      * This value is <code>null</code> when the <code>isPageFlipping</code>

    96      * returns <code>false</code>, implying blitting.  It can be one of

    97      * <code>FlipContents.UNDEFINED</code>

    98      * (the assumed default), <code>FlipContents.BACKGROUND</code>,

    99      * <code>FlipContents.PRIOR</code>, or

   100      * <code>FlipContents.COPIED</code>.

   101      * @see #isPageFlipping

   102      * @see FlipContents#UNDEFINED

   103      * @see FlipContents#BACKGROUND

   104      * @see FlipContents#PRIOR

   105      * @see FlipContents#COPIED

   106      */

   107     public FlipContents getFlipContents() {

   108         return flipContents;

   109     }

   110 

   111     /**

   112      * @return whether page flipping is only available in full-screen mode.  If this

   113      * is <code>true</code>, full-screen exclusive mode is required for

   114      * page-flipping.

   115      * @see #isPageFlipping

   116      * @see GraphicsDevice#setFullScreenWindow

   117      */

   118     public boolean isFullScreenRequired() {

   119         return false;

   120     }

   121 

   122     /**

   123      * @return whether or not

   124      * page flipping can be performed using more than two buffers (one or more

   125      * intermediate buffers as well as the front and back buffer).

   126      * @see #isPageFlipping

   127      */

   128     public boolean isMultiBufferAvailable() {

   129         return false;

   130     }

   131 

   132     /**

   133      * @return a copy of this BufferCapabilities object.

   134      */

   135     public Object clone() {

   136         try {

   137             return super.clone();

   138         } catch (CloneNotSupportedException e) {

   139             // Since we implement Cloneable, this should never happen

   140             throw new InternalError();

   141         }

   142     }

   143 

   144     // Inner class FlipContents

   145     /**

   146      * A type-safe enumeration of the possible back buffer contents after

   147      * page-flipping

   148      * @since 1.4

   149      */

   150     public static final class FlipContents extends AttributeValue {

   151 

   152         private static int I_UNDEFINED = 0;

   153         private static int I_BACKGROUND = 1;

   154         private static int I_PRIOR = 2;

   155         private static int I_COPIED = 3;

   156 

   157         private static final String NAMES[] =

   158             { "undefined", "background", "prior", "copied" };

   159 

   160         /**

   161          * When flip contents are <code>UNDEFINED</code>, the

   162          * contents of the back buffer are undefined after flipping.

   163          * @see #isPageFlipping

   164          * @see #getFlipContents

   165          * @see #BACKGROUND

   166          * @see #PRIOR

   167          * @see #COPIED

   168          */

   169         public static final FlipContents UNDEFINED =

   170             new FlipContents(I_UNDEFINED);

   171 

   172         /**

   173          * When flip contents are <code>BACKGROUND</code>, the

   174          * contents of the back buffer are cleared with the background color after

   175          * flipping.

   176          * @see #isPageFlipping

   177          * @see #getFlipContents

   178          * @see #UNDEFINED

   179          * @see #PRIOR

   180          * @see #COPIED

   181          */

   182         public static final FlipContents BACKGROUND =

   183             new FlipContents(I_BACKGROUND);

   184 

   185         /**

   186          * When flip contents are <code>PRIOR</code>, the

   187          * contents of the back buffer are the prior contents of the front buffer

   188          * (a true page flip).

   189          * @see #isPageFlipping

   190          * @see #getFlipContents

   191          * @see #UNDEFINED

   192          * @see #BACKGROUND

   193          * @see #COPIED

   194          */

   195         public static final FlipContents PRIOR =

   196             new FlipContents(I_PRIOR);

   197 

   198         /**

   199          * When flip contents are <code>COPIED</code>, the

   200          * contents of the back buffer are copied to the front buffer when

   201          * flipping.

   202          * @see #isPageFlipping

   203          * @see #getFlipContents

   204          * @see #UNDEFINED

   205          * @see #BACKGROUND

   206          * @see #PRIOR

   207          */

   208         public static final FlipContents COPIED =

   209             new FlipContents(I_COPIED);

   210 

   211         private FlipContents(int type) {

   212             super(type, NAMES);

   213         }

   214 

   215     } // Inner class FlipContents

   216 

   217 }