1. /*

  2.  * @(#)GraphicsConfiguration.java	1.28 01/02/09

  3.  *

  4.  * Copyright 1997-2001 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.awt;

  12. 

  13. import java.awt.geom.AffineTransform;

  14. import java.awt.image.BufferedImage;

  15. import java.awt.image.ColorModel;

  16. 

  17. /**

  18.  * The <code>GraphicsConfiguration</code> class describes the

  19.  * characteristics of a graphics destination such as a printer or monitor.

  20.  * There can be many <code>GraphicsConfiguration</code> objects associated

  21.  * with a single graphics device, representing different drawing modes or

  22.  * capabilities.  The corresponding native structure will vary from platform

  23.  * to platform.  For example, on X11 windowing systems,

  24.  * each visual is a different <code>GraphicsConfiguration</code>.  

  25.  * On win32, <code>GraphicsConfiguration</code>s represent PixelFormats 

  26.  * available in the current resolution and color depth. 

  27.  * <p>

  28.  * In a virtual device multi-screen environment in which the desktop

  29.  * area could span multiple physical screen devices, the bounds of the 

  30.  * <code>GraphicsConfiguration</code> objects are relative to the

  31.  * virtual coordinate system.  When setting the location of a 

  32.  * component, use {@link #getBounds() getBounds} to get the bounds of 

  33.  * the desired <code>GraphicsConfiguration</code> and offset the location

  34.  * with the coordinates of the <code>GraphicsConfiguration</code>,

  35.  * as the following code sample illustrates:

  36.  * <pre>

  37.  *      Frame f = new Frame(GraphicsConfiguration gc);

  38.  *      Rectangle bounds = gc.getBounds();

  39.  *      f.setLocation(10 + bounds.x, 10 + bounds.y);

  40.  * </pre>

  41.  * To determine if your environment is a virtual device

  42.  * environment, call <code>getBounds</code> on all of the 

  43.  * <code>GraphicsConfiguration</code> objects in your system.  If 

  44.  * any of the origins of the returned bounds are not (0, 0),

  45.  * your environment is a virtual device environment.

  46.  * <p>

  47.  * You can also use <code>getBounds</code> to determine the bounds

  48.  * of the virtual device.  Call <code>getBounds</code> on all

  49.  * of the <code>GraphicsConfiguration</code> objects in your

  50.  * system.  Then, calculate the union of all of the bounds returned

  51.  * from the calls to <code>getBounds</code>.  The union is the

  52.  * bounds of the virtual device.  The following code sample

  53.  * calculates the bounds of the virtual device.

  54.  * <pre>

  55.  *	Rectangle virtualBounds = new Rectangle();

  56.  *      GraphicsEnvironment ge = GraphicsEnvironment.

  57.  *		getLocalGraphicsEnvironment();

  58.  *	GraphicsDevice[] gs =

  59.  *		ge.getScreenDevices();

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

  61.  *	   GraphicsDevice gd = gs[j];

  62.  *	   GraphicsConfiguration[] gc =

  63.  *	      gd.getConfigurations();

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

  65.  *	      virtualBounds =

  66.  *		virtualBounds.union(gc[i].getBounds());

  67.  *	   }

  68.  *      }

  69.  * </pre>                   

  70.  * @see Window

  71.  * @see Frame

  72.  * @see GraphicsEnvironment

  73.  * @see GraphicsDevice

  74.  */

  75. /*

  76.  * REMIND:  What to do about capabilities?

  77.  * The

  78.  * capabilities of the device can be determined by enumerating the possible

  79.  * capabilities and checking if the GraphicsConfiguration

  80.  * implements the interface for that capability.

  81.  *

  82.  * @version 1.28, 02/09/01

  83.  */

  84. 

  85. 

  86. public abstract class GraphicsConfiguration {

  87.     /**

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

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

  90.      *

  91.      * @see GraphicsDevice#getConfigurations

  92.      * @see GraphicsDevice#getDefaultConfiguration

  93.      * @see GraphicsDevice#getBestConfiguration

  94.      * @see Graphics2D#getDeviceConfiguration

  95.      */

  96.     protected GraphicsConfiguration() {

  97.     }

  98. 

  99.     /**

  100.      * Returns the {@link GraphicsDevice} associated with this

  101.      * <code>GraphicsConfiguration</code>.

  102.      * @return a <code>GraphicsDevice</code> object that is 

  103.      * associated with this <code>GraphicsConfiguration</code>.

  104.      */

  105.     public abstract GraphicsDevice getDevice();

  106. 

  107.     /**

  108.      * Returns a {@link BufferedImage} with a data layout and color model

  109.      * compatible with this <code>GraphicsConfiguration</code>.  This

  110.      * method has nothing to do with memory-mapping

  111.      * a device.  The returned <code>BufferedImage</code> has

  112.      * a layout and color model that is closest to this native device

  113.      * configuration and can therefore be optimally blitted to this

  114.      * device.

  115.      * @param width the width of the returned <code>BufferedImage</code>

  116.      * @param height the height of the returned <code>BufferedImage</code>

  117.      * @return a <code>BufferedImage</code> whose data layout and color

  118.      * model is compatible with this <code>GraphicsConfiguration</code>.

  119.      */

  120.     public abstract BufferedImage createCompatibleImage(int width, int height);

  121. 

  122.     /**

  123.      * Returns a <code>BufferedImage</code> that supports the specified

  124.      * transparency and has a data layout and color model

  125.      * compatible with this <code>GraphicsConfiguration</code>.  This

  126.      * method has nothing to do with memory-mapping

  127.      * a device. The returned <code>BufferedImage</code> has a layout and

  128.      * color model that can be optimally blitted to a device

  129.      * with this <code>GraphicsConfiguration</code>.

  130.      * @param width the width of the returned <code>BufferedImage</code>

  131.      * @param height the height of the returned <code>BufferedImage</code>

  132.      * @param transparency the specified transparency mode

  133.      * @return a <code>BufferedImage</code> whose data layout and color  

  134.      * model is compatible with this <code>GraphicsConfiguration</code>

  135.      * and also supports the specified transparency.

  136.      * @see Transparency#OPAQUE

  137.      * @see Transparency#BITMASK

  138.      * @see Transparency#TRANSLUCENT

  139.      */

  140.     public abstract BufferedImage createCompatibleImage(int width, int height,

  141.                                                         int transparency);

  142. 

  143.     /**

  144.      * Returns the {@link ColorModel} associated with this 

  145.      * <code>GraphicsConfiguration</code>.

  146.      * @return a <code>ColorModel</code> object that is associated with

  147.      * this <code>GraphicsConfiguration</code>.

  148.      */

  149.     public abstract ColorModel getColorModel();

  150. 

  151.     /**

  152.      * Returns the <code>ColorModel</code> associated with this

  153.      * <code>GraphicsConfiguration</code> that supports the specified

  154.      * transparency.

  155.      * @param transparency the specified transparency mode

  156.      * @return a <code>ColorModel</code> object that is associated with

  157.      * this <code>GraphicsConfiguration</code> and supports the 

  158.      * specified transparency.

  159.      */

  160.     public abstract ColorModel getColorModel(int transparency);

  161. 

  162.     /**

  163.      * Returns the default {@link AffineTransform} for this 

  164.      * <code>GraphicsConfiguration</code>. This

  165.      * <code>AffineTransform</code> is typically the Identity transform

  166.      * for most normal screens.  The default <code>AffineTransform</code>

  167.      * maps coordinates onto the device such that 72 user space

  168.      * coordinate units measure approximately 1 inch in device

  169.      * space.  The normalizing transform can be used to make

  170.      * this mapping more exact.  Coordinates in the coordinate space

  171.      * defined by the default <code>AffineTransform</code> for screen and

  172.      * printer devices have the origin in the upper left-hand corner of

  173.      * the target region of the device, with X coordinates

  174.      * increasing to the right and Y coordinates increasing downwards.

  175.      * For image buffers not associated with a device, such as those not

  176.      * created by <code>createCompatibleImage</code>,

  177.      * this <code>AffineTransform</code> is the Identity transform.

  178.      * @return the default <code>AffineTransform</code> for this

  179.      * <code>GraphicsConfiguration</code>.

  180.      */

  181.     public abstract AffineTransform getDefaultTransform();

  182. 

  183.     /**

  184.      *

  185.      * Returns a <code>AffineTransform</code> that can be concatenated

  186.      * with the default <code>AffineTransform</code>

  187.      * of a <code>GraphicsConfiguration</code> so that 72 units in user

  188.      * space equals 1 inch in device space.  

  189.      * <p>

  190.      * For a particular {@link Graphics2D}, g, one

  191.      * can reset the transformation to create

  192.      * such a mapping by using the following pseudocode:

  193.      * <pre>

  194.      *      GraphicsConfiguration gc = g.getGraphicsConfiguration();

  195.      *

  196.      *      g.setTransform(gc.getDefaultTransform());

  197.      *      g.transform(gc.getNormalizingTransform());

  198.      * </pre>

  199.      * Note that sometimes this <code>AffineTransform</code> is identity,

  200.      * such as for printers or metafile output, and that this 

  201.      * <code>AffineTransform</code> is only as accurate as the information

  202.      * supplied by the underlying system.  For image buffers not

  203.      * associated with a device, such as those not created by

  204.      * <code>createCompatibleImage</code>, this

  205.      * <code>AffineTransform</code> is the Identity transform

  206.      * since there is no valid distance measurement.

  207.      * @return an <code>AffineTransform</code> to concatenate to the

  208.      * default <code>AffineTransform</code> so that 72 units in user

  209.      * space is mapped to 1 inch in device space.

  210.      */

  211.     public abstract AffineTransform getNormalizingTransform();

  212. 

  213.     /**

  214.      * Returns the bounds of the <code>GraphicsConfiguration</code>

  215.      * in the device coordinates. In a multi-screen environment

  216.      * with a virtual device, the bounds can have negative X

  217.      * or Y origins.

  218.      * @return the bounds of the area covered by this

  219.      * <code>GraphicsConfiguration</code>.

  220.      * @since 1.3

  221.      */

  222.     public abstract Rectangle getBounds();

  223.     

  224.     }

  225. 

  226.