001: /*
002: * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.awt;
027:
028: import java.awt.image.ColorModel;
029: import sun.awt.AppContext;
030:
031: /**
032: * The <code>GraphicsDevice</code> class describes the graphics devices
033: * that might be available in a particular graphics environment. These
034: * include screen and printer devices. Note that there can be many screens
035: * and many printers in an instance of {@link GraphicsEnvironment}. Each
036: * graphics device has one or more {@link GraphicsConfiguration} objects
037: * associated with it. These objects specify the different configurations
038: * in which the <code>GraphicsDevice</code> can be used.
039: * <p>
040: * In a multi-screen environment, the <code>GraphicsConfiguration</code>
041: * objects can be used to render components on multiple screens. The
042: * following code sample demonstrates how to create a <code>JFrame</code>
043: * object for each <code>GraphicsConfiguration</code> on each screen
044: * device in the <code>GraphicsEnvironment</code>:
045: * <pre>
046: * GraphicsEnvironment ge = GraphicsEnvironment.
047: * getLocalGraphicsEnvironment();
048: * GraphicsDevice[] gs = ge.getScreenDevices();
049: * for (int j = 0; j < gs.length; j++) {
050: * GraphicsDevice gd = gs[j];
051: * GraphicsConfiguration[] gc =
052: * gd.getConfigurations();
053: * for (int i=0; i < gc.length; i++) {
054: * JFrame f = new
055: * JFrame(gs[j].getDefaultConfiguration());
056: * Canvas c = new Canvas(gc[i]);
057: * Rectangle gcBounds = gc[i].getBounds();
058: * int xoffs = gcBounds.x;
059: * int yoffs = gcBounds.y;
060: * f.getContentPane().add(c);
061: * f.setLocation((i*50)+xoffs, (i*60)+yoffs);
062: * f.show();
063: * }
064: * }
065: * </pre>
066: * <p>
067: * For more information on full-screen exclusive mode API, see the
068: * <a href="http://java.sun.com/docs/books/tutorial/extra/fullscreen/index.html">
069: * Full-Screen Exclusive Mode API Tutorial</a>.
070: *
071: * @see GraphicsEnvironment
072: * @see GraphicsConfiguration
073: * @version 1.47, 05/05/07
074: */
075: public abstract class GraphicsDevice {
076:
077: private Window fullScreenWindow;
078: private AppContext fullScreenAppContext; // tracks which AppContext
079: // created the FS window
080: // this lock is used for making synchronous changes to the AppContext's
081: // current full screen window
082: private final Object fsAppContextLock = new Object();
083:
084: private Rectangle windowedModeBounds;
085:
086: /**
087: * This is an abstract class that cannot be instantiated directly.
088: * Instances must be obtained from a suitable factory or query method.
089: * @see GraphicsEnvironment#getScreenDevices
090: * @see GraphicsEnvironment#getDefaultScreenDevice
091: * @see GraphicsConfiguration#getDevice
092: */
093: protected GraphicsDevice() {
094: }
095:
096: /**
097: * Device is a raster screen.
098: */
099: public final static int TYPE_RASTER_SCREEN = 0;
100:
101: /**
102: * Device is a printer.
103: */
104: public final static int TYPE_PRINTER = 1;
105:
106: /**
107: * Device is an image buffer. This buffer can reside in device
108: * or system memory but it is not physically viewable by the user.
109: */
110: public final static int TYPE_IMAGE_BUFFER = 2;
111:
112: /**
113: * Returns the type of this <code>GraphicsDevice</code>.
114: * @return the type of this <code>GraphicsDevice</code>, which can
115: * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.
116: * @see #TYPE_RASTER_SCREEN
117: * @see #TYPE_PRINTER
118: * @see #TYPE_IMAGE_BUFFER
119: */
120: public abstract int getType();
121:
122: /**
123: * Returns the identification string associated with this
124: * <code>GraphicsDevice</code>.
125: * <p>
126: * A particular program might use more than one
127: * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.
128: * This method returns a <code>String</code> identifying a
129: * particular <code>GraphicsDevice</code> in the local
130: * <code>GraphicsEnvironment</code>. Although there is
131: * no public method to set this <code>String</code>, a programmer can
132: * use the <code>String</code> for debugging purposes. Vendors of
133: * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can
134: * format the return value of the <code>String</code>. To determine
135: * how to interpret the value of the <code>String</code>, contact the
136: * vendor of your Java Runtime. To find out who the vendor is, from
137: * your program, call the
138: * {@link System#getProperty(String) getProperty} method of the
139: * System class with "java.vendor".
140: * @return a <code>String</code> that is the identification
141: * of this <code>GraphicsDevice</code>.
142: */
143: public abstract String getIDstring();
144:
145: /**
146: * Returns all of the <code>GraphicsConfiguration</code>
147: * objects associated with this <code>GraphicsDevice</code>.
148: * @return an array of <code>GraphicsConfiguration</code>
149: * objects that are associated with this
150: * <code>GraphicsDevice</code>.
151: */
152: public abstract GraphicsConfiguration[] getConfigurations();
153:
154: /**
155: * Returns the default <code>GraphicsConfiguration</code>
156: * associated with this <code>GraphicsDevice</code>.
157: * @return the default <code>GraphicsConfiguration</code>
158: * of this <code>GraphicsDevice</code>.
159: */
160: public abstract GraphicsConfiguration getDefaultConfiguration();
161:
162: /**
163: * Returns the "best" configuration possible that passes the
164: * criteria defined in the {@link GraphicsConfigTemplate}.
165: * @param gct the <code>GraphicsConfigTemplate</code> object
166: * used to obtain a valid <code>GraphicsConfiguration</code>
167: * @return a <code>GraphicsConfiguration</code> that passes
168: * the criteria defined in the specified
169: * <code>GraphicsConfigTemplate</code>.
170: * @see GraphicsConfigTemplate
171: */
172: public GraphicsConfiguration getBestConfiguration(
173: GraphicsConfigTemplate gct) {
174: GraphicsConfiguration[] configs = getConfigurations();
175: return gct.getBestConfiguration(configs);
176: }
177:
178: /**
179: * Returns <code>true</code> if this <code>GraphicsDevice</code>
180: * supports full-screen exclusive mode.
181: * If a SecurityManager is installed, its
182: * <code>checkPermission</code> method will be called
183: * with <code>AWTPermission("fullScreenExclusive")</code>.
184: * <code>isFullScreenSupported</code> returns true only if
185: * that permission is granted.
186: * @return whether full-screen exclusive mode is available for
187: * this graphics device
188: * @see java.awt.AWTPermission
189: * @since 1.4
190: */
191: public boolean isFullScreenSupported() {
192: return false;
193: }
194:
195: /**
196: * Enter full-screen mode, or return to windowed mode. The entered
197: * full-screen mode may be either exclusive or simulated. Exclusive
198: * mode is only available if <code>isFullScreenSupported</code>
199: * returns <code>true</code>.
200: * <p>
201: * Exclusive mode implies:
202: * <ul>
203: * <li>Windows cannot overlap the full-screen window. All other application
204: * windows will always appear beneath the full-screen window in the Z-order.
205: * <li>There can be only one full-screen window on a device at any time,
206: * so calling this method while there is an existing full-screen Window
207: * will cause the existing full-screen window to
208: * return to windowed mode.
209: * <li>Input method windows are disabled. It is advisable to call
210: * <code>Component.enableInputMethods(false)</code> to make a component
211: * a non-client of the input method framework.
212: * </ul>
213: * <p>
214: * Simulated full-screen mode resizes
215: * the window to the size of the screen and positions it at (0,0).
216: * <p>
217: * When entering full-screen mode, if the window to be used as the
218: * full-screen window is not visible, this method will make it visible.
219: * It will remain visible when returning to windowed mode.
220: * <p>
221: * When returning to windowed mode from an exclusive full-screen window, any
222: * display changes made by calling <code>setDisplayMode</code> are
223: * automatically restored to their original state.
224: *
225: * @param w a window to use as the full-screen window; <code>null</code>
226: * if returning to windowed mode. Some platforms expect the
227: * fullscreen window to be a top-level component (i.e., a Frame);
228: * therefore it is preferable to use a Frame here rather than a
229: * Window.
230: * @see #isFullScreenSupported
231: * @see #getFullScreenWindow
232: * @see #setDisplayMode
233: * @see Component#enableInputMethods
234: * @see Component#setVisible
235: * @since 1.4
236: */
237: public void setFullScreenWindow(Window w) {
238: if (fullScreenWindow != null && windowedModeBounds != null) {
239: fullScreenWindow.setBounds(windowedModeBounds);
240: }
241: // Set the full screen window
242: synchronized (fsAppContextLock) {
243: // Associate fullscreen window with current AppContext
244: if (w == null) {
245: fullScreenAppContext = null;
246: } else {
247: fullScreenAppContext = AppContext.getAppContext();
248: }
249: fullScreenWindow = w;
250: }
251: if (fullScreenWindow != null) {
252: windowedModeBounds = fullScreenWindow.getBounds();
253: // Note that we use the graphics configuration of the device,
254: // not the window's, because we're setting the fs window for
255: // this device.
256: Rectangle screenBounds = getDefaultConfiguration()
257: .getBounds();
258: fullScreenWindow.setBounds(screenBounds.x, screenBounds.y,
259: screenBounds.width, screenBounds.height);
260: fullScreenWindow.setVisible(true);
261: fullScreenWindow.toFront();
262: }
263: }
264:
265: /**
266: * Returns the <code>Window</code> object representing the
267: * full-screen window if the device is in full-screen mode.
268: *
269: * @return the full-screen window, or <code>null</code> if the device is
270: * not in full-screen mode.
271: * @see #setFullScreenWindow(Window)
272: * @since 1.4
273: */
274: public Window getFullScreenWindow() {
275: Window returnWindow = null;
276: synchronized (fsAppContextLock) {
277: // Only return a handle to the current fs window if we are in the
278: // same AppContext that set the fs window
279: if (fullScreenAppContext == AppContext.getAppContext()) {
280: returnWindow = fullScreenWindow;
281: }
282: }
283: return returnWindow;
284: }
285:
286: /**
287: * Returns <code>true</code> if this <code>GraphicsDevice</code>
288: * supports low-level display changes.
289: * On some platforms low-level display changes may only be allowed in
290: * full-screen exclusive mode (i.e., if {@link #isFullScreenSupported()}
291: * returns {@code true} and the application has already entered
292: * full-screen mode using {@link #setFullScreenWindow}).
293: * @return whether low-level display changes are supported for this
294: * graphics device.
295: * @see #isFullScreenSupported
296: * @see #setDisplayMode
297: * @see #setFullScreenWindow
298: * @since 1.4
299: */
300: public boolean isDisplayChangeSupported() {
301: return false;
302: }
303:
304: /**
305: * Sets the display mode of this graphics device. This is only allowed
306: * if {@link #isDisplayChangeSupported()} returns {@code true} and may
307: * require first entering full-screen exclusive mode using
308: * {@link #setFullScreenWindow} providing that full-screen exclusive mode is
309: * supported (i.e., {@link #isFullScreenSupported()} returns
310: * {@code true}).
311: * <p>
312: *
313: * The display mode must be one of the display modes returned by
314: * {@link #getDisplayModes()}, with one exception: passing a display mode
315: * with {@link DisplayMode#REFRESH_RATE_UNKNOWN} refresh rate will result in
316: * selecting a display mode from the list of available display modes with
317: * matching width, height and bit depth.
318: * However, passing a display mode with {@link DisplayMode#BIT_DEPTH_MULTI}
319: * for bit depth is only allowed if such mode exists in the list returned by
320: * {@link #getDisplayModes()}.
321: * <p>
322: * Example code:
323: * <pre><code>
324: * Frame frame;
325: * DisplayMode newDisplayMode;
326: * GraphicsDevice gd;
327: * // create a Frame, select desired DisplayMode from the list of modes
328: * // returned by gd.getDisplayModes() ...
329: *
330: * if (gd.isFullScreenSupported()) {
331: * gd.setFullScreenWindow(frame);
332: * } else {
333: * // proceed in non-full-screen mode
334: * frame.setSize(...);
335: * frame.setLocation(...);
336: * frame.setVisible(true);
337: * }
338: *
339: * if (gd.isDisplayChangeSupported()) {
340: * gd.setDisplayMode(newDisplayMode);
341: * }
342: * </code></pre>
343: *
344: * @param dm The new display mode of this graphics device.
345: * @exception IllegalArgumentException if the <code>DisplayMode</code>
346: * supplied is <code>null</code>, or is not available in the array returned
347: * by <code>getDisplayModes</code>
348: * @exception UnsupportedOperationException if
349: * <code>isDisplayChangeSupported</code> returns <code>false</code>
350: * @see #getDisplayMode
351: * @see #getDisplayModes
352: * @see #isDisplayChangeSupported
353: * @since 1.4
354: */
355: public void setDisplayMode(DisplayMode dm) {
356: throw new UnsupportedOperationException(
357: "Cannot change display mode");
358: }
359:
360: /**
361: * Returns the current display mode of this
362: * <code>GraphicsDevice</code>.
363: * The returned display mode is allowed to have a refresh rate
364: * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
365: * Likewise, the returned display mode is allowed to have a bit depth
366: * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
367: * bit depths are supported.
368: * @return the current display mode of this graphics device.
369: * @see #setDisplayMode(DisplayMode)
370: * @since 1.4
371: */
372: public DisplayMode getDisplayMode() {
373: GraphicsConfiguration gc = getDefaultConfiguration();
374: Rectangle r = gc.getBounds();
375: ColorModel cm = gc.getColorModel();
376: return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);
377: }
378:
379: /**
380: * Returns all display modes available for this
381: * <code>GraphicsDevice</code>.
382: * The returned display modes are allowed to have a refresh rate
383: * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
384: * Likewise, the returned display modes are allowed to have a bit depth
385: * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
386: * bit depths are supported.
387: * @return all of the display modes available for this graphics device.
388: * @since 1.4
389: */
390: public DisplayMode[] getDisplayModes() {
391: return new DisplayMode[] { getDisplayMode() };
392: }
393:
394: /**
395: * This method returns the number of bytes available in
396: * accelerated memory on this device.
397: * Some images are created or cached
398: * in accelerated memory on a first-come,
399: * first-served basis. On some operating systems,
400: * this memory is a finite resource. Calling this method
401: * and scheduling the creation and flushing of images carefully may
402: * enable applications to make the most efficient use of
403: * that finite resource.
404: * <br>
405: * Note that the number returned is a snapshot of how much
406: * memory is available; some images may still have problems
407: * being allocated into that memory. For example, depending
408: * on operating system, driver, memory configuration, and
409: * thread situations, the full extent of the size reported
410: * may not be available for a given image. There are further
411: * inquiry methods on the {@link ImageCapabilities} object
412: * associated with a VolatileImage that can be used to determine
413: * whether a particular VolatileImage has been created in accelerated
414: * memory.
415: * @return number of bytes available in accelerated memory.
416: * A negative return value indicates that the amount of accelerated memory
417: * on this GraphicsDevice is indeterminate.
418: * @see java.awt.image.VolatileImage#flush
419: * @see ImageCapabilities#isAccelerated
420: * @since 1.4
421: */
422: public int getAvailableAcceleratedMemory() {
423: return -1;
424: }
425: }
|
