1 /*
2 * Copyright (c) 1997, 2009, 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
27 package java.awt;
28
29 import java.awt.image.ColorModel;
30
31 import sun.awt.AWTAccessor;
32 import sun.awt.AppContext;
33 import sun.awt.SunToolkit;
34
35 /**
36 * The <code>GraphicsDevice</code> class describes the graphics devices
37 * that might be available in a particular graphics environment. These
38 * include screen and printer devices. Note that there can be many screens
39 * and many printers in an instance of {@link GraphicsEnvironment}. Each
40 * graphics device has one or more {@link GraphicsConfiguration} objects
41 * associated with it. These objects specify the different configurations
42 * in which the <code>GraphicsDevice</code> can be used.
43 * <p>
44 * In a multi-screen environment, the <code>GraphicsConfiguration</code>
45 * objects can be used to render components on multiple screens. The
46 * following code sample demonstrates how to create a <code>JFrame</code>
47 * object for each <code>GraphicsConfiguration</code> on each screen
48 * device in the <code>GraphicsEnvironment</code>:
49 * <pre>
50 * GraphicsEnvironment ge = GraphicsEnvironment.
51 * getLocalGraphicsEnvironment();
52 * GraphicsDevice[] gs = ge.getScreenDevices();
53 * for (int j = 0; j < gs.length; j++) {
54 * GraphicsDevice gd = gs[j];
55 * GraphicsConfiguration[] gc =
56 * gd.getConfigurations();
57 * for (int i=0; i < gc.length; i++) {
58 * JFrame f = new
59 * JFrame(gs[j].getDefaultConfiguration());
60 * Canvas c = new Canvas(gc[i]);
61 * Rectangle gcBounds = gc[i].getBounds();
62 * int xoffs = gcBounds.x;
63 * int yoffs = gcBounds.y;
64 * f.getContentPane().add(c);
65 * f.setLocation((i*50)+xoffs, (i*60)+yoffs);
66 * f.show();
67 * }
68 * }
69 * </pre>
70 * <p>
71 * For more information on full-screen exclusive mode API, see the
72 * <a href="http://java.sun.com/docs/books/tutorial/extra/fullscreen/index.html">
73 * Full-Screen Exclusive Mode API Tutorial</a>.
74 *
75 * @see GraphicsEnvironment
76 * @see GraphicsConfiguration
77 */
78 public abstract class GraphicsDevice {
79
80 private Window fullScreenWindow;
81 private AppContext fullScreenAppContext; // tracks which AppContext
82 // created the FS window
83 // this lock is used for making synchronous changes to the AppContext's
84 // current full screen window
85 private final Object fsAppContextLock = new Object();
86
87 private Rectangle windowedModeBounds;
88
89 /**
90 * This is an abstract class that cannot be instantiated directly.
91 * Instances must be obtained from a suitable factory or query method.
92 * @see GraphicsEnvironment#getScreenDevices
93 * @see GraphicsEnvironment#getDefaultScreenDevice
94 * @see GraphicsConfiguration#getDevice
95 */
96 protected GraphicsDevice() {
97 }
98
99 /**
100 * Device is a raster screen.
101 */
102 public final static int TYPE_RASTER_SCREEN = 0;
103
104 /**
105 * Device is a printer.
106 */
107 public final static int TYPE_PRINTER = 1;
108
109 /**
110 * Device is an image buffer. This buffer can reside in device
111 * or system memory but it is not physically viewable by the user.
112 */
113 public final static int TYPE_IMAGE_BUFFER = 2;
114
115 /** Kinds of translucency supported by the underlying system.
116 * @see #isTranslucencySupported
117 */
118 /*public */static enum WindowTranslucency {
119 /**
120 * Represents support in the underlying system for windows each pixel
121 * of which is guaranteed to be either completely opaque, with
122 * an alpha value of 1.0, or completely transparent, with an alpha
123 * value of 0.0.
124 */
125 PERPIXEL_TRANSPARENT,
126 /**
127 * Represents support in the underlying system for windows all of
128 * the pixels of which have the same alpha value between or including
129 * 0.0 and 1.0.
130 */
131 TRANSLUCENT,
132 /**
133 * Represents support in the underlying system for windows that
134 * contain or might contain pixels with arbitrary alpha values
135 * between and including 0.0 and 1.0.
136 */
137 PERPIXEL_TRANSLUCENT;
138 }
139
140 /**
141 * Returns the type of this <code>GraphicsDevice</code>.
142 * @return the type of this <code>GraphicsDevice</code>, which can
143 * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.
144 * @see #TYPE_RASTER_SCREEN
145 * @see #TYPE_PRINTER
146 * @see #TYPE_IMAGE_BUFFER
147 */
148 public abstract int getType();
149
150 /**
151 * Returns the identification string associated with this
152 * <code>GraphicsDevice</code>.
153 * <p>
154 * A particular program might use more than one
155 * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.
156 * This method returns a <code>String</code> identifying a
157 * particular <code>GraphicsDevice</code> in the local
158 * <code>GraphicsEnvironment</code>. Although there is
159 * no public method to set this <code>String</code>, a programmer can
160 * use the <code>String</code> for debugging purposes. Vendors of
161 * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can
162 * format the return value of the <code>String</code>. To determine
163 * how to interpret the value of the <code>String</code>, contact the
164 * vendor of your Java Runtime. To find out who the vendor is, from
165 * your program, call the
166 * {@link System#getProperty(String) getProperty} method of the
167 * System class with "java.vendor".
168 * @return a <code>String</code> that is the identification
169 * of this <code>GraphicsDevice</code>.
170 */
171 public abstract String getIDstring();
172
173 /**
174 * Returns all of the <code>GraphicsConfiguration</code>
175 * objects associated with this <code>GraphicsDevice</code>.
176 * @return an array of <code>GraphicsConfiguration</code>
177 * objects that are associated with this
178 * <code>GraphicsDevice</code>.
179 */
180 public abstract GraphicsConfiguration[] getConfigurations();
181
182 /**
183 * Returns the default <code>GraphicsConfiguration</code>
184 * associated with this <code>GraphicsDevice</code>.
185 * @return the default <code>GraphicsConfiguration</code>
186 * of this <code>GraphicsDevice</code>.
187 */
188 public abstract GraphicsConfiguration getDefaultConfiguration();
189
190 /**
191 * Returns the "best" configuration possible that passes the
192 * criteria defined in the {@link GraphicsConfigTemplate}.
193 * @param gct the <code>GraphicsConfigTemplate</code> object
194 * used to obtain a valid <code>GraphicsConfiguration</code>
195 * @return a <code>GraphicsConfiguration</code> that passes
196 * the criteria defined in the specified
197 * <code>GraphicsConfigTemplate</code>.
198 * @see GraphicsConfigTemplate
199 */
200 public GraphicsConfiguration
201 getBestConfiguration(GraphicsConfigTemplate gct) {
202 GraphicsConfiguration[] configs = getConfigurations();
203 return gct.getBestConfiguration(configs);
204 }
205
206 /**
207 * Returns <code>true</code> if this <code>GraphicsDevice</code>
208 * supports full-screen exclusive mode.
209 * If a SecurityManager is installed, its
210 * <code>checkPermission</code> method will be called
211 * with <code>AWTPermission("fullScreenExclusive")</code>.
212 * <code>isFullScreenSupported</code> returns true only if
213 * that permission is granted.
214 * @return whether full-screen exclusive mode is available for
215 * this graphics device
216 * @see java.awt.AWTPermission
217 * @since 1.4
218 */
219 public boolean isFullScreenSupported() {
220 return false;
221 }
222
223 /**
224 * Enter full-screen mode, or return to windowed mode. The entered
225 * full-screen mode may be either exclusive or simulated. Exclusive
226 * mode is only available if <code>isFullScreenSupported</code>
227 * returns <code>true</code>.
228 * <p>
229 * Exclusive mode implies:
230 * <ul>
231 * <li>Windows cannot overlap the full-screen window. All other application
232 * windows will always appear beneath the full-screen window in the Z-order.
233 * <li>There can be only one full-screen window on a device at any time,
234 * so calling this method while there is an existing full-screen Window
235 * will cause the existing full-screen window to
236 * return to windowed mode.
237 * <li>Input method windows are disabled. It is advisable to call
238 * <code>Component.enableInputMethods(false)</code> to make a component
239 * a non-client of the input method framework.
240 * </ul>
241 * <p>
242 * Simulated full-screen mode resizes
243 * the window to the size of the screen and positions it at (0,0).
244 * <p>
245 * When entering full-screen mode, if the window to be used as a
246 * full-screen window is not visible, this method will make it visible.
247 * It will remain visible when returning to windowed mode.
248 * <p>
249 * When returning to windowed mode from an exclusive full-screen window, any
250 * display changes made by calling <code>setDisplayMode</code> are
251 * automatically restored to their original state.
252 *
253 * @param w a window to use as the full-screen window; {@code null}
254 * if returning to windowed mode. Some platforms expect the
255 * fullscreen window to be a top-level component (i.e., a {@code Frame});
256 * therefore it is preferable to use a {@code Frame} here rather than a
257 * {@code Window}.
258 * @see #isFullScreenSupported
259 * @see #getFullScreenWindow
260 * @see #setDisplayMode
261 * @see Component#enableInputMethods
262 * @see Component#setVisible
263 * @since 1.4
264 */
265 public void setFullScreenWindow(Window w) {
266 if (w != null) {
267 //XXX: The actions should be documented in some non-update release.
268 /*
269 if (w.getShape() != null) {
270 w.setShape(w, null);
271 }
272 if (!w.isOpaque()) {
273 w.setOpaque(false);
274 }
275 if (w.getOpacity() < 1.0f) {
276 w.setOpacity(1.0f);
277 }
278 */
279 }
280
281 if (fullScreenWindow != null && windowedModeBounds != null) {
282 // if the window went into fs mode before it was realized it may
283 // have (0,0) dimensions
284 if (windowedModeBounds.width == 0) windowedModeBounds.width = 1;
285 if (windowedModeBounds.height == 0) windowedModeBounds.height = 1;
286 fullScreenWindow.setBounds(windowedModeBounds);
287 }
288 // Set the full screen window
289 synchronized (fsAppContextLock) {
290 // Associate fullscreen window with current AppContext
291 if (w == null) {
292 fullScreenAppContext = null;
293 } else {
294 fullScreenAppContext = AppContext.getAppContext();
295 }
296 fullScreenWindow = w;
297 }
298 if (fullScreenWindow != null) {
299 windowedModeBounds = fullScreenWindow.getBounds();
300 // Note that we use the graphics configuration of the device,
301 // not the window's, because we're setting the fs window for
302 // this device.
303 Rectangle screenBounds = getDefaultConfiguration().getBounds();
304 fullScreenWindow.setBounds(screenBounds.x, screenBounds.y,
305 screenBounds.width, screenBounds.height);
306 fullScreenWindow.setVisible(true);
307 fullScreenWindow.toFront();
308 }
309 }
310
311 /**
312 * Returns the <code>Window</code> object representing the
313 * full-screen window if the device is in full-screen mode.
314 *
315 * @return the full-screen window, or <code>null</code> if the device is
316 * not in full-screen mode.
317 * @see #setFullScreenWindow(Window)
318 * @since 1.4
319 */
320 public Window getFullScreenWindow() {
321 Window returnWindow = null;
322 synchronized (fsAppContextLock) {
323 // Only return a handle to the current fs window if we are in the
324 // same AppContext that set the fs window
325 if (fullScreenAppContext == AppContext.getAppContext()) {
326 returnWindow = fullScreenWindow;
327 }
328 }
329 return returnWindow;
330 }
331
332 /**
333 * Returns <code>true</code> if this <code>GraphicsDevice</code>
334 * supports low-level display changes.
335 * On some platforms low-level display changes may only be allowed in
336 * full-screen exclusive mode (i.e., if {@link #isFullScreenSupported()}
337 * returns {@code true} and the application has already entered
338 * full-screen mode using {@link #setFullScreenWindow}).
339 * @return whether low-level display changes are supported for this
340 * graphics device.
341 * @see #isFullScreenSupported
342 * @see #setDisplayMode
343 * @see #setFullScreenWindow
344 * @since 1.4
345 */
346 public boolean isDisplayChangeSupported() {
347 return false;
348 }
349
350 /**
351 * Sets the display mode of this graphics device. This is only allowed
352 * if {@link #isDisplayChangeSupported()} returns {@code true} and may
353 * require first entering full-screen exclusive mode using
354 * {@link #setFullScreenWindow} providing that full-screen exclusive mode is
355 * supported (i.e., {@link #isFullScreenSupported()} returns
356 * {@code true}).
357 * <p>
358 *
359 * The display mode must be one of the display modes returned by
360 * {@link #getDisplayModes()}, with one exception: passing a display mode
361 * with {@link DisplayMode#REFRESH_RATE_UNKNOWN} refresh rate will result in
362 * selecting a display mode from the list of available display modes with
363 * matching width, height and bit depth.
364 * However, passing a display mode with {@link DisplayMode#BIT_DEPTH_MULTI}
365 * for bit depth is only allowed if such mode exists in the list returned by
366 * {@link #getDisplayModes()}.
367 * <p>
368 * Example code:
369 * <pre><code>
370 * Frame frame;
371 * DisplayMode newDisplayMode;
372 * GraphicsDevice gd;
373 * // create a Frame, select desired DisplayMode from the list of modes
374 * // returned by gd.getDisplayModes() ...
375 *
376 * if (gd.isFullScreenSupported()) {
377 * gd.setFullScreenWindow(frame);
378 * } else {
379 * // proceed in non-full-screen mode
380 * frame.setSize(...);
381 * frame.setLocation(...);
382 * frame.setVisible(true);
383 * }
384 *
385 * if (gd.isDisplayChangeSupported()) {
386 * gd.setDisplayMode(newDisplayMode);
387 * }
388 * </code></pre>
389 *
390 * @param dm The new display mode of this graphics device.
391 * @exception IllegalArgumentException if the <code>DisplayMode</code>
392 * supplied is <code>null</code>, or is not available in the array returned
393 * by <code>getDisplayModes</code>
394 * @exception UnsupportedOperationException if
395 * <code>isDisplayChangeSupported</code> returns <code>false</code>
396 * @see #getDisplayMode
397 * @see #getDisplayModes
398 * @see #isDisplayChangeSupported
399 * @since 1.4
400 */
401 public void setDisplayMode(DisplayMode dm) {
402 throw new UnsupportedOperationException("Cannot change display mode");
403 }
404
405 /**
406 * Returns the current display mode of this
407 * <code>GraphicsDevice</code>.
408 * The returned display mode is allowed to have a refresh rate
409 * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
410 * Likewise, the returned display mode is allowed to have a bit depth
411 * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
412 * bit depths are supported.
413 * @return the current display mode of this graphics device.
414 * @see #setDisplayMode(DisplayMode)
415 * @since 1.4
416 */
417 public DisplayMode getDisplayMode() {
418 GraphicsConfiguration gc = getDefaultConfiguration();
419 Rectangle r = gc.getBounds();
420 ColorModel cm = gc.getColorModel();
421 return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);
422 }
423
424 /**
425 * Returns all display modes available for this
426 * <code>GraphicsDevice</code>.
427 * The returned display modes are allowed to have a refresh rate
428 * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
429 * Likewise, the returned display modes are allowed to have a bit depth
430 * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
431 * bit depths are supported.
432 * @return all of the display modes available for this graphics device.
433 * @since 1.4
434 */
435 public DisplayMode[] getDisplayModes() {
436 return new DisplayMode[] { getDisplayMode() };
437 }
438
439 /**
440 * This method returns the number of bytes available in
441 * accelerated memory on this device.
442 * Some images are created or cached
443 * in accelerated memory on a first-come,
444 * first-served basis. On some operating systems,
445 * this memory is a finite resource. Calling this method
446 * and scheduling the creation and flushing of images carefully may
447 * enable applications to make the most efficient use of
448 * that finite resource.
449 * <br>
450 * Note that the number returned is a snapshot of how much
451 * memory is available; some images may still have problems
452 * being allocated into that memory. For example, depending
453 * on operating system, driver, memory configuration, and
454 * thread situations, the full extent of the size reported
455 * may not be available for a given image. There are further
456 * inquiry methods on the {@link ImageCapabilities} object
457 * associated with a VolatileImage that can be used to determine
458 * whether a particular VolatileImage has been created in accelerated
459 * memory.
460 * @return number of bytes available in accelerated memory.
461 * A negative return value indicates that the amount of accelerated memory
462 * on this GraphicsDevice is indeterminate.
463 * @see java.awt.image.VolatileImage#flush
464 * @see ImageCapabilities#isAccelerated
465 * @since 1.4
466 */
467 public int getAvailableAcceleratedMemory() {
468 return -1;
469 }
470
471 /**
472 * Returns whether the given level of translucency is supported
473 * this graphics device.
474 *
475 * @param translucencyKind a kind of translucency support
476 * @return whether the given translucency kind is supported
477 */
478 /*public */boolean isWindowTranslucencySupported(WindowTranslucency translucencyKind) {
479 switch (translucencyKind) {
480 case PERPIXEL_TRANSPARENT:
481 return isWindowShapingSupported();
482 case TRANSLUCENT:
483 return isWindowOpacitySupported();
484 case PERPIXEL_TRANSLUCENT:
485 return isWindowPerpixelTranslucencySupported();
486 }
487 return false;
488 }
489
490 /**
491 * Returns whether the windowing system supports changing the shape
492 * of top-level windows.
493 * Note that this method may sometimes return true, but the native
494 * windowing system may still not support the concept of
495 * shaping (due to the bugs in the windowing system).
496 */
497 static boolean isWindowShapingSupported() {
498 Toolkit curToolkit = Toolkit.getDefaultToolkit();
499 if (!(curToolkit instanceof SunToolkit)) {
500 return false;
501 }
502 return ((SunToolkit)curToolkit).isWindowShapingSupported();
503 }
504
505 /**
506 * Returns whether the windowing system supports changing the opacity
507 * value of top-level windows.
508 * Note that this method may sometimes return true, but the native
509 * windowing system may still not support the concept of
510 * translucency (due to the bugs in the windowing system).
511 */
512 static boolean isWindowOpacitySupported() {
513 Toolkit curToolkit = Toolkit.getDefaultToolkit();
514 if (!(curToolkit instanceof SunToolkit)) {
515 return false;
516 }
517 return ((SunToolkit)curToolkit).isWindowOpacitySupported();
518 }
519
520 boolean isWindowPerpixelTranslucencySupported() {
521 /*
522 * Per-pixel alpha is supported if all the conditions are TRUE:
523 * 1. The toolkit is a sort of SunToolkit
524 * 2. The toolkit supports translucency in general
525 * (isWindowTranslucencySupported())
526 * 3. There's at least one translucency-capable
527 * GraphicsConfiguration
528 */
529 Toolkit curToolkit = Toolkit.getDefaultToolkit();
530 if (!(curToolkit instanceof SunToolkit)) {
531 return false;
532 }
533 if (!((SunToolkit)curToolkit).isWindowTranslucencySupported()) {
534 return false;
535 }
536
537 // TODO: cache translucency capable GC
538 return getTranslucencyCapableGC() != null;
539 }
540
541 GraphicsConfiguration getTranslucencyCapableGC() {
542 // If the default GC supports translucency return true.
543 // It is important to optimize the verification this way,
544 // see CR 6661196 for more details.
545 GraphicsConfiguration defaultGC = getDefaultConfiguration();
546 if (defaultGC.isTranslucencyCapable()) {
547 return defaultGC;
548 }
549
550 // ... otherwise iterate through all the GCs.
551 GraphicsConfiguration[] configs = getConfigurations();
552 for (int j = 0; j < configs.length; j++) {
553 if (configs[j].isTranslucencyCapable()) {
554 return configs[j];
555 }
556 }
557
558 return null;
559 }
560 }