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: }