J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 1997-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | |
| 27 | package java.awt; |
| 28 | |
| 29 | import java.awt.image.ColorModel; |
| 30 | import sun.awt.AppContext; |
| 31 | |
| 32 | /** |
| 33 | * The <code>GraphicsDevice</code> class describes the graphics devices |
| 34 | * that might be available in a particular graphics environment. These |
| 35 | * include screen and printer devices. Note that there can be many screens |
| 36 | * and many printers in an instance of {@link GraphicsEnvironment}. Each |
| 37 | * graphics device has one or more {@link GraphicsConfiguration} objects |
| 38 | * associated with it. These objects specify the different configurations |
| 39 | * in which the <code>GraphicsDevice</code> can be used. |
| 40 | * <p> |
| 41 | * In a multi-screen environment, the <code>GraphicsConfiguration</code> |
| 42 | * objects can be used to render components on multiple screens. The |
| 43 | * following code sample demonstrates how to create a <code>JFrame</code> |
| 44 | * object for each <code>GraphicsConfiguration</code> on each screen |
| 45 | * device in the <code>GraphicsEnvironment</code>: |
| 46 | * <pre> |
| 47 | * GraphicsEnvironment ge = GraphicsEnvironment. |
| 48 | * getLocalGraphicsEnvironment(); |
| 49 | * GraphicsDevice[] gs = ge.getScreenDevices(); |
| 50 | * for (int j = 0; j < gs.length; j++) { |
| 51 | * GraphicsDevice gd = gs[j]; |
| 52 | * GraphicsConfiguration[] gc = |
| 53 | * gd.getConfigurations(); |
| 54 | * for (int i=0; i < gc.length; i++) { |
| 55 | * JFrame f = new |
| 56 | * JFrame(gs[j].getDefaultConfiguration()); |
| 57 | * Canvas c = new Canvas(gc[i]); |
| 58 | * Rectangle gcBounds = gc[i].getBounds(); |
| 59 | * int xoffs = gcBounds.x; |
| 60 | * int yoffs = gcBounds.y; |
| 61 | * f.getContentPane().add(c); |
| 62 | * f.setLocation((i*50)+xoffs, (i*60)+yoffs); |
| 63 | * f.show(); |
| 64 | * } |
| 65 | * } |
| 66 | * </pre> |
| 67 | * <p> |
| 68 | * For more information on full-screen exclusive mode API, see the |
| 69 | * <a href="http://java.sun.com/docs/books/tutorial/extra/fullscreen/index.html"> |
| 70 | * Full-Screen Exclusive Mode API Tutorial</a>. |
| 71 | * |
| 72 | * @see GraphicsEnvironment |
| 73 | * @see GraphicsConfiguration |
| 74 | */ |
| 75 | public abstract class GraphicsDevice { |
| 76 | |
| 77 | private Window fullScreenWindow; |
| 78 | private AppContext fullScreenAppContext; // tracks which AppContext |
| 79 | // created the FS window |
| 80 | // this lock is used for making synchronous changes to the AppContext's |
| 81 | // current full screen window |
| 82 | private final Object fsAppContextLock = new Object(); |
| 83 | |
| 84 | private Rectangle windowedModeBounds; |
| 85 | |
| 86 | /** |
| 87 | * This is an abstract class that cannot be instantiated directly. |
| 88 | * Instances must be obtained from a suitable factory or query method. |
| 89 | * @see GraphicsEnvironment#getScreenDevices |
| 90 | * @see GraphicsEnvironment#getDefaultScreenDevice |
| 91 | * @see GraphicsConfiguration#getDevice |
| 92 | */ |
| 93 | protected GraphicsDevice() { |
| 94 | } |
| 95 | |
| 96 | /** |
| 97 | * Device is a raster screen. |
| 98 | */ |
| 99 | 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 |
| 173 | getBestConfiguration(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().getBounds(); |
| 257 | fullScreenWindow.setBounds(screenBounds.x, screenBounds.y, |
| 258 | screenBounds.width, screenBounds.height); |
| 259 | fullScreenWindow.setVisible(true); |
| 260 | fullScreenWindow.toFront(); |
| 261 | } |
| 262 | } |
| 263 | |
| 264 | /** |
| 265 | * Returns the <code>Window</code> object representing the |
| 266 | * full-screen window if the device is in full-screen mode. |
| 267 | * |
| 268 | * @return the full-screen window, or <code>null</code> if the device is |
| 269 | * not in full-screen mode. |
| 270 | * @see #setFullScreenWindow(Window) |
| 271 | * @since 1.4 |
| 272 | */ |
| 273 | public Window getFullScreenWindow() { |
| 274 | Window returnWindow = null; |
| 275 | synchronized (fsAppContextLock) { |
| 276 | // Only return a handle to the current fs window if we are in the |
| 277 | // same AppContext that set the fs window |
| 278 | if (fullScreenAppContext == AppContext.getAppContext()) { |
| 279 | returnWindow = fullScreenWindow; |
| 280 | } |
| 281 | } |
| 282 | return returnWindow; |
| 283 | } |
| 284 | |
| 285 | /** |
| 286 | * Returns <code>true</code> if this <code>GraphicsDevice</code> |
| 287 | * supports low-level display changes. |
| 288 | * On some platforms low-level display changes may only be allowed in |
| 289 | * full-screen exclusive mode (i.e., if {@link #isFullScreenSupported()} |
| 290 | * returns {@code true} and the application has already entered |
| 291 | * full-screen mode using {@link #setFullScreenWindow}). |
| 292 | * @return whether low-level display changes are supported for this |
| 293 | * graphics device. |
| 294 | * @see #isFullScreenSupported |
| 295 | * @see #setDisplayMode |
| 296 | * @see #setFullScreenWindow |
| 297 | * @since 1.4 |
| 298 | */ |
| 299 | public boolean isDisplayChangeSupported() { |
| 300 | return false; |
| 301 | } |
| 302 | |
| 303 | /** |
| 304 | * Sets the display mode of this graphics device. This is only allowed |
| 305 | * if {@link #isDisplayChangeSupported()} returns {@code true} and may |
| 306 | * require first entering full-screen exclusive mode using |
| 307 | * {@link #setFullScreenWindow} providing that full-screen exclusive mode is |
| 308 | * supported (i.e., {@link #isFullScreenSupported()} returns |
| 309 | * {@code true}). |
| 310 | * <p> |
| 311 | * |
| 312 | * The display mode must be one of the display modes returned by |
| 313 | * {@link #getDisplayModes()}, with one exception: passing a display mode |
| 314 | * with {@link DisplayMode#REFRESH_RATE_UNKNOWN} refresh rate will result in |
| 315 | * selecting a display mode from the list of available display modes with |
| 316 | * matching width, height and bit depth. |
| 317 | * However, passing a display mode with {@link DisplayMode#BIT_DEPTH_MULTI} |
| 318 | * for bit depth is only allowed if such mode exists in the list returned by |
| 319 | * {@link #getDisplayModes()}. |
| 320 | * <p> |
| 321 | * Example code: |
| 322 | * <pre><code> |
| 323 | * Frame frame; |
| 324 | * DisplayMode newDisplayMode; |
| 325 | * GraphicsDevice gd; |
| 326 | * // create a Frame, select desired DisplayMode from the list of modes |
| 327 | * // returned by gd.getDisplayModes() ... |
| 328 | * |
| 329 | * if (gd.isFullScreenSupported()) { |
| 330 | * gd.setFullScreenWindow(frame); |
| 331 | * } else { |
| 332 | * // proceed in non-full-screen mode |
| 333 | * frame.setSize(...); |
| 334 | * frame.setLocation(...); |
| 335 | * frame.setVisible(true); |
| 336 | * } |
| 337 | * |
| 338 | * if (gd.isDisplayChangeSupported()) { |
| 339 | * gd.setDisplayMode(newDisplayMode); |
| 340 | * } |
| 341 | * </code></pre> |
| 342 | * |
| 343 | * @param dm The new display mode of this graphics device. |
| 344 | * @exception IllegalArgumentException if the <code>DisplayMode</code> |
| 345 | * supplied is <code>null</code>, or is not available in the array returned |
| 346 | * by <code>getDisplayModes</code> |
| 347 | * @exception UnsupportedOperationException if |
| 348 | * <code>isDisplayChangeSupported</code> returns <code>false</code> |
| 349 | * @see #getDisplayMode |
| 350 | * @see #getDisplayModes |
| 351 | * @see #isDisplayChangeSupported |
| 352 | * @since 1.4 |
| 353 | */ |
| 354 | public void setDisplayMode(DisplayMode dm) { |
| 355 | throw new UnsupportedOperationException("Cannot change display mode"); |
| 356 | } |
| 357 | |
| 358 | /** |
| 359 | * Returns the current display mode of this |
| 360 | * <code>GraphicsDevice</code>. |
| 361 | * The returned display mode is allowed to have a refresh rate |
| 362 | * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate. |
| 363 | * Likewise, the returned display mode is allowed to have a bit depth |
| 364 | * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple |
| 365 | * bit depths are supported. |
| 366 | * @return the current display mode of this graphics device. |
| 367 | * @see #setDisplayMode(DisplayMode) |
| 368 | * @since 1.4 |
| 369 | */ |
| 370 | public DisplayMode getDisplayMode() { |
| 371 | GraphicsConfiguration gc = getDefaultConfiguration(); |
| 372 | Rectangle r = gc.getBounds(); |
| 373 | ColorModel cm = gc.getColorModel(); |
| 374 | return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0); |
| 375 | } |
| 376 | |
| 377 | /** |
| 378 | * Returns all display modes available for this |
| 379 | * <code>GraphicsDevice</code>. |
| 380 | * The returned display modes are allowed to have a refresh rate |
| 381 | * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate. |
| 382 | * Likewise, the returned display modes are allowed to have a bit depth |
| 383 | * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple |
| 384 | * bit depths are supported. |
| 385 | * @return all of the display modes available for this graphics device. |
| 386 | * @since 1.4 |
| 387 | */ |
| 388 | public DisplayMode[] getDisplayModes() { |
| 389 | return new DisplayMode[] { getDisplayMode() }; |
| 390 | } |
| 391 | |
| 392 | /** |
| 393 | * This method returns the number of bytes available in |
| 394 | * accelerated memory on this device. |
| 395 | * Some images are created or cached |
| 396 | * in accelerated memory on a first-come, |
| 397 | * first-served basis. On some operating systems, |
| 398 | * this memory is a finite resource. Calling this method |
| 399 | * and scheduling the creation and flushing of images carefully may |
| 400 | * enable applications to make the most efficient use of |
| 401 | * that finite resource. |
| 402 | * <br> |
| 403 | * Note that the number returned is a snapshot of how much |
| 404 | * memory is available; some images may still have problems |
| 405 | * being allocated into that memory. For example, depending |
| 406 | * on operating system, driver, memory configuration, and |
| 407 | * thread situations, the full extent of the size reported |
| 408 | * may not be available for a given image. There are further |
| 409 | * inquiry methods on the {@link ImageCapabilities} object |
| 410 | * associated with a VolatileImage that can be used to determine |
| 411 | * whether a particular VolatileImage has been created in accelerated |
| 412 | * memory. |
| 413 | * @return number of bytes available in accelerated memory. |
| 414 | * A negative return value indicates that the amount of accelerated memory |
| 415 | * on this GraphicsDevice is indeterminate. |
| 416 | * @see java.awt.image.VolatileImage#flush |
| 417 | * @see ImageCapabilities#isAccelerated |
| 418 | * @since 1.4 |
| 419 | */ |
| 420 | public int getAvailableAcceleratedMemory() { |
| 421 | return -1; |
| 422 | } |
| 423 | } |