/*

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

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.awt;

import java.awt.geom.AffineTransform;

import java.awt.image.BufferedImage;

import java.awt.image.ColorModel;

import java.awt.image.VolatileImage;

import java.awt.image.WritableRaster;

import sun.awt.image.SunVolatileImage;

/**

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

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

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

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

 * capabilities.  The corresponding native structure will vary from platform

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

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

 * On Microsoft Windows, <code>GraphicsConfiguration</code>s represent

 * PixelFormats available in the current resolution and color depth.

 * <p>

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

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

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

 * virtual coordinate system.  When setting the location of a

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

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

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

 * as the following code sample illustrates:

 * </p>

 *

 * <pre>

 *      Frame f = new Frame(gc);  // where gc is a GraphicsConfiguration

 *      Rectangle bounds = gc.getBounds();

 *      f.setLocation(10 + bounds.x, 10 + bounds.y); </pre>

 *

 * <p>

 * To determine if your environment is a virtual device

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

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

 * any of the origins of the returned bounds is not (0, 0),

 * your environment is a virtual device environment.

 *

 * <p>

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

 * of the virtual device.  To do this, first call <code>getBounds</code> on all

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

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

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

 * bounds of the virtual device.  The following code sample

 * calculates the bounds of the virtual device.

 *

 * <pre>

 *      Rectangle virtualBounds = new Rectangle();

 *      GraphicsEnvironment ge = GraphicsEnvironment.

 *              getLocalGraphicsEnvironment();

 *      GraphicsDevice[] gs =

 *              ge.getScreenDevices();

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

 *          GraphicsDevice gd = gs[j];

 *          GraphicsConfiguration[] gc =

 *              gd.getConfigurations();

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

 *              virtualBounds =

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

 *          }

 *      } </pre>

 *

 * @see Window

 * @see Frame

 * @see GraphicsEnvironment

 * @see GraphicsDevice

 */

/*

 * REMIND:  What to do about capabilities?

 * The

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

 * capabilities and checking if the GraphicsConfiguration

 * implements the interface for that capability.

 *

 */

public abstract class GraphicsConfiguration {

    private static BufferCapabilities defaultBufferCaps;

    private static ImageCapabilities defaultImageCaps;

    /**

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

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

     *

     * @see GraphicsDevice#getConfigurations

     * @see GraphicsDevice#getDefaultConfiguration

     * @see GraphicsDevice#getBestConfiguration

     * @see Graphics2D#getDeviceConfiguration

     */

    protected GraphicsConfiguration() {

    }

    /**

     * Returns the {@link GraphicsDevice} associated with this

     * <code>GraphicsConfiguration</code>.

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

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

     */

    public abstract GraphicsDevice getDevice();

    /**

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

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

     * method has nothing to do with memory-mapping

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

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

     * configuration and can therefore be optimally blitted to this

     * device.

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

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

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

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

     */

    public BufferedImage createCompatibleImage(int width, int height) {

        ColorModel model = getColorModel();

        WritableRaster raster =

            model.createCompatibleWritableRaster(width, height);

        return new BufferedImage(model, raster,

                                 model.isAlphaPremultiplied(), null);

    }

    /**

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

     * transparency and has a data layout and color model

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

     * method has nothing to do with memory-mapping

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

     * color model that can be optimally blitted to a device

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

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

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

     * @param transparency the specified transparency mode

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

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

     * and also supports the specified transparency.

     * @throws IllegalArgumentException if the transparency is not a valid value

     * @see Transparency#OPAQUE

     * @see Transparency#BITMASK

     * @see Transparency#TRANSLUCENT

     */

    public BufferedImage createCompatibleImage(int width, int height,

                                               int transparency)

    {

        if (getColorModel().getTransparency() == transparency) {

            return createCompatibleImage(width, height);

        }

        ColorModel cm = getColorModel(transparency);

        if (cm == null) {

            throw new IllegalArgumentException("Unknown transparency: " +

                                               transparency);

        }

        WritableRaster wr = cm.createCompatibleWritableRaster(width, height);

        return new BufferedImage(cm, wr, cm.isAlphaPremultiplied(), null);

    }

    /**

     * Returns a {@link VolatileImage} with a data layout and color model

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

     * The returned <code>VolatileImage</code>

     * may have data that is stored optimally for the underlying graphics

     * device and may therefore benefit from platform-specific rendering

     * acceleration.

     * @param width the width of the returned <code>VolatileImage</code>

     * @param height the height of the returned <code>VolatileImage</code>

     * @return a <code>VolatileImage</code> whose data layout and color

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

     * @see Component#createVolatileImage(int, int)

     * @since 1.4

     */

    public VolatileImage createCompatibleVolatileImage(int width, int height) {

        VolatileImage vi = null;

        try {

            vi = createCompatibleVolatileImage(width, height,

                                               null, Transparency.OPAQUE);

        } catch (AWTException e) {

            // shouldn't happen: we're passing in null caps

            assert false;

        }

        return vi;

    }

    /**

     * Returns a {@link VolatileImage} with a data layout and color model

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

     * The returned <code>VolatileImage</code>

     * may have data that is stored optimally for the underlying graphics

     * device and may therefore benefit from platform-specific rendering

     * acceleration.

     * @param width the width of the returned <code>VolatileImage</code>

     * @param height the height of the returned <code>VolatileImage</code>

     * @param transparency the specified transparency mode

     * @return a <code>VolatileImage</code> whose data layout and color

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

     * @throws IllegalArgumentException if the transparency is not a valid value

     * @see Transparency#OPAQUE

     * @see Transparency#BITMASK

     * @see Transparency#TRANSLUCENT

     * @see Component#createVolatileImage(int, int)

     * @since 1.5

     */

    public VolatileImage createCompatibleVolatileImage(int width, int height,

                                                       int transparency)

    {

        VolatileImage vi = null;

        try {

            vi = createCompatibleVolatileImage(width, height, null, transparency);

        } catch (AWTException e) {

            // shouldn't happen: we're passing in null caps

            assert false;

        }

        return vi;

    }

    /**

     * Returns a {@link VolatileImage} with a data layout and color model

     * compatible with this <code>GraphicsConfiguration</code>, using

     * the specified image capabilities.

     * If the <code>caps</code> parameter is null, it is effectively ignored

     * and this method will create a VolatileImage without regard to

     * <code>ImageCapabilities</code> constraints.

     *

     * The returned <code>VolatileImage</code> has

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

     * configuration and can therefore be optimally blitted to this

     * device.

     * @return a <code>VolatileImage</code> whose data layout and color

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

     * @param width the width of the returned <code>VolatileImage</code>

     * @param height the height of the returned <code>VolatileImage</code>

     * @param caps the image capabilities

     * @exception AWTException if the supplied image capabilities could not

     * be met by this graphics configuration

     * @since 1.4

     */

    public VolatileImage createCompatibleVolatileImage(int width, int height,

        ImageCapabilities caps) throws AWTException

    {

        return createCompatibleVolatileImage(width, height, caps,

                                             Transparency.OPAQUE);

    }

    /**

     * Returns a {@link VolatileImage} with a data layout and color model

     * compatible with this <code>GraphicsConfiguration</code>, using

     * the specified image capabilities and transparency value.

     * If the <code>caps</code> parameter is null, it is effectively ignored

     * and this method will create a VolatileImage without regard to

     * <code>ImageCapabilities</code> constraints.

     *

     * The returned <code>VolatileImage</code> has

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

     * configuration and can therefore be optimally blitted to this

     * device.

     * @param width the width of the returned <code>VolatileImage</code>

     * @param height the height of the returned <code>VolatileImage</code>

     * @param caps the image capabilities

     * @param transparency the specified transparency mode

     * @return a <code>VolatileImage</code> whose data layout and color

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

     * @see Transparency#OPAQUE

     * @see Transparency#BITMASK

     * @see Transparency#TRANSLUCENT

     * @throws IllegalArgumentException if the transparency is not a valid value

     * @exception AWTException if the supplied image capabilities could not

     * be met by this graphics configuration

     * @see Component#createVolatileImage(int, int)

     * @since 1.5

     */

    public VolatileImage createCompatibleVolatileImage(int width, int height,

        ImageCapabilities caps, int transparency) throws AWTException

    {

        VolatileImage vi =

            new SunVolatileImage(this, width, height, transparency, caps);

        if (caps != null && caps.isAccelerated() &&

            !vi.getCapabilities().isAccelerated())

        {

            throw new AWTException("Supplied image capabilities could not " +

                                   "be met by this graphics configuration.");

        }

        return vi;

    }

    /**

     * Returns the {@link ColorModel} associated with this

     * <code>GraphicsConfiguration</code>.

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

     * this <code>GraphicsConfiguration</code>.

     */

    public abstract ColorModel getColorModel();

    /**

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

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

     * transparency.

     * @param transparency the specified transparency mode

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

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

     * specified transparency or null if the transparency is not a valid

     * value.

     * @see Transparency#OPAQUE

     * @see Transparency#BITMASK

     * @see Transparency#TRANSLUCENT

     */

    public abstract ColorModel getColorModel(int transparency);

    /**

     * Returns the default {@link AffineTransform} for this

     * <code>GraphicsConfiguration</code>. This

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

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

     * maps coordinates onto the device such that 72 user space

     * coordinate units measure approximately 1 inch in device

     * space.  The normalizing transform can be used to make

     * this mapping more exact.  Coordinates in the coordinate space

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

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

     * the target region of the device, with X coordinates

     * increasing to the right and Y coordinates increasing downwards.

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

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

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

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

     * <code>GraphicsConfiguration</code>.

     */

    public abstract AffineTransform getDefaultTransform();

    /**

     *

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

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

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

     * space equals 1 inch in device space.

     * <p>

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

     * can reset the transformation to create

     * such a mapping by using the following pseudocode:

     * <pre>

     *      GraphicsConfiguration gc = g.getDeviceConfiguration();

     *

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

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

     * </pre>

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

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

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

     * supplied by the underlying system.  For image buffers not

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

     * <code>createCompatibleImage</code>, this

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

     * since there is no valid distance measurement.

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

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

     * space is mapped to 1 inch in device space.

     */

    public abstract AffineTransform getNormalizingTransform();

    /**

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

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

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

     * or Y origins.

     * @return the bounds of the area covered by this

     * <code>GraphicsConfiguration</code>.

     * @since 1.3

     */

    public abstract Rectangle getBounds();

    private static class DefaultBufferCapabilities extends BufferCapabilities {

        public DefaultBufferCapabilities(ImageCapabilities imageCaps) {

            super(imageCaps, imageCaps, null);

        }

    }

    /**

     * Returns the buffering capabilities of this

     * <code>GraphicsConfiguration</code>.

     * @return the buffering capabilities of this graphics

     * configuration object

     * @since 1.4

     */

    public BufferCapabilities getBufferCapabilities() {

        if (defaultBufferCaps == null) {

            defaultBufferCaps = new DefaultBufferCapabilities(

                getImageCapabilities());

        }

        return defaultBufferCaps;

    }

    /**

     * Returns the image capabilities of this

     * <code>GraphicsConfiguration</code>.

     * @return the image capabilities of this graphics

     * configuration object

     * @since 1.4

     */

    public ImageCapabilities getImageCapabilities() {

        if (defaultImageCaps == null) {

            defaultImageCaps = new ImageCapabilities(false);

        }

        return defaultImageCaps;

    }

    /**

     * Returns whether this GraphicsConfiguration supports

     * the {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT

     * PERPIXEL_TRANSLUCENT} kind of translucency.

     *

     * @param gc GraphicsConfiguration

     * @throws NullPointerException if the gc argument is null

     * @return whether the given GraphicsConfiguration supports

     *         the translucency effects.

     * @see Window#setBackground(Color)

     */

    /*public */boolean isTranslucencyCapable() {

        // Overridden in subclasses

        return false;

    }

}