Source for java.awt.BufferCapabilities

   1: /* BufferCapabilities.java -- double-buffering capabilities descriptor
   2:    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.awt;
  40: 
  41: import java.awt.image.BufferStrategy;
  42: 
  43: /**
  44:  * A double-buffering capability descriptor.  This class exposes
  45:  * details about the double-buffering algorithms used by image
  46:  * buffers.
  47:  *
  48:  * BufferCapabilities represents algorithms that involve at least two
  49:  * buffers but it can also specify so-called "multi-buffer" schemes
  50:  * involving more than two buffers.  This class describes the
  51:  * capabilities of the front and back buffers as well as the results
  52:  * of "flipping" -- that is, what happens when an image is transferred
  53:  * from the back buffer to the front buffer.
  54:  *
  55:  * Flipping may or may not be supported or may be supported only in
  56:  * fullscreen mode.  If it is not supported then "blitting" is implied
  57:  * -- that is, the contents of the back buffer are copied using a fast
  58:  * block transfer operation from the back buffer to the front buffer.
  59:  *
  60:  * The front buffer is the one that is displayed.
  61:  *
  62:  * @author Eric Blake (ebb9@email.byu.edu)
  63:  *
  64:  * @see BufferStrategy#getCapabilities()
  65:  * @see GraphicsConfiguration#getBufferCapabilities()
  66:  *
  67:  * @since 1.4
  68:  */
  69: public class BufferCapabilities implements Cloneable
  70: {
  71:   /**
  72:    * A type-safe enumeration of buffer flipping results.
  73:    *
  74:    * @see AttributeValue
  75:    */
  76:   public static final class FlipContents extends AttributeValue
  77:   {
  78:     /**
  79:      * The names of the different flipping results.
  80:      */
  81:     private static final String[] NAMES
  82:       = { "undefined", "background", "prior", "copied" };
  83: 
  84:     /**
  85:      * The contents of the back buffer are undefined after flipping.
  86:      */
  87:     public static final FlipContents UNDEFINED = new FlipContents(0);
  88: 
  89:     /**
  90:      * The back buffer is cleared with the background color after
  91:      * flipping.
  92:      */
  93:     public static final FlipContents BACKGROUND = new FlipContents(1);
  94: 
  95:     /**
  96:      * The back buffer contains the pre-flipping contents of the front
  97:      * buffer after flipping.  In other words a true "flip" has been
  98:      * performed.
  99:      */
 100:     public static final FlipContents PRIOR = new FlipContents(2);
 101: 
 102:     /**
 103:      * The back buffer has the same contents as the front buffer after
 104:      * flipping.
 105:      */
 106:     public static final FlipContents COPIED = new FlipContents(3);
 107: 
 108:     /**
 109:      * Create a new flipping result descriptor.
 110:      *
 111:      * @param value the enumeration value
 112:      */
 113:     private FlipContents(int value)
 114:     {
 115:       super(value, NAMES);
 116:     }
 117:   }
 118: 
 119:   /**
 120:    * Front buffer capabilities descriptor.
 121:    */
 122:   private final ImageCapabilities front;
 123: 
 124:   /**
 125:    * Back buffer capabilities descriptor.
 126:    */
 127:   private final ImageCapabilities back;
 128: 
 129:   /**
 130:    * Describes the results of a "flip" operation.
 131:    */
 132:   private final FlipContents flip;
 133: 
 134:   /**
 135:    * Creates a buffer capabilities object.
 136:    *
 137:    * @param frontCaps front buffer capabilities descriptor
 138:    * @param backCaps back buffer capabilities descriptor
 139:    * @param flip the results of a flip operation or null if
 140:    * flipping is not supported
 141:    *
 142:    * @exception IllegalArgumentException if frontCaps or backCaps is
 143:    * null
 144:    */
 145:   public BufferCapabilities(ImageCapabilities frontCaps,
 146:                 ImageCapabilities backCaps,
 147:                             FlipContents flip)
 148:   {
 149:     if (frontCaps ==  null || backCaps == null)
 150:       throw new IllegalArgumentException();
 151:     this.front = frontCaps;
 152:     this.back = backCaps;
 153:     this.flip = flip;
 154:   }
 155: 
 156:   /**
 157:    * Retrieve the front buffer's image capabilities.
 158:    *
 159:    * @return the front buffer's image capabilities
 160:    */
 161:   public ImageCapabilities getFrontBufferCapabilities()
 162:   {
 163:     return front;
 164:   }
 165: 
 166:   /**
 167:    * Retrieve the back buffer's image capabilities.
 168:    *
 169:    * @return the back buffer's image capabilities
 170:    */
 171:   public ImageCapabilities getBackBufferCapabilities()
 172:   {
 173:     return back;
 174:   }
 175: 
 176:   /**
 177:    * Return whether or not flipping is supported.
 178:    *
 179:    * @return true if flipping is supported, false otherwise
 180:    */
 181:   public boolean isPageFlipping()
 182:   {
 183:     return flip != null;
 184:   }
 185: 
 186:   /**
 187:    * Retrieve the result of a flipping operation.  If this method
 188:    * returns null then flipping is not supported.  This implies that
 189:    * "blitting", a fast block transfer, is used to copy the contents
 190:    * of the back buffer to the front buffer.  Other possible return
 191:    * values are:
 192:    * <ul>
 193:    *   <li><code>FlipContents.UNDEFINED</code> the contents of the
 194:    *   back buffer are undefined after flipping.</li>
 195:    *   <li><code>FlipContents.BACKGROUND</code> the contents of the
 196:    *   back buffer are cleared to the background color after
 197:    *   flipping.</li>
 198:    *   <li><code>FlipContents.PRIOR</code> the back buffer contains
 199:    *   the pre-flipping contents of the front * buffer after
 200:    *   flipping.</li>
 201:    *   <li><code>FlipContents.COPIED</code> the back buffer has the
 202:    *   same contents as the front buffer after flipping.</li>
 203:    * </ul>
 204:    *
 205:    * @return the result of a flipping operation or null if flipping is
 206:    * not supported
 207:    */
 208:   public FlipContents getFlipContents()
 209:   {
 210:     return flip;
 211:   }
 212: 
 213:   /**
 214:    * Returns true if flipping is only supported in fullscreen mode.
 215:    *
 216:    * @return true if flipping is only supported in fullscreen mode,
 217:    * false otherwise
 218:    */
 219:   public boolean isFullScreenRequired()
 220:   {
 221:     return true;
 222:   }
 223: 
 224:   /**
 225:    * Returns true if flipping can involve more than two buffers.  One
 226:    * or more intermediate buffers may be available in addition to the
 227:    * front and back buffers.
 228:    *
 229:    * @return true if there are more than two buffers available for
 230:    * flipping, false otherwise
 231:    */
 232:   public boolean isMultiBufferAvailable()
 233:   {
 234:     return false;
 235:   }
 236: 
 237:   /**
 238:    * Clone this buffering capability descriptor.
 239:    *
 240:    * @return a clone of this buffer capability descriptor
 241:    */
 242:   public Object clone()
 243:   {
 244:     try
 245:       {
 246:         return super.clone();
 247:       }
 248:     catch (CloneNotSupportedException e)
 249:       {
 250:         throw (Error) new InternalError().initCause(e);
 251:       }
 252:   }
 253: }