/* * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; import java.awt.image.ColorModel; import sun.awt.AppContext; import sun.awt.SunToolkit; /** * The {@code GraphicsDevice} class describes the graphics devices * that might be available in a particular graphics environment. These * include screen and printer devices. Note that there can be many screens * and many printers in an instance of {@link GraphicsEnvironment}. Each * graphics device has one or more {@link GraphicsConfiguration} objects * associated with it. These objects specify the different configurations * in which the {@code GraphicsDevice} can be used. *
* In a multi-screen environment, the {@code GraphicsConfiguration} * objects can be used to render components on multiple screens. The * following code sample demonstrates how to create a {@code JFrame} * object for each {@code GraphicsConfiguration} on each screen * device in the {@code GraphicsEnvironment}: *
{@code * GraphicsEnvironment ge = GraphicsEnvironment. * getLocalGraphicsEnvironment(); * GraphicsDevice[] gs = ge.getScreenDevices(); * for (int j = 0; j < gs.length; j++) { * GraphicsDevice gd = gs[j]; * GraphicsConfiguration[] gc = * gd.getConfigurations(); * for (int i=0; i < gc.length; i++) { * JFrame f = new * JFrame(gs[j].getDefaultConfiguration()); * Canvas c = new Canvas(gc[i]); * Rectangle gcBounds = gc[i].getBounds(); * int xoffs = gcBounds.x; * int yoffs = gcBounds.y; * f.getContentPane().add(c); * f.setLocation((i*50)+xoffs, (i*60)+yoffs); * f.show(); * } * } * }*
* For more information on full-screen exclusive mode API, see the * * Full-Screen Exclusive Mode API Tutorial. * * @see GraphicsEnvironment * @see GraphicsConfiguration */ public abstract class GraphicsDevice { private Window fullScreenWindow; private AppContext fullScreenAppContext; // tracks which AppContext // created the FS window // this lock is used for making synchronous changes to the AppContext's // current full screen window private final Object fsAppContextLock = new Object(); private Rectangle windowedModeBounds; /** * This is an abstract class that cannot be instantiated directly. * Instances must be obtained from a suitable factory or query method. * @see GraphicsEnvironment#getScreenDevices * @see GraphicsEnvironment#getDefaultScreenDevice * @see GraphicsConfiguration#getDevice */ protected GraphicsDevice() { } /** * Device is a raster screen. */ public static final int TYPE_RASTER_SCREEN = 0; /** * Device is a printer. */ public static final int TYPE_PRINTER = 1; /** * Device is an image buffer. This buffer can reside in device * or system memory but it is not physically viewable by the user. */ public static final int TYPE_IMAGE_BUFFER = 2; /** * Kinds of translucency supported by the underlying system. * * @see #isWindowTranslucencySupported * * @since 1.7 */ public static enum WindowTranslucency { /** * Represents support in the underlying system for windows each pixel * of which is guaranteed to be either completely opaque, with * an alpha value of 1.0, or completely transparent, with an alpha * value of 0.0. */ PERPIXEL_TRANSPARENT, /** * Represents support in the underlying system for windows all of * the pixels of which have the same alpha value between or including * 0.0 and 1.0. */ TRANSLUCENT, /** * Represents support in the underlying system for windows that * contain or might contain pixels with arbitrary alpha values * between and including 0.0 and 1.0. */ PERPIXEL_TRANSLUCENT; } /** * Returns the type of this {@code GraphicsDevice}. * @return the type of this {@code GraphicsDevice}, which can * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER. * @see #TYPE_RASTER_SCREEN * @see #TYPE_PRINTER * @see #TYPE_IMAGE_BUFFER */ public abstract int getType(); /** * Returns the identification string associated with this * {@code GraphicsDevice}. *
* A particular program might use more than one * {@code GraphicsDevice} in a {@code GraphicsEnvironment}. * This method returns a {@code String} identifying a * particular {@code GraphicsDevice} in the local * {@code GraphicsEnvironment}. Although there is * no public method to set this {@code String}, a programmer can * use the {@code String} for debugging purposes. Vendors of * the Java Runtime Environment can * format the return value of the {@code String}. To determine * how to interpret the value of the {@code String}, contact the * vendor of your Java Runtime. To find out who the vendor is, from * your program, call the * {@link System#getProperty(String) getProperty} method of the * System class with "java.vendor". * @return a {@code String} that is the identification * of this {@code GraphicsDevice}. */ public abstract String getIDstring(); /** * Returns all of the {@code GraphicsConfiguration} * objects associated with this {@code GraphicsDevice}. * @return an array of {@code GraphicsConfiguration} * objects that are associated with this * {@code GraphicsDevice}. */ public abstract GraphicsConfiguration[] getConfigurations(); /** * Returns the default {@code GraphicsConfiguration} * associated with this {@code GraphicsDevice}. * @return the default {@code GraphicsConfiguration} * of this {@code GraphicsDevice}. */ public abstract GraphicsConfiguration getDefaultConfiguration(); /** * Returns the "best" configuration possible that passes the * criteria defined in the {@link GraphicsConfigTemplate}. * @param gct the {@code GraphicsConfigTemplate} object * used to obtain a valid {@code GraphicsConfiguration} * @return a {@code GraphicsConfiguration} that passes * the criteria defined in the specified * {@code GraphicsConfigTemplate}. * @see GraphicsConfigTemplate */ public GraphicsConfiguration getBestConfiguration(GraphicsConfigTemplate gct) { GraphicsConfiguration[] configs = getConfigurations(); return gct.getBestConfiguration(configs); } /** * Returns {@code true} if this {@code GraphicsDevice} * supports full-screen exclusive mode. * If a SecurityManager is installed, its * {@code checkPermission} method will be called * with {@code AWTPermission("fullScreenExclusive")}. * {@code isFullScreenSupported} returns true only if * that permission is granted. * @return whether full-screen exclusive mode is available for * this graphics device * @see java.awt.AWTPermission * @since 1.4 */ public boolean isFullScreenSupported() { return false; } /** * Enter full-screen mode, or return to windowed mode. The entered * full-screen mode may be either exclusive or simulated. Exclusive * mode is only available if {@code isFullScreenSupported} * returns {@code true}. *
* Exclusive mode implies: *
* The simulated full-screen mode places and resizes the window to the maximum * possible visible area of the screen. However, the native windowing system * may modify the requested geometry-related data, so that the {@code Window} object * is placed and sized in a way that corresponds closely to the desktop settings. *
* When entering full-screen mode, if the window to be used as a * full-screen window is not visible, this method will make it visible. * It will remain visible when returning to windowed mode. *
* When entering full-screen mode, all the translucency effects are reset for * the window. Its shape is set to {@code null}, the opacity value is set to * 1.0f, and the background color alpha is set to 255 (completely opaque). * These values are not restored when returning to windowed mode. *
* It is unspecified and platform-dependent how decorated windows operate * in full-screen mode. For this reason, it is recommended to turn off * the decorations in a {@code Frame} or {@code Dialog} object by using the * {@code setUndecorated} method. *
* When returning to windowed mode from an exclusive full-screen window, * any display changes made by calling {@code setDisplayMode} are * automatically restored to their original state. * * @param w a window to use as the full-screen window; {@code null} * if returning to windowed mode. Some platforms expect the * fullscreen window to be a top-level component (i.e., a {@code Frame}); * therefore it is preferable to use a {@code Frame} here rather than a * {@code Window}. * * @see #isFullScreenSupported * @see #getFullScreenWindow * @see #setDisplayMode * @see Component#enableInputMethods * @see Component#setVisible * @see Frame#setUndecorated * @see Dialog#setUndecorated * * @since 1.4 */ public void setFullScreenWindow(Window w) { if (w != null) { if (w.getShape() != null) { w.setShape(null); } if (w.getOpacity() < 1.0f) { w.setOpacity(1.0f); } if (!w.isOpaque()) { Color bgColor = w.getBackground(); bgColor = new Color(bgColor.getRed(), bgColor.getGreen(), bgColor.getBlue(), 255); w.setBackground(bgColor); } // Check if this window is in fullscreen mode on another device. final GraphicsConfiguration gc = w.getGraphicsConfiguration(); if (gc != null && gc.getDevice() != this && gc.getDevice().getFullScreenWindow() == w) { gc.getDevice().setFullScreenWindow(null); } } if (fullScreenWindow != null && windowedModeBounds != null) { // if the window went into fs mode before it was realized it may // have (0,0) dimensions if (windowedModeBounds.width == 0) windowedModeBounds.width = 1; if (windowedModeBounds.height == 0) windowedModeBounds.height = 1; fullScreenWindow.setBounds(windowedModeBounds); } // Set the full screen window synchronized (fsAppContextLock) { // Associate fullscreen window with current AppContext if (w == null) { fullScreenAppContext = null; } else { fullScreenAppContext = AppContext.getAppContext(); } fullScreenWindow = w; } if (fullScreenWindow != null) { windowedModeBounds = fullScreenWindow.getBounds(); // Note that we use the graphics configuration of the device, // not the window's, because we're setting the fs window for // this device. final GraphicsConfiguration gc = getDefaultConfiguration(); final Rectangle screenBounds = gc.getBounds(); if (SunToolkit.isDispatchThreadForAppContext(fullScreenWindow)) { // Update graphics configuration here directly and do not wait // asynchronous notification from the peer. Note that // setBounds() will reset a GC, if it was set incorrectly. fullScreenWindow.setGraphicsConfiguration(gc); } fullScreenWindow.setBounds(screenBounds.x, screenBounds.y, screenBounds.width, screenBounds.height); fullScreenWindow.setVisible(true); fullScreenWindow.toFront(); } } /** * Returns the {@code Window} object representing the * full-screen window if the device is in full-screen mode. * * @return the full-screen window, or {@code null} if the device is * not in full-screen mode. * @see #setFullScreenWindow(Window) * @since 1.4 */ public Window getFullScreenWindow() { Window returnWindow = null; synchronized (fsAppContextLock) { // Only return a handle to the current fs window if we are in the // same AppContext that set the fs window if (fullScreenAppContext == AppContext.getAppContext()) { returnWindow = fullScreenWindow; } } return returnWindow; } /** * Returns {@code true} if this {@code GraphicsDevice} * supports low-level display changes. * On some platforms low-level display changes may only be allowed in * full-screen exclusive mode (i.e., if {@link #isFullScreenSupported()} * returns {@code true} and the application has already entered * full-screen mode using {@link #setFullScreenWindow}). * @return whether low-level display changes are supported for this * graphics device. * @see #isFullScreenSupported * @see #setDisplayMode * @see #setFullScreenWindow * @since 1.4 */ public boolean isDisplayChangeSupported() { return false; } /** * Sets the display mode of this graphics device. This is only allowed * if {@link #isDisplayChangeSupported()} returns {@code true} and may * require first entering full-screen exclusive mode using * {@link #setFullScreenWindow} providing that full-screen exclusive mode is * supported (i.e., {@link #isFullScreenSupported()} returns * {@code true}). *
* * The display mode must be one of the display modes returned by * {@link #getDisplayModes()}, with one exception: passing a display mode * with {@link DisplayMode#REFRESH_RATE_UNKNOWN} refresh rate will result in * selecting a display mode from the list of available display modes with * matching width, height and bit depth. * However, passing a display mode with {@link DisplayMode#BIT_DEPTH_MULTI} * for bit depth is only allowed if such mode exists in the list returned by * {@link #getDisplayModes()}. *
* Example code: *
* Frame frame;
* DisplayMode newDisplayMode;
* GraphicsDevice gd;
* // create a Frame, select desired DisplayMode from the list of modes
* // returned by gd.getDisplayModes() ...
*
* if (gd.isFullScreenSupported()) {
* gd.setFullScreenWindow(frame);
* } else {
* // proceed in non-full-screen mode
* frame.setSize(...);
* frame.setLocation(...);
* frame.setVisible(true);
* }
*
* if (gd.isDisplayChangeSupported()) {
* gd.setDisplayMode(newDisplayMode);
* }
*
*
* @param dm The new display mode of this graphics device.
* @exception IllegalArgumentException if the {@code DisplayMode}
* supplied is {@code null}, or is not available in the array returned
* by {@code getDisplayModes}
* @exception UnsupportedOperationException if
* {@code isDisplayChangeSupported} returns {@code false}
* @see #getDisplayMode
* @see #getDisplayModes
* @see #isDisplayChangeSupported
* @since 1.4
*/
public void setDisplayMode(DisplayMode dm) {
throw new UnsupportedOperationException("Cannot change display mode");
}
/**
* Returns the current display mode of this
* {@code GraphicsDevice}.
* The returned display mode is allowed to have a refresh rate
* {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
* Likewise, the returned display mode is allowed to have a bit depth
* {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
* bit depths are supported.
* @return the current display mode of this graphics device.
* @see #setDisplayMode(DisplayMode)
* @since 1.4
*/
public DisplayMode getDisplayMode() {
GraphicsConfiguration gc = getDefaultConfiguration();
Rectangle r = gc.getBounds();
ColorModel cm = gc.getColorModel();
return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);
}
/**
* Returns all display modes available for this
* {@code GraphicsDevice}.
* The returned display modes are allowed to have a refresh rate
* {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
* Likewise, the returned display modes are allowed to have a bit depth
* {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
* bit depths are supported.
* @return all of the display modes available for this graphics device.
* @since 1.4
*/
public DisplayMode[] getDisplayModes() {
return new DisplayMode[] { getDisplayMode() };
}
/**
* This method returns the number of bytes available in
* accelerated memory on this device.
* Some images are created or cached
* in accelerated memory on a first-come,
* first-served basis. On some operating systems,
* this memory is a finite resource. Calling this method
* and scheduling the creation and flushing of images carefully may
* enable applications to make the most efficient use of
* that finite resource.
*