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 }
|