libjava/classpath/java/awt/GraphicsConfiguration.java

   1 /* GraphicsConfiguration.java -- describes characteristics of graphics
   2    Copyright (C) 2000, 2001, 2002 Free Software Foundation
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import gnu.classpath.NotImplementedException;
  42
  43 import java.awt.geom.AffineTransform;
  44 import java.awt.image.BufferedImage;
  45 import java.awt.image.ColorModel;
  46 import java.awt.image.VolatileImage;
  47
  48 /**
  49  * This class describes the configuration of various graphics devices, such
  50  * as a monitor or printer. Different configurations may exist for the same
  51  * device, according to the different native modes supported.
  52  *
  53  * <p>Virtual devices are supported (for example, in a multiple screen
  54  * environment, a virtual device covers all screens simultaneously); the
  55  * configuration will have a non-zero relative coordinate system in such
  56  * a case.
  57  *
  58  * @author Eric Blake (ebb9@email.byu.edu)
  59  * @see Window
  60  * @see Frame
  61  * @see GraphicsEnvironment
  62  * @see GraphicsDevice
  63  * @since 1.0
  64  * @status updated to 1.4
  65  */
  66 public abstract class GraphicsConfiguration
  67 {
  68
  69   /** The cached image capabilities. */
  70   private ImageCapabilities imageCapabilities;
  71
  72   /** The cached buffer capabilities. */
  73   private BufferCapabilities bufferCapabilities;
  74
  75   /**
  76    * The default constructor.
  77    *
  78    * @see GraphicsDevice#getConfigurations()
  79    * @see GraphicsDevice#getDefaultConfiguration()
  80    * @see GraphicsDevice#getBestConfiguration(GraphicsConfigTemplate)
  81    * @see Graphics2D#getDeviceConfiguration()
  82    */
  83   protected GraphicsConfiguration ()
  84   {
  85   }
  86
  87   /**
  88    * Gets the associated device that this configuration describes.
  89    *
  90    * @return the device
  91    */
  92   public abstract GraphicsDevice getDevice();
  93
  94   /**
  95    * Returns a buffered image optimized to this device, so that blitting can
  96    * be supported in the buffered image.
  97    *
  98    * @param w the width of the buffer
  99    * @param h the height of the buffer
 100    * @return the buffered image, or null if none is supported
 101    */
 102   public abstract BufferedImage createCompatibleImage(int w, int h);
 103
 104   /**
 105    * Returns a buffered volatile image optimized to this device, so that
 106    * blitting can be supported in the buffered image. Because the buffer is
 107    * volatile, it can be optimized by native graphics accelerators.
 108    *
 109    * @param w the width of the buffer
 110    * @param h the height of the buffer
 111    * @return the buffered image, or null if none is supported
 112    * @see Component#createVolatileImage(int, int)
 113    * @since 1.4
 114    */
 115   public abstract VolatileImage createCompatibleVolatileImage(int w, int h);
 116
 117   /**
 118    * Returns a buffered volatile image optimized to this device, and with the
 119    * given capabilities, so that blitting can be supported in the buffered
 120    * image. Because the buffer is volatile, it can be optimized by native
 121    * graphics accelerators.
 122    *
 123    * @param w the width of the buffer
 124    * @param h the height of the buffer
 125    * @param caps the desired capabilities of the image buffer
 126    * @return the buffered image, or null if none is supported
 127    * @throws AWTException if the capabilities cannot be met
 128    * @since 1.4
 129    */
 130   public VolatileImage createCompatibleVolatileImage(int w, int h,
 131                                                      ImageCapabilities caps)
 132     throws AWTException
 133   {
 134     throw new AWTException("not implemented");
 135   }
 136
 137   /**
 138    * Returns a buffered volatile image optimized to this device, and
 139    * with the given transparency. Because the buffer is volatile, it
 140    * can be optimized by native graphics accelerators.
 141    *
 142    * @param width the width of the buffer
 143    * @param height the height of the buffer
 144    * @param transparency the transparency value for the buffer
 145    * @return the buffered image, or null if none is supported
 146    * @since 1.5
 147    */
 148   public abstract VolatileImage createCompatibleVolatileImage(int width,
 149                                                               int height,
 150                                                               int transparency);
 151
 152   /**
 153    * Returns a buffered image optimized to this device, and with the specified
 154    * transparency, so that blitting can be supported in the buffered image.
 155    *
 156    * @param w the width of the buffer
 157    * @param h the height of the buffer
 158    * @param transparency the transparency of the buffer
 159    * @return the buffered image, or null if none is supported
 160    * @see Transparency#OPAQUE
 161    * @see Transparency#BITMASK
 162    * @see Transparency#TRANSLUCENT
 163    */
 164   public abstract BufferedImage createCompatibleImage(int w, int h,
 165                                                       int transparency);
 166
 167   /**
 168    * Gets the color model of the corresponding device.
 169    *
 170    * @return the color model
 171    */
 172   public abstract ColorModel getColorModel();
 173
 174   /**
 175    * Gets a color model for the corresponding device which supports the desired
 176    * transparency level.
 177    *
 178    * @param transparency the transparency of the model
 179    * @return the color model, with transparency
 180    * @see Transparency#OPAQUE
 181    * @see Transparency#BITMASK
 182    * @see Transparency#TRANSLUCENT
 183    */
 184   public abstract ColorModel getColorModel(int transparency);
 185
 186   /**
 187    * Returns a transform that maps user coordinates to device coordinates. The
 188    * preferred mapping is about 72 user units to 1 inch (2.54 cm) of physical
 189    * space. This is often the identity transform. The device coordinates have
 190    * the origin at the upper left, with increasing x to the right, and
 191    * increasing y to the bottom.
 192    *
 193    * @return the transformation from user space to device space
 194    * @see #getNormalizingTransform()
 195    */
 196   public abstract AffineTransform getDefaultTransform();
 197
 198   /**
 199    * Returns a transform that maps user coordinates to device coordinates. The
 200    * exact mapping is 72 user units to 1 inch (2.54 cm) of physical space.
 201    * This is often the identity transform. The device coordinates have the
 202    * origin at the upper left, with increasing x to the right, and increasing
 203    * y to the bottom. Note that this is more accurate (and thus, sometimes more
 204    * costly) than the default transform.
 205    *
 206    * @return the normalized transformation from user space to device space
 207    * @see #getDefaultTransform()
 208    */
 209   public abstract AffineTransform getNormalizingTransform();
 210
 211   /**
 212    * Returns the bounds of the configuration, in device coordinates. If this
 213    * is a virtual device (for example, encompassing several screens), the
 214    * bounds may have a non-zero origin.
 215    *
 216    * @return the device bounds
 217    * @since 1.3
 218    */
 219   public abstract Rectangle getBounds();
 220
 221   /**
 222    * Returns the buffering capabilities of this configuration.
 223    *
 224    * @return the buffer capabilities
 225    * @since 1.4
 226    */
 227   public BufferCapabilities getBufferCapabilities()
 228   {
 229     if (imageCapabilities == null)
 230       getImageCapabilities();
 231
 232     if (bufferCapabilities == null)
 233       bufferCapabilities = new BufferCapabilities(imageCapabilities,
 234                                                   imageCapabilities, null);
 235     return bufferCapabilities;
 236   }
 237
 238   /**
 239    * Returns the imaging capabilities of this configuration.
 240    *
 241    * @return the image capabilities
 242    * @since 1.4
 243    */
 244   public ImageCapabilities getImageCapabilities()
 245   {
 246     if (imageCapabilities == null)
 247       imageCapabilities = new ImageCapabilities(false);
 248     return imageCapabilities;
 249   }
 250 } // class GraphicsConfiguration