1. /*
  2. * @(#)GraphicsDevice.java 1.27 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt;
  8. import java.awt.image.ColorModel;
  9. /**
  10. * The <code>GraphicsDevice</code> class describes the graphics devices
  11. * that might be available in a particular graphics environment. These
  12. * include screen and printer devices. Note that there can be many screens
  13. * and many printers in an instance of {@link GraphicsEnvironment}. Each
  14. * graphics device has one or more {@link GraphicsConfiguration} objects
  15. * associated with it. These objects specify the different configurations
  16. * in which the <code>GraphicsDevice</code> can be used.
  17. * <p>
  18. * In a multi-screen environment, the <code>GraphicsConfiguration</code>
  19. * objects can be used to render components on multiple screens. The
  20. * following code sample demonstrates how to create a <code>JFrame</code>
  21. * object for each <code>GraphicsConfiguration</code> on each screen
  22. * device in the <code>GraphicsEnvironment</code>:
  23. * <pre>
  24. * GraphicsEnvironment ge = GraphicsEnvironment.
  25. * getLocalGraphicsEnvironment();
  26. * GraphicsDevice[] gs = ge.getScreenDevices();
  27. * for (int j = 0; j < gs.length; j++) {
  28. * GraphicsDevice gd = gs[j];
  29. * GraphicsConfiguration[] gc =
  30. * gd.getConfigurations();
  31. * for (int i=0; i < gc.length; i++) {
  32. * JFrame f = new
  33. * JFrame(gs[j].getDefaultConfiguration());
  34. * Canvas c = new Canvas(gc[i]);
  35. * Rectangle gcBounds = gc[i].getBounds();
  36. * int xoffs = gcBounds.x;
  37. * int yoffs = gcBounds.y;
  38. * f.getContentPane().add(c);
  39. * f.setLocation((i*50)+xoffs, (i*60)+yoffs);
  40. * f.show();
  41. * }
  42. * }
  43. * </pre>
  44. * @see GraphicsEnvironment
  45. * @see GraphicsConfiguration
  46. * @version 1.27, 01/23/03
  47. */
  48. public abstract class GraphicsDevice {
  49. private Window fullScreenWindow;
  50. private Rectangle windowedModeBounds;
  51. /**
  52. * This is an abstract class that cannot be instantiated directly.
  53. * Instances must be obtained from a suitable factory or query method.
  54. * @see GraphicsEnvironment#getScreenDevices
  55. * @see GraphicsEnvironment#getDefaultScreenDevice
  56. * @see GraphicsConfiguration#getDevice
  57. */
  58. protected GraphicsDevice() {
  59. }
  60. /**
  61. * Device is a raster screen.
  62. */
  63. public final static int TYPE_RASTER_SCREEN = 0;
  64. /**
  65. * Device is a printer.
  66. */
  67. public final static int TYPE_PRINTER = 1;
  68. /**
  69. * Device is an image buffer. This buffer can reside in device
  70. * or system memory but it is not physically viewable by the user.
  71. */
  72. public final static int TYPE_IMAGE_BUFFER = 2;
  73. /**
  74. * Returns the type of this <code>GraphicsDevice</code>.
  75. * @return the type of this <code>GraphicsDevice</code>, which can
  76. * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.
  77. * @see #TYPE_RASTER_SCREEN
  78. * @see #TYPE_PRINTER
  79. * @see #TYPE_IMAGE_BUFFER
  80. */
  81. public abstract int getType();
  82. /**
  83. * Returns the identification string associated with this
  84. * <code>GraphicsDevice</code>.
  85. * <p>
  86. * A particular program might use more than one
  87. * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.
  88. * This method returns a <code>String</code> identifying a
  89. * particular <code>GraphicsDevice</code> in the local
  90. * <code>GraphicsEnvironment</code>. Although there is
  91. * no public method to set this <code>String</code>, a programmer can
  92. * use the <code>String</code> for debugging purposes. Vendors of
  93. * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can
  94. * format the return value of the <code>String</code>. To determine
  95. * how to interpret the value of the <code>String</code>, contact the
  96. * vendor of your Java Runtime. To find out who the vendor is, from
  97. * your program, call the
  98. * {@link System#getProperty(String) getProperty} method of the
  99. * System class with "java.vendor".
  100. * @return a <code>String</code> that is the identification
  101. * of this <code>GraphicsDevice</code>.
  102. */
  103. public abstract String getIDstring();
  104. /**
  105. * Returns all of the <code>GraphicsConfiguration</code>
  106. * objects associated with this <code>GraphicsDevice</code>.
  107. * @return an array of <code>GraphicsConfiguration</code>
  108. * objects that are associated with this
  109. * <code>GraphicsDevice</code>.
  110. */
  111. public abstract GraphicsConfiguration[] getConfigurations();
  112. /**
  113. * Returns the default <code>GraphicsConfiguration</code>
  114. * associated with this <code>GraphicsDevice</code>.
  115. * @return the default <code>GraphicsConfiguration</code>
  116. * of this <code>GraphicsDevice</code>.
  117. */
  118. public abstract GraphicsConfiguration getDefaultConfiguration();
  119. /**
  120. * Returns the "best" configuration possible that passes the
  121. * criteria defined in the {@link GraphicsConfigTemplate}.
  122. * @param gct the <code>GraphicsConfigTemplate</code> object
  123. * used to obtain a valid <code>GraphicsConfiguration</code>
  124. * @return a <code>GraphicsConfiguration</code> that passes
  125. * the criteria defined in the specified
  126. * <code>GraphicsConfigTemplate</code>.
  127. * @see GraphicsConfigTemplate
  128. */
  129. public GraphicsConfiguration
  130. getBestConfiguration(GraphicsConfigTemplate gct) {
  131. GraphicsConfiguration[] configs = getConfigurations();
  132. return gct.getBestConfiguration(configs);
  133. }
  134. /**
  135. * Returns <code>true</code> if this <code>GraphicsDevice</code>
  136. * supports full-screen exclusive mode.
  137. * @return whether full-screen exclusive mode is available for
  138. * this graphics device
  139. * @since 1.4
  140. */
  141. public boolean isFullScreenSupported() {
  142. return false;
  143. }
  144. /**
  145. * Enter full-screen mode, or return to windowed mode.
  146. * <p>
  147. * If <code>isFullScreenSupported</code> returns <code>true</code>, full
  148. * screen mode is considered to be <i>exclusive</i>, which implies:
  149. * <ul>
  150. * <li>Windows cannot overlap the full-screen window. All other application
  151. * windows will always appear beneath the full-screen window in the Z-order.
  152. * <li>Input method windows are disabled. It is advisable to call
  153. * <code>Component.enableInputMethods(false)</code> to make a component
  154. * a non-client of the input method framework.
  155. * </ul>
  156. * <p>
  157. * If <code>isFullScreenSupported</code> returns
  158. * <code>false</code>, full-screen exclusive mode is simulated by resizing
  159. * the window to the size of the screen and positioning it at (0,0).
  160. * <p>
  161. * When returning to windowed mode from an exclusive full-screen window, any
  162. * display changes made by calling <code>setDisplayMode</code> are
  163. * automatically restored to their original state.
  164. *
  165. * @param w a window to use as the full-screen window; <code>null</code>
  166. * if returning to windowed mode.
  167. * @see #isFullScreenSupported
  168. * @see #getFullScreenWindow
  169. * @see #setDisplayMode
  170. * @see Component#enableInputMethods
  171. * @since 1.4
  172. */
  173. public void setFullScreenWindow(Window w) {
  174. // Get display mode before changing the full screen window
  175. DisplayMode dm;
  176. if (w == null) {
  177. dm = null;
  178. } else {
  179. dm = getDisplayMode();
  180. }
  181. if (fullScreenWindow != null && windowedModeBounds != null) {
  182. fullScreenWindow.setBounds(windowedModeBounds);
  183. }
  184. // Set the full screen window
  185. fullScreenWindow = w;
  186. if (fullScreenWindow != null) {
  187. windowedModeBounds = fullScreenWindow.getBounds();
  188. fullScreenWindow.setBounds(0, 0, dm.getWidth(), dm.getHeight());
  189. fullScreenWindow.setVisible(true);
  190. fullScreenWindow.toFront();
  191. }
  192. }
  193. /**
  194. * Returns the <code>Window</code> object representing the
  195. * full-screen window if the device is in full-screen mode.
  196. * @return the full-screen window, <code>null</code> if the device is
  197. * not in full-screen mode.
  198. * @see #setFullScreenWindow(Window)
  199. * @since 1.4
  200. */
  201. public Window getFullScreenWindow() {
  202. return fullScreenWindow;
  203. }
  204. /**
  205. * Returns <code>true</code> if this <code>GraphicsDevice</code>
  206. * supports low-level display changes.
  207. * @return whether low-level display changes are supported for this
  208. * graphics device. Note that this may or may not be dependent on
  209. * full-screen exclusive mode.
  210. * @see #setDisplayMode
  211. * @since 1.4
  212. */
  213. public boolean isDisplayChangeSupported() {
  214. return false;
  215. }
  216. /**
  217. * Sets the display mode of this graphics device. This may only be allowed
  218. * in full-screen, exclusive mode.
  219. * @param dm the new display mode of this graphics device
  220. * @exception IllegalArgumentException if the <code>DisplayMode</code>
  221. * supplied is <code>null</code>, or is not available in the array returned
  222. * by <code>getDisplayModes</code>
  223. * @exception UnsupportedOperationException if
  224. * <code>isDisplayChangeSupported</code> returns <code>false</code>
  225. * @see #getDisplayMode
  226. * @see #getDisplayModes
  227. * @see #isDisplayChangeSupported
  228. * @since 1.4
  229. */
  230. public void setDisplayMode(DisplayMode dm) {
  231. throw new UnsupportedOperationException("Cannot change display mode");
  232. }
  233. /**
  234. * Returns the current display mode of this
  235. * <code>GraphicsDevice</code>.
  236. * @return the current display mode of this graphics device.
  237. * @see #setDisplayMode(DisplayMode)
  238. * @since 1.4
  239. */
  240. public DisplayMode getDisplayMode() {
  241. GraphicsConfiguration gc = getDefaultConfiguration();
  242. Rectangle r = gc.getBounds();
  243. ColorModel cm = gc.getColorModel();
  244. return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);
  245. }
  246. /**
  247. * Returns all display modes available for this
  248. * <code>GraphicsDevice</code>.
  249. * @return all of the display modes available for this graphics device.
  250. * @since 1.4
  251. */
  252. public DisplayMode[] getDisplayModes() {
  253. return new DisplayMode[] { getDisplayMode() };
  254. }
  255. /**
  256. * This method returns the number of bytes available in
  257. * accelerated memory on this device.
  258. * Some images are created or cached
  259. * in accelerated memory on a first-come,
  260. * first-served basis. On some operating systems,
  261. * this memory is a finite resource. Calling this method
  262. * and scheduling the creation and flushing of images carefully may
  263. * enable applications to make the most efficient use of
  264. * that finite resource.
  265. * <br>
  266. * Note that the number returned is a snapshot of how much
  267. * memory is available; some images may still have problems
  268. * being allocated into that memory. For example, depending
  269. * on operating system, driver, memory configuration, and
  270. * thread situations, the full extent of the size reported
  271. * may not be available for a given image. There are further
  272. * inquiry methods on the {@link ImageCapabilities} object
  273. * associated with a VolatileImage that can be used to determine
  274. * whether a particular VolatileImage has been created in accelerated
  275. * memory.
  276. * @return number of bytes available in accelerated memory.
  277. * A negative return value indicates that accelerated memory
  278. * is unlimited.
  279. * @see java.awt.image.VolatileImage#flush
  280. * @see ImageCapabilities#isAccelerated
  281. */
  282. public int getAvailableAcceleratedMemory() {
  283. return -1;
  284. }
  285. }