1. /*

  2.  * @(#)GraphicsDevice.java	1.30 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. 

  9. package java.awt;

  10. 

  11. import java.awt.image.ColorModel;

  12. 

  13. /**

  14.  * The <code>GraphicsDevice</code> class describes the graphics devices

  15.  * that might be available in a particular graphics environment.  These

  16.  * include screen and printer devices. Note that there can be many screens

  17.  * and many printers in an instance of {@link GraphicsEnvironment}. Each

  18.  * graphics device has one or more {@link GraphicsConfiguration} objects

  19.  * associated with it.  These objects specify the different configurations

  20.  * in which the <code>GraphicsDevice</code> can be used.

  21.  * <p>  

  22.  * In a multi-screen environment, the <code>GraphicsConfiguration</code>

  23.  * objects can be used to render components on multiple screens.  The 

  24.  * following code sample demonstrates how to create a <code>JFrame</code>

  25.  * object for each <code>GraphicsConfiguration</code> on each screen

  26.  * device in the <code>GraphicsEnvironment</code>:

  27.  * <pre>

  28.  *   GraphicsEnvironment ge = GraphicsEnvironment.

  29.  *   getLocalGraphicsEnvironment();

  30.  *   GraphicsDevice[] gs = ge.getScreenDevices();

  31.  *   for (int j = 0; j < gs.length; j++) { 

  32.  *      GraphicsDevice gd = gs[j];

  33.  *      GraphicsConfiguration[] gc =

  34.  * 	gd.getConfigurations();

  35.  *      for (int i=0; i < gc.length; i++) {

  36.  *         JFrame f = new

  37.  *         JFrame(gs[j].getDefaultConfiguration());

  38.  *         Canvas c = new Canvas(gc[i]); 

  39.  *         Rectangle gcBounds = gc[i].getBounds();

  40.  *         int xoffs = gcBounds.x;

  41.  *         int yoffs = gcBounds.y;

  42.  *	   f.getContentPane().add(c);

  43.  *	   f.setLocation((i*50)+xoffs, (i*60)+yoffs);

  44.  *         f.show();

  45.  *      }

  46.  *   }

  47.  * </pre>                           

  48.  * @see GraphicsEnvironment

  49.  * @see GraphicsConfiguration

  50.  * @version 1.30, 12/19/03

  51.  */

  52. public abstract class GraphicsDevice {

  53. 

  54.     private Window fullScreenWindow;

  55.     private Rectangle windowedModeBounds;

  56.     

  57.     /**

  58.      * This is an abstract class that cannot be instantiated directly.

  59.      * Instances must be obtained from a suitable factory or query method.

  60.      * @see GraphicsEnvironment#getScreenDevices

  61.      * @see GraphicsEnvironment#getDefaultScreenDevice

  62.      * @see GraphicsConfiguration#getDevice

  63.      */

  64.     protected GraphicsDevice() {

  65.     }

  66. 

  67.     /**

  68.      * Device is a raster screen.

  69.      */

  70.     public final static int TYPE_RASTER_SCREEN		= 0;

  71. 

  72.     /**

  73.      * Device is a printer.

  74.      */

  75.     public final static int TYPE_PRINTER		= 1;

  76. 

  77.     /**

  78.      * Device is an image buffer.  This buffer can reside in device

  79.      * or system memory but it is not physically viewable by the user.

  80.      */

  81.     public final static int TYPE_IMAGE_BUFFER           = 2;

  82.     

  83.     /**

  84.      * Returns the type of this <code>GraphicsDevice</code>.

  85.      * @return the type of this <code>GraphicsDevice</code>, which can

  86.      * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.

  87.      * @see #TYPE_RASTER_SCREEN

  88.      * @see #TYPE_PRINTER

  89.      * @see #TYPE_IMAGE_BUFFER

  90.      */

  91.     public abstract int getType();

  92. 

  93.     /**

  94.      * Returns the identification string associated with this 

  95.      * <code>GraphicsDevice</code>.

  96.      * <p>

  97.      * A particular program might use more than one 

  98.      * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.

  99.      * This method returns a <code>String</code> identifying a

  100.      * particular <code>GraphicsDevice</code> in the local

  101.      * <code>GraphicsEnvironment</code>.  Although there is

  102.      * no public method to set this <code>String</code>, a programmer can

  103.      * use the <code>String</code> for debugging purposes.  Vendors of 

  104.      * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can

  105.      * format the return value of the <code>String</code>.  To determine 

  106.      * how to interpret the value of the <code>String</code>, contact the

  107.      * vendor of your Java Runtime.  To find out who the vendor is, from

  108.      * your program, call the 

  109.      * {@link System#getProperty(String) getProperty} method of the

  110.      * System class with "java.vendor".

  111.      * @return a <code>String</code> that is the identification

  112.      * of this <code>GraphicsDevice</code>.

  113.      */

  114.     public abstract String getIDstring();

  115.     

  116.     /**

  117.      * Returns all of the <code>GraphicsConfiguration</code>

  118.      * objects associated with this <code>GraphicsDevice</code>.

  119.      * @return an array of <code>GraphicsConfiguration</code>

  120.      * objects that are associated with this 

  121.      * <code>GraphicsDevice</code>.

  122.      */

  123.     public abstract GraphicsConfiguration[] getConfigurations();

  124. 

  125.     /**

  126.      * Returns the default <code>GraphicsConfiguration</code>

  127.      * associated with this <code>GraphicsDevice</code>.

  128.      * @return the default <code>GraphicsConfiguration</code>

  129.      * of this <code>GraphicsDevice</code>.

  130.      */

  131.     public abstract GraphicsConfiguration getDefaultConfiguration();

  132. 

  133.     /**

  134.      * Returns the "best" configuration possible that passes the

  135.      * criteria defined in the {@link GraphicsConfigTemplate}.

  136.      * @param gct the <code>GraphicsConfigTemplate</code> object

  137.      * used to obtain a valid <code>GraphicsConfiguration</code>

  138.      * @return a <code>GraphicsConfiguration</code> that passes

  139.      * the criteria defined in the specified

  140.      * <code>GraphicsConfigTemplate</code>.

  141.      * @see GraphicsConfigTemplate

  142.      */

  143.     public GraphicsConfiguration

  144.            getBestConfiguration(GraphicsConfigTemplate gct) {

  145.         GraphicsConfiguration[] configs = getConfigurations();

  146.         return gct.getBestConfiguration(configs);

  147.     }

  148.  

  149.     /**

  150.      * Returns <code>true</code> if this <code>GraphicsDevice</code>

  151.      * supports full-screen exclusive mode.

  152.      * @return whether full-screen exclusive mode is available for

  153.      * this graphics device

  154.      * @since 1.4

  155.      */

  156.     public boolean isFullScreenSupported() {

  157.         return false;

  158.     }

  159.     

  160.     /**

  161.      * Enter full-screen mode, or return to windowed mode.

  162.      * <p>

  163.      * If <code>isFullScreenSupported</code> returns <code>true</code>, full

  164.      * screen mode is considered to be <i>exclusive</i>, which implies:

  165.      * <ul>

  166.      * <li>Windows cannot overlap the full-screen window.  All other application

  167.      * windows will always appear beneath the full-screen window in the Z-order.

  168.      * <li>Input method windows are disabled.  It is advisable to call

  169.      * <code>Component.enableInputMethods(false)</code> to make a component

  170.      * a non-client of the input method framework.

  171.      * </ul>

  172.      * <p>

  173.      * If <code>isFullScreenSupported</code> returns

  174.      * <code>false</code>, full-screen exclusive mode is simulated by resizing

  175.      * the window to the size of the screen and positioning it at (0,0).

  176.      * <p>

  177.      * When entering full-screen exclusive mode, if the window to be used as the 

  178.      * full-screen window is not visible, this method will make it visible. 

  179.      * It will remain visible when returning to windowed mode.  

  180.      * <p>

  181.      * When returning to windowed mode from an exclusive full-screen window, any

  182.      * display changes made by calling <code>setDisplayMode</code> are

  183.      * automatically restored to their original state.

  184.      *

  185.      * @param w a window to use as the full-screen window; <code>null</code>

  186.      * if returning to windowed mode.  Some platforms expect the

  187.      * fullscreen window to be a top-level component (i.e., a Frame);

  188.      * therefore it is preferable to use a Frame here rather than a

  189.      * Window. 

  190.      * @see #isFullScreenSupported

  191.      * @see #getFullScreenWindow

  192.      * @see #setDisplayMode

  193.      * @see Component#enableInputMethods

  194.      * @see Component#setVisible

  195.      * @since 1.4

  196.      */

  197.     public void setFullScreenWindow(Window w) {

  198.         // Get display mode before changing the full screen window

  199.         DisplayMode dm;

  200.         if (w == null) {

  201.             dm = null;

  202.         } else {

  203.             dm = getDisplayMode();

  204.         }

  205.         if (fullScreenWindow != null && windowedModeBounds != null) {

  206.             fullScreenWindow.setBounds(windowedModeBounds);

  207. 	}

  208.         // Set the full screen window

  209.         fullScreenWindow = w;

  210.         if (fullScreenWindow != null) {

  211.             windowedModeBounds = fullScreenWindow.getBounds();

  212.             fullScreenWindow.setBounds(0, 0, dm.getWidth(), dm.getHeight());

  213.             fullScreenWindow.setVisible(true);

  214.             fullScreenWindow.toFront();

  215.         }

  216.     }

  217.     

  218.     /**

  219.      * Returns the <code>Window</code> object representing the 

  220.      * full-screen window if the device is in full-screen mode.

  221.      * 

  222.      * @return the full-screen window, or <code>null</code> if the device is

  223.      * not in full-screen mode.

  224.      * @see #setFullScreenWindow(Window)

  225.      * @since 1.4

  226.      */

  227.     public Window getFullScreenWindow() {

  228.         return fullScreenWindow;

  229.     }

  230.     

  231.     /**

  232.      * Returns <code>true</code> if this <code>GraphicsDevice</code>

  233.      * supports low-level display changes.

  234.      * @return whether low-level display changes are supported for this

  235.      * graphics device.  Note that this may or may not be dependent on

  236.      * full-screen exclusive mode.

  237.      * @see #setDisplayMode

  238.      * @since 1.4

  239.      */

  240.     public boolean isDisplayChangeSupported() {

  241.         return false;

  242.     }

  243.     

  244.     /**

  245.      * Sets the display mode of this graphics device.  This may only be allowed

  246.      * in full-screen, exclusive mode.

  247.      * @param dm the new display mode of this graphics device

  248.      * @exception IllegalArgumentException if the <code>DisplayMode</code>

  249.      * supplied is <code>null</code>, or is not available in the array returned

  250.      * by <code>getDisplayModes</code>

  251.      * @exception UnsupportedOperationException if

  252.      * <code>isDisplayChangeSupported</code> returns <code>false</code>

  253.      * @see #getDisplayMode

  254.      * @see #getDisplayModes

  255.      * @see #isDisplayChangeSupported

  256.      * @since 1.4

  257.      */

  258.     public void setDisplayMode(DisplayMode dm) {

  259.         throw new UnsupportedOperationException("Cannot change display mode");

  260.     }

  261.     

  262.     /**

  263.      * Returns the current display mode of this 

  264.      * <code>GraphicsDevice</code>.

  265.      * @return the current display mode of this graphics device.

  266.      * @see #setDisplayMode(DisplayMode)

  267.      * @since 1.4

  268.      */

  269.     public DisplayMode getDisplayMode() {

  270.         GraphicsConfiguration gc = getDefaultConfiguration();

  271.         Rectangle r = gc.getBounds();

  272.         ColorModel cm = gc.getColorModel();

  273.         return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);

  274.     }

  275.     

  276.     /**

  277.      * Returns all display modes available for this      

  278.      * <code>GraphicsDevice</code>.

  279.      * @return all of the display modes available for this graphics device.

  280.      * @since 1.4

  281.      */

  282.     public DisplayMode[] getDisplayModes() {

  283.         return new DisplayMode[] { getDisplayMode() };

  284.     }

  285. 

  286.     /**

  287.      * This method returns the number of bytes available in

  288.      * accelerated memory on this device.

  289.      * Some images are created or cached

  290.      * in accelerated memory on a first-come,

  291.      * first-served basis.  On some operating systems,

  292.      * this memory is a finite resource.  Calling this method

  293.      * and scheduling the creation and flushing of images carefully may

  294.      * enable applications to make the most efficient use of

  295.      * that finite resource.

  296.      * <br>

  297.      * Note that the number returned is a snapshot of how much

  298.      * memory is available; some images may still have problems

  299.      * being allocated into that memory.  For example, depending

  300.      * on operating system, driver, memory configuration, and

  301.      * thread situations, the full extent of the size reported

  302.      * may not be available for a given image.  There are further

  303.      * inquiry methods on the {@link ImageCapabilities} object

  304.      * associated with a VolatileImage that can be used to determine

  305.      * whether a particular VolatileImage has been created in accelerated

  306.      * memory.

  307.      * @return number of bytes available in accelerated memory.

  308.      * A negative return value indicates that accelerated memory

  309.      * is unlimited.

  310.      * @see java.awt.image.VolatileImage#flush

  311.      * @see ImageCapabilities#isAccelerated

  312.      */

  313.     public int getAvailableAcceleratedMemory() {

  314. 	return -1;

  315.     }

  316. }