View Javadoc
1   /*
2    * Copyright (c) 2000, 2011, 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;
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(e);
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 }