1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt;
  27 
  28 import java.awt.geom.AffineTransform;
  29 import java.awt.image.BufferedImage;
  30 import java.awt.image.ColorModel;
  31 import java.awt.image.VolatileImage;
  32 import java.awt.image.WritableRaster;
  33 
  34 import sun.awt.image.SunVolatileImage;
  35 
  36 /**
  37  * The <code>GraphicsConfiguration</code> class describes the
  38  * characteristics of a graphics destination such as a printer or monitor.
  39  * There can be many <code>GraphicsConfiguration</code> objects associated
  40  * with a single graphics device, representing different drawing modes or
  41  * capabilities.  The corresponding native structure will vary from platform
  42  * to platform.  For example, on X11 windowing systems,
  43  * each visual is a different <code>GraphicsConfiguration</code>.
  44  * On Microsoft Windows, <code>GraphicsConfiguration</code>s represent
  45  * PixelFormats available in the current resolution and color depth.
  46  * <p>
  47  * In a virtual device multi-screen environment in which the desktop
  48  * area could span multiple physical screen devices, the bounds of the
  49  * <code>GraphicsConfiguration</code> objects are relative to the
  50  * virtual coordinate system.  When setting the location of a
  51  * component, use {@link #getBounds() getBounds} to get the bounds of
  52  * the desired <code>GraphicsConfiguration</code> and offset the location
  53  * with the coordinates of the <code>GraphicsConfiguration</code>,
  54  * as the following code sample illustrates:
  55  * </p>
  56  *
  57  * <pre>
  58  *      Frame f = new Frame(gc);  // where gc is a GraphicsConfiguration
  59  *      Rectangle bounds = gc.getBounds();
  60  *      f.setLocation(10 + bounds.x, 10 + bounds.y); </pre>
  61  *
  62  * <p>
  63  * To determine if your environment is a virtual device
  64  * environment, call <code>getBounds</code> on all of the
  65  * <code>GraphicsConfiguration</code> objects in your system.  If
  66  * any of the origins of the returned bounds is not (0,&nbsp;0),
  67  * your environment is a virtual device environment.
  68  *
  69  * <p>
  70  * You can also use <code>getBounds</code> to determine the bounds
  71  * of the virtual device.  To do this, first call <code>getBounds</code> on all
  72  * of the <code>GraphicsConfiguration</code> objects in your
  73  * system.  Then calculate the union of all of the bounds returned
  74  * from the calls to <code>getBounds</code>.  The union is the
  75  * bounds of the virtual device.  The following code sample
  76  * calculates the bounds of the virtual device.
  77  *
  78  * <pre>{@code
  79  *      Rectangle virtualBounds = new Rectangle();
  80  *      GraphicsEnvironment ge = GraphicsEnvironment.
  81  *              getLocalGraphicsEnvironment();
  82  *      GraphicsDevice[] gs =
  83  *              ge.getScreenDevices();
  84  *      for (int j = 0; j < gs.length; j++) {
  85  *          GraphicsDevice gd = gs[j];
  86  *          GraphicsConfiguration[] gc =
  87  *              gd.getConfigurations();
  88  *          for (int i=0; i < gc.length; i++) {
  89  *              virtualBounds =
  90  *                  virtualBounds.union(gc[i].getBounds());
  91  *          }
  92  *      } }</pre>
  93  *
  94  * @see Window
  95  * @see Frame
  96  * @see GraphicsEnvironment
  97  * @see GraphicsDevice
  98  */
  99 /*
 100  * REMIND:  What to do about capabilities?
 101  * The
 102  * capabilities of the device can be determined by enumerating the possible
 103  * capabilities and checking if the GraphicsConfiguration
 104  * implements the interface for that capability.
 105  *
 106  */
 107 
 108 
 109 public abstract class GraphicsConfiguration {
 110 
 111     private static BufferCapabilities defaultBufferCaps;
 112     private static ImageCapabilities defaultImageCaps;
 113 
 114     /**
 115      * This is an abstract class that cannot be instantiated directly.
 116      * Instances must be obtained from a suitable factory or query method.
 117      *
 118      * @see GraphicsDevice#getConfigurations
 119      * @see GraphicsDevice#getDefaultConfiguration
 120      * @see GraphicsDevice#getBestConfiguration
 121      * @see Graphics2D#getDeviceConfiguration
 122      */
 123     protected GraphicsConfiguration() {
 124     }
 125 
 126     /**
 127      * Returns the {@link GraphicsDevice} associated with this
 128      * <code>GraphicsConfiguration</code>.
 129      * @return a <code>GraphicsDevice</code> object that is
 130      * associated with this <code>GraphicsConfiguration</code>.
 131      */
 132     public abstract GraphicsDevice getDevice();
 133 
 134     /**
 135      * Returns a {@link BufferedImage} with a data layout and color model
 136      * compatible with this <code>GraphicsConfiguration</code>.  This
 137      * method has nothing to do with memory-mapping
 138      * a device.  The returned <code>BufferedImage</code> has
 139      * a layout and color model that is closest to this native device
 140      * configuration and can therefore be optimally blitted to this
 141      * device.
 142      * @param width the width of the returned <code>BufferedImage</code>
 143      * @param height the height of the returned <code>BufferedImage</code>
 144      * @return a <code>BufferedImage</code> whose data layout and color
 145      * model is compatible with this <code>GraphicsConfiguration</code>.
 146      */
 147     public BufferedImage createCompatibleImage(int width, int height) {
 148         ColorModel model = getColorModel();
 149         WritableRaster raster =
 150             model.createCompatibleWritableRaster(width, height);
 151         return new BufferedImage(model, raster,
 152                                  model.isAlphaPremultiplied(), null);
 153     }
 154 
 155     /**
 156      * Returns a <code>BufferedImage</code> that supports the specified
 157      * transparency and has a data layout and color model
 158      * compatible with this <code>GraphicsConfiguration</code>.  This
 159      * method has nothing to do with memory-mapping
 160      * a device. The returned <code>BufferedImage</code> has a layout and
 161      * color model that can be optimally blitted to a device
 162      * with this <code>GraphicsConfiguration</code>.
 163      * @param width the width of the returned <code>BufferedImage</code>
 164      * @param height the height of the returned <code>BufferedImage</code>
 165      * @param transparency the specified transparency mode
 166      * @return a <code>BufferedImage</code> whose data layout and color
 167      * model is compatible with this <code>GraphicsConfiguration</code>
 168      * and also supports the specified transparency.
 169      * @throws IllegalArgumentException if the transparency is not a valid value
 170      * @see Transparency#OPAQUE
 171      * @see Transparency#BITMASK
 172      * @see Transparency#TRANSLUCENT
 173      */
 174     public BufferedImage createCompatibleImage(int width, int height,
 175                                                int transparency)
 176     {
 177         if (getColorModel().getTransparency() == transparency) {
 178             return createCompatibleImage(width, height);
 179         }
 180 
 181         ColorModel cm = getColorModel(transparency);
 182         if (cm == null) {
 183             throw new IllegalArgumentException("Unknown transparency: " +
 184                                                transparency);
 185         }
 186         WritableRaster wr = cm.createCompatibleWritableRaster(width, height);
 187         return new BufferedImage(cm, wr, cm.isAlphaPremultiplied(), null);
 188     }
 189 
 190 
 191     /**
 192      * Returns a {@link VolatileImage} with a data layout and color model
 193      * compatible with this <code>GraphicsConfiguration</code>.
 194      * The returned <code>VolatileImage</code>
 195      * may have data that is stored optimally for the underlying graphics
 196      * device and may therefore benefit from platform-specific rendering
 197      * acceleration.
 198      * @param width the width of the returned <code>VolatileImage</code>
 199      * @param height the height of the returned <code>VolatileImage</code>
 200      * @return a <code>VolatileImage</code> whose data layout and color
 201      * model is compatible with this <code>GraphicsConfiguration</code>.
 202      * @see Component#createVolatileImage(int, int)
 203      * @since 1.4
 204      */
 205     public VolatileImage createCompatibleVolatileImage(int width, int height) {
 206         VolatileImage vi = null;
 207         try {
 208             vi = createCompatibleVolatileImage(width, height,
 209                                                null, Transparency.OPAQUE);
 210         } catch (AWTException e) {
 211             // shouldn't happen: we're passing in null caps
 212             assert false;
 213         }
 214         return vi;
 215     }
 216 
 217     /**
 218      * Returns a {@link VolatileImage} with a data layout and color model
 219      * compatible with this <code>GraphicsConfiguration</code>.
 220      * The returned <code>VolatileImage</code>
 221      * may have data that is stored optimally for the underlying graphics
 222      * device and may therefore benefit from platform-specific rendering
 223      * acceleration.
 224      * @param width the width of the returned <code>VolatileImage</code>
 225      * @param height the height of the returned <code>VolatileImage</code>
 226      * @param transparency the specified transparency mode
 227      * @return a <code>VolatileImage</code> whose data layout and color
 228      * model is compatible with this <code>GraphicsConfiguration</code>.
 229      * @throws IllegalArgumentException if the transparency is not a valid value
 230      * @see Transparency#OPAQUE
 231      * @see Transparency#BITMASK
 232      * @see Transparency#TRANSLUCENT
 233      * @see Component#createVolatileImage(int, int)
 234      * @since 1.5
 235      */
 236     public VolatileImage createCompatibleVolatileImage(int width, int height,
 237                                                        int transparency)
 238     {
 239         VolatileImage vi = null;
 240         try {
 241             vi = createCompatibleVolatileImage(width, height, null, transparency);
 242         } catch (AWTException e) {
 243             // shouldn't happen: we're passing in null caps
 244             assert false;
 245         }
 246         return vi;
 247     }
 248 
 249     /**
 250      * Returns a {@link VolatileImage} with a data layout and color model
 251      * compatible with this <code>GraphicsConfiguration</code>, using
 252      * the specified image capabilities.
 253      * If the <code>caps</code> parameter is null, it is effectively ignored
 254      * and this method will create a VolatileImage without regard to
 255      * <code>ImageCapabilities</code> constraints.
 256      *
 257      * The returned <code>VolatileImage</code> has
 258      * a layout and color model that is closest to this native device
 259      * configuration and can therefore be optimally blitted to this
 260      * device.
 261      * @return a <code>VolatileImage</code> whose data layout and color
 262      * model is compatible with this <code>GraphicsConfiguration</code>.
 263      * @param width the width of the returned <code>VolatileImage</code>
 264      * @param height the height of the returned <code>VolatileImage</code>
 265      * @param caps the image capabilities
 266      * @exception AWTException if the supplied image capabilities could not
 267      * be met by this graphics configuration
 268      * @since 1.4
 269      */
 270     public VolatileImage createCompatibleVolatileImage(int width, int height,
 271         ImageCapabilities caps) throws AWTException
 272     {
 273         return createCompatibleVolatileImage(width, height, caps,
 274                                              Transparency.OPAQUE);
 275     }
 276 
 277     /**
 278      * Returns a {@link VolatileImage} with a data layout and color model
 279      * compatible with this <code>GraphicsConfiguration</code>, using
 280      * the specified image capabilities and transparency value.
 281      * If the <code>caps</code> parameter is null, it is effectively ignored
 282      * and this method will create a VolatileImage without regard to
 283      * <code>ImageCapabilities</code> constraints.
 284      *
 285      * The returned <code>VolatileImage</code> has
 286      * a layout and color model that is closest to this native device
 287      * configuration and can therefore be optimally blitted to this
 288      * device.
 289      * @param width the width of the returned <code>VolatileImage</code>
 290      * @param height the height of the returned <code>VolatileImage</code>
 291      * @param caps the image capabilities
 292      * @param transparency the specified transparency mode
 293      * @return a <code>VolatileImage</code> whose data layout and color
 294      * model is compatible with this <code>GraphicsConfiguration</code>.
 295      * @see Transparency#OPAQUE
 296      * @see Transparency#BITMASK
 297      * @see Transparency#TRANSLUCENT
 298      * @throws IllegalArgumentException if the transparency is not a valid value
 299      * @exception AWTException if the supplied image capabilities could not
 300      * be met by this graphics configuration
 301      * @see Component#createVolatileImage(int, int)
 302      * @since 1.5
 303      */
 304     public VolatileImage createCompatibleVolatileImage(int width, int height,
 305         ImageCapabilities caps, int transparency) throws AWTException
 306     {
 307         VolatileImage vi =
 308             new SunVolatileImage(this, width, height, transparency, caps);
 309         if (caps != null && caps.isAccelerated() &&
 310             !vi.getCapabilities().isAccelerated())
 311         {
 312             throw new AWTException("Supplied image capabilities could not " +
 313                                    "be met by this graphics configuration.");
 314         }
 315         return vi;
 316     }
 317 
 318     /**
 319      * Returns the {@link ColorModel} associated with this
 320      * <code>GraphicsConfiguration</code>.
 321      * @return a <code>ColorModel</code> object that is associated with
 322      * this <code>GraphicsConfiguration</code>.
 323      */
 324     public abstract ColorModel getColorModel();
 325 
 326     /**
 327      * Returns the <code>ColorModel</code> associated with this
 328      * <code>GraphicsConfiguration</code> that supports the specified
 329      * transparency.
 330      * @param transparency the specified transparency mode
 331      * @return a <code>ColorModel</code> object that is associated with
 332      * this <code>GraphicsConfiguration</code> and supports the
 333      * specified transparency or null if the transparency is not a valid
 334      * value.
 335      * @see Transparency#OPAQUE
 336      * @see Transparency#BITMASK
 337      * @see Transparency#TRANSLUCENT
 338      */
 339     public abstract ColorModel getColorModel(int transparency);
 340 
 341     /**
 342      * Returns the default {@link AffineTransform} for this
 343      * <code>GraphicsConfiguration</code>. This
 344      * <code>AffineTransform</code> is typically the Identity transform
 345      * for most normal screens.  The default <code>AffineTransform</code>
 346      * maps coordinates onto the device such that 72 user space
 347      * coordinate units measure approximately 1 inch in device
 348      * space.  The normalizing transform can be used to make
 349      * this mapping more exact.  Coordinates in the coordinate space
 350      * defined by the default <code>AffineTransform</code> for screen and
 351      * printer devices have the origin in the upper left-hand corner of
 352      * the target region of the device, with X coordinates
 353      * increasing to the right and Y coordinates increasing downwards.
 354      * For image buffers not associated with a device, such as those not
 355      * created by <code>createCompatibleImage</code>,
 356      * this <code>AffineTransform</code> is the Identity transform.
 357      * @return the default <code>AffineTransform</code> for this
 358      * <code>GraphicsConfiguration</code>.
 359      */
 360     public abstract AffineTransform getDefaultTransform();
 361 
 362     /**
 363      *
 364      * Returns a <code>AffineTransform</code> that can be concatenated
 365      * with the default <code>AffineTransform</code>
 366      * of a <code>GraphicsConfiguration</code> so that 72 units in user
 367      * space equals 1 inch in device space.
 368      * <p>
 369      * For a particular {@link Graphics2D}, g, one
 370      * can reset the transformation to create
 371      * such a mapping by using the following pseudocode:
 372      * <pre>
 373      *      GraphicsConfiguration gc = g.getDeviceConfiguration();
 374      *
 375      *      g.setTransform(gc.getDefaultTransform());
 376      *      g.transform(gc.getNormalizingTransform());
 377      * </pre>
 378      * Note that sometimes this <code>AffineTransform</code> is identity,
 379      * such as for printers or metafile output, and that this
 380      * <code>AffineTransform</code> is only as accurate as the information
 381      * supplied by the underlying system.  For image buffers not
 382      * associated with a device, such as those not created by
 383      * <code>createCompatibleImage</code>, this
 384      * <code>AffineTransform</code> is the Identity transform
 385      * since there is no valid distance measurement.
 386      * @return an <code>AffineTransform</code> to concatenate to the
 387      * default <code>AffineTransform</code> so that 72 units in user
 388      * space is mapped to 1 inch in device space.
 389      */
 390     public abstract AffineTransform getNormalizingTransform();
 391 
 392     /**
 393      * Returns the bounds of the <code>GraphicsConfiguration</code>
 394      * in the device coordinates. In a multi-screen environment
 395      * with a virtual device, the bounds can have negative X
 396      * or Y origins.
 397      * @return the bounds of the area covered by this
 398      * <code>GraphicsConfiguration</code>.
 399      * @since 1.3
 400      */
 401     public abstract Rectangle getBounds();
 402 
 403     private static class DefaultBufferCapabilities extends BufferCapabilities {
 404         public DefaultBufferCapabilities(ImageCapabilities imageCaps) {
 405             super(imageCaps, imageCaps, null);
 406         }
 407     }
 408 
 409     /**
 410      * Returns the buffering capabilities of this
 411      * <code>GraphicsConfiguration</code>.
 412      * @return the buffering capabilities of this graphics
 413      * configuration object
 414      * @since 1.4
 415      */
 416     public BufferCapabilities getBufferCapabilities() {
 417         if (defaultBufferCaps == null) {
 418             defaultBufferCaps = new DefaultBufferCapabilities(
 419                 getImageCapabilities());
 420         }
 421         return defaultBufferCaps;
 422     }
 423 
 424     /**
 425      * Returns the image capabilities of this
 426      * <code>GraphicsConfiguration</code>.
 427      * @return the image capabilities of this graphics
 428      * configuration object
 429      * @since 1.4
 430      */
 431     public ImageCapabilities getImageCapabilities() {
 432         if (defaultImageCaps == null) {
 433             defaultImageCaps = new ImageCapabilities(false);
 434         }
 435         return defaultImageCaps;
 436     }
 437 
 438     /**
 439      * Returns whether this {@code GraphicsConfiguration} supports
 440      * the {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT
 441      * PERPIXEL_TRANSLUCENT} kind of translucency.
 442      *
 443      * @return whether the given GraphicsConfiguration supports
 444      *         the translucency effects.
 445      *
 446      * @see Window#setBackground(Color)
 447      *
 448      * @since 1.7
 449      */
 450     public boolean isTranslucencyCapable() {
 451         // Overridden in subclasses
 452         return false;
 453     }
 454 }
--- EOF ---