1 /*
2 * Copyright (c) 2000, 2018, 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}
46 * @param backCaps the capabilities of the back and intermediate buffers;
47 * cannot be {@code null}
48 * @param flipContents the contents of the back buffer after page-flipping,
49 * {@code null} if page flipping is not used (implies blitting)
50 * @exception IllegalArgumentException if frontCaps or backCaps are
51 * {@code null}
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} returns
87 * {@code null}
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} when the {@code isPageFlipping}
96 * returns {@code false}, implying blitting. It can be one of
97 * {@code FlipContents.UNDEFINED}
98 * (the assumed default), {@code FlipContents.BACKGROUND},
99 * {@code FlipContents.PRIOR}, or
100 * {@code FlipContents.COPIED}.
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}, 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}, 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}, 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}, 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}, 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 }