java.awt

## Class GraphicsConfiguration

- java.lang.Object
- - java.awt.GraphicsConfiguration

-     public abstract class GraphicsConfiguration
      extends Object

  The `GraphicsConfiguration` class describes the characteristics of a graphics destination such as a printer or monitor. There can be many `GraphicsConfiguration` 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 `GraphicsConfiguration`. On Microsoft Windows, `GraphicsConfiguration`s represent PixelFormats available in the current resolution and color depth.

  In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, the bounds of the `GraphicsConfiguration` objects are relative to the virtual coordinate system. When setting the location of a component, use `getBounds` to get the bounds of the desired `GraphicsConfiguration` and offset the location with the coordinates of the `GraphicsConfiguration`, as the following code sample illustrates:

            Frame f = new Frame(gc);  // where gc is a GraphicsConfiguration
            Rectangle bounds = gc.getBounds();
            f.setLocation(10 + bounds.x, 10 + bounds.y);

  To determine if your environment is a virtual device environment, call `getBounds` on all of the `GraphicsConfiguration` objects in your system. If any of the origins of the returned bounds is not (0, 0), your environment is a virtual device environment.

  You can also use `getBounds` to determine the bounds of the virtual device. To do this, first call `getBounds` on all of the `GraphicsConfiguration` objects in your system. Then calculate the union of all of the bounds returned from the calls to `getBounds`. The union is the bounds of the virtual device. The following code sample calculates the bounds of the virtual device.

            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());
                }
            }

  See Also:
    `Window`, `Frame`, `GraphicsEnvironment`, `GraphicsDevice`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `GraphicsConfiguration()` This is an abstract class that cannot be instantiated directly.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract BufferedImage` | `createCompatibleImage(int width, int height)` Returns a `BufferedImage` with a data layout and color model compatible with this `GraphicsConfiguration`.
    `BufferedImage` | `createCompatibleImage(int width, int height, int transparency)` Returns a `BufferedImage` that supports the specified transparency and has a data layout and color model compatible with this `GraphicsConfiguration`.
    `VolatileImage` | `createCompatibleVolatileImage(int width, int height)` Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`.
    `VolatileImage` | `createCompatibleVolatileImage(int width, int height, ImageCapabilities caps)` Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`, using the specified image capabilities.
    `VolatileImage` | `createCompatibleVolatileImage(int width, int height, ImageCapabilities caps, int transparency)` Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`, using the specified image capabilities and transparency value.
    `VolatileImage` | `createCompatibleVolatileImage(int width, int height, int transparency)` Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`.
    `abstract Rectangle` | `getBounds()` Returns the bounds of the `GraphicsConfiguration` in the device coordinates.
    `BufferCapabilities` | `getBufferCapabilities()` Returns the buffering capabilities of this `GraphicsConfiguration`.
    `abstract ColorModel` | `getColorModel()` Returns the `ColorModel` associated with this `GraphicsConfiguration`.
    `abstract ColorModel` | `getColorModel(int transparency)` Returns the `ColorModel` associated with this `GraphicsConfiguration` that supports the specified transparency.
    `abstract AffineTransform` | `getDefaultTransform()` Returns the default `AffineTransform` for this `GraphicsConfiguration`.
    `abstract GraphicsDevice` | `getDevice()` Returns the `GraphicsDevice` associated with this `GraphicsConfiguration`.
    `ImageCapabilities` | `getImageCapabilities()` Returns the image capabilities of this `GraphicsConfiguration`.
    `abstract AffineTransform` | `getNormalizingTransform()` Returns a `AffineTransform` that can be concatenated with the default `AffineTransform` of a `GraphicsConfiguration` so that 72 units in user space equals 1 inch in device space.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### GraphicsConfiguration

          protected GraphicsConfiguration()

      This is an abstract class that cannot be instantiated directly. Instances must be obtained from a suitable factory or query method.
      See Also:
        `GraphicsDevice.getConfigurations()`, `GraphicsDevice.getDefaultConfiguration()`, `GraphicsDevice.getBestConfiguration(java.awt.GraphicsConfigTemplate)`, `Graphics2D.getDeviceConfiguration()`

  - ### Method Detail

    - #### getDevice

          public abstract GraphicsDevice getDevice()

      Returns the `GraphicsDevice` associated with this `GraphicsConfiguration`.
      Returns:
        a `GraphicsDevice` object that is associated with this `GraphicsConfiguration`.

    - #### createCompatibleImage

          public abstract BufferedImage createCompatibleImage(int width,
                                            int height)

      Returns a `BufferedImage` with a data layout and color model compatible with this `GraphicsConfiguration`. This method has nothing to do with memory-mapping a device. The returned `BufferedImage` has a layout and color model that is closest to this native device configuration and can therefore be optimally blitted to this device.
      Parameters:
        `width` - the width of the returned `BufferedImage`
        `height` - the height of the returned `BufferedImage`
      Returns:
        a `BufferedImage` whose data layout and color model is compatible with this `GraphicsConfiguration`.

    - #### createCompatibleImage

          public BufferedImage createCompatibleImage(int width,
                                            int height,
                                            int transparency)

      Returns a `BufferedImage` that supports the specified transparency and has a data layout and color model compatible with this `GraphicsConfiguration`. This method has nothing to do with memory-mapping a device. The returned `BufferedImage` has a layout and color model that can be optimally blitted to a device with this `GraphicsConfiguration`.
      Parameters:
        `width` - the width of the returned `BufferedImage`
        `height` - the height of the returned `BufferedImage`
        `transparency` - the specified transparency mode
      Returns:
        a `BufferedImage` whose data layout and color model is compatible with this `GraphicsConfiguration` and also supports the specified transparency.
      Throws:
        `IllegalArgumentException` - if the transparency is not a valid value
      See Also:
        `Transparency.OPAQUE`, `Transparency.BITMASK`, `Transparency.TRANSLUCENT`

    - #### createCompatibleVolatileImage

          public VolatileImage createCompatibleVolatileImage(int width,
                                                    int height)

      Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`. The returned `VolatileImage` may have data that is stored optimally for the underlying graphics device and may therefore benefit from platform-specific rendering acceleration.
      Parameters:
        `width` - the width of the returned `VolatileImage`
        `height` - the height of the returned `VolatileImage`
      Returns:
        a `VolatileImage` whose data layout and color model is compatible with this `GraphicsConfiguration`.
      Since:
        1.4
      See Also:
        `Component.createVolatileImage(int, int)`

    - #### createCompatibleVolatileImage

          public VolatileImage createCompatibleVolatileImage(int width,
                                                    int height,
                                                    int transparency)

      Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`. The returned `VolatileImage` may have data that is stored optimally for the underlying graphics device and may therefore benefit from platform-specific rendering acceleration.
      Parameters:
        `width` - the width of the returned `VolatileImage`
        `height` - the height of the returned `VolatileImage`
        `transparency` - the specified transparency mode
      Returns:
        a `VolatileImage` whose data layout and color model is compatible with this `GraphicsConfiguration`.
      Throws:
        `IllegalArgumentException` - if the transparency is not a valid value
      Since:
        1.5
      See Also:
        `Transparency.OPAQUE`, `Transparency.BITMASK`, `Transparency.TRANSLUCENT`, `Component.createVolatileImage(int, int)`

    - #### createCompatibleVolatileImage

          public VolatileImage createCompatibleVolatileImage(int width,
                                                    int height,
                                                    ImageCapabilities caps)
                                                      throws AWTException

      Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`, using the specified image capabilities. If the `caps` parameter is null, it is effectively ignored and this method will create a VolatileImage without regard to `ImageCapabilities` constraints. The returned `VolatileImage` has a layout and color model that is closest to this native device configuration and can therefore be optimally blitted to this device.
      Parameters:
        `width` - the width of the returned `VolatileImage`
        `height` - the height of the returned `VolatileImage`
        `caps` - the image capabilities
      Returns:
        a `VolatileImage` whose data layout and color model is compatible with this `GraphicsConfiguration`.
      Throws:
        `AWTException` - if the supplied image capabilities could not be met by this graphics configuration
      Since:
        1.4

    - #### createCompatibleVolatileImage

          public VolatileImage createCompatibleVolatileImage(int width,
                                                    int height,
                                                    ImageCapabilities caps,
                                                    int transparency)
                                                      throws AWTException

      Returns a `VolatileImage` with a data layout and color model compatible with this `GraphicsConfiguration`, using the specified image capabilities and transparency value. If the `caps` parameter is null, it is effectively ignored and this method will create a VolatileImage without regard to `ImageCapabilities` constraints. The returned `VolatileImage` has a layout and color model that is closest to this native device configuration and can therefore be optimally blitted to this device.
      Parameters:
        `width` - the width of the returned `VolatileImage`
        `height` - the height of the returned `VolatileImage`
        `caps` - the image capabilities
        `transparency` - the specified transparency mode
      Returns:
        a `VolatileImage` whose data layout and color model is compatible with this `GraphicsConfiguration`.
      Throws:
        `IllegalArgumentException` - if the transparency is not a valid value
        `AWTException` - if the supplied image capabilities could not be met by this graphics configuration
      Since:
        1.5
      See Also:
        `Transparency.OPAQUE`, `Transparency.BITMASK`, `Transparency.TRANSLUCENT`, `Component.createVolatileImage(int, int)`

    - #### getColorModel

          public abstract ColorModel getColorModel()

      Returns the `ColorModel` associated with this `GraphicsConfiguration`.
      Returns:
        a `ColorModel` object that is associated with this `GraphicsConfiguration`.

    - #### getColorModel

          public abstract ColorModel getColorModel(int transparency)

      Returns the `ColorModel` associated with this `GraphicsConfiguration` that supports the specified transparency.
      Parameters:
        `transparency` - the specified transparency mode
      Returns:
        a `ColorModel` object that is associated with this `GraphicsConfiguration` and supports the specified transparency or null if the transparency is not a valid value.
      See Also:
        `Transparency.OPAQUE`, `Transparency.BITMASK`, `Transparency.TRANSLUCENT`

    - #### getDefaultTransform

          public abstract AffineTransform getDefaultTransform()

      Returns the default `AffineTransform` for this `GraphicsConfiguration`. This `AffineTransform` is typically the Identity transform for most normal screens. The default `AffineTransform` 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 `AffineTransform` 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 `createCompatibleImage`, this `AffineTransform` is the Identity transform.
      Returns:
        the default `AffineTransform` for this `GraphicsConfiguration`.

    - #### getNormalizingTransform

          public abstract AffineTransform getNormalizingTransform()

      Returns a `AffineTransform` that can be concatenated with the default `AffineTransform` of a `GraphicsConfiguration` so that 72 units in user space equals 1 inch in device space.

      For a particular `Graphics2D`, g, one can reset the transformation to create such a mapping by using the following pseudocode:

                GraphicsConfiguration gc = g.getDeviceConfiguration();

                g.setTransform(gc.getDefaultTransform());
                g.transform(gc.getNormalizingTransform());

      Note that sometimes this `AffineTransform` is identity, such as for printers or metafile output, and that this `AffineTransform` 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 `createCompatibleImage`, this `AffineTransform` is the Identity transform since there is no valid distance measurement.
      Returns:
        an `AffineTransform` to concatenate to the default `AffineTransform` so that 72 units in user space is mapped to 1 inch in device space.

    - #### getBounds

          public abstract Rectangle getBounds()

      Returns the bounds of the `GraphicsConfiguration` in the device coordinates. In a multi-screen environment with a virtual device, the bounds can have negative X or Y origins.
      Returns:
        the bounds of the area covered by this `GraphicsConfiguration`.
      Since:
        1.3

    - #### getBufferCapabilities

          public BufferCapabilities getBufferCapabilities()

      Returns the buffering capabilities of this `GraphicsConfiguration`.
      Returns:
        the buffering capabilities of this graphics configuration object
      Since:
        1.4

    - #### getImageCapabilities

          public ImageCapabilities getImageCapabilities()

      Returns the image capabilities of this `GraphicsConfiguration`.
      Returns:
        the image capabilities of this graphics configuration object
      Since:
        1.4

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.