/*
* Copyright (c) 1997, 2009, Oracle and/or its affiliates. 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. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.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 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:
/**
* 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 Also: - getConfigurations.getConfigurations
- GraphicsDevice.getDefaultConfiguration
- GraphicsDevice.getBestConfiguration
- Graphics2D.getDeviceConfiguration
/**
* 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 GraphicsDevice
associated with this GraphicsConfiguration
.
Returns: a GraphicsDevice
object that is
associated with this 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 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.
Params: - 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
.
/**
* 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 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
.
Params: - width – the width of the returned
BufferedImage
- height – the height of the returned
BufferedImage
- transparency – the specified transparency mode
Throws: - IllegalArgumentException – if the transparency is not a valid value
See Also: Returns: a BufferedImage
whose data layout and color
model is compatible with this GraphicsConfiguration
and also supports the specified transparency.
/**
* 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 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.
Params: - width – the width of the returned
VolatileImage
- height – the height of the returned
VolatileImage
See Also: Returns: a VolatileImage
whose data layout and color
model is compatible with this GraphicsConfiguration
. Since: 1.4
/**
* 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 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.
Params: - width – the width of the returned
VolatileImage
- height – the height of the returned
VolatileImage
- transparency – the specified transparency mode
Throws: - IllegalArgumentException – if the transparency is not a valid value
See Also: Returns: a VolatileImage
whose data layout and color
model is compatible with this GraphicsConfiguration
. Since: 1.5
/**
* 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 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.
Params: - width – the width of the returned
VolatileImage
- height – the height of the returned
VolatileImage
- caps – the image capabilities
Throws: - AWTException – if the supplied image capabilities could not
be met by this graphics configuration
Returns: a VolatileImage
whose data layout and color
model is compatible with this GraphicsConfiguration
. Since: 1.4
/**
* 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 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.
Params: - width – the width of the returned
VolatileImage
- height – the height of the returned
VolatileImage
- caps – the image capabilities
- transparency – the specified transparency mode
Throws: - IllegalArgumentException – if the transparency is not a valid value
- AWTException – if the supplied image capabilities could not
be met by this graphics configuration
See Also: Returns: a VolatileImage
whose data layout and color
model is compatible with this GraphicsConfiguration
. Since: 1.5
/**
* 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 ColorModel
associated with this GraphicsConfiguration
.
Returns: a ColorModel
object that is associated with
this GraphicsConfiguration
.
/**
* 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 ColorModel
associated with this
GraphicsConfiguration
that supports the specified
transparency.
Params: - transparency – the specified transparency mode
See Also: 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.
/**
* 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 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
.
/**
* 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 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.
/**
*
* 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 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
/**
* 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
GraphicsConfiguration
.
Returns: the buffering capabilities of this graphics
configuration object Since: 1.4
/**
* 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
GraphicsConfiguration
.
Returns: the image capabilities of this graphics
configuration object Since: 1.4
/**
* 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
PERPIXEL_TRANSLUCENT
kind of translucency. See Also: Returns: whether the given GraphicsConfiguration supports
the translucency effects. Since: 1.7
/**
* Returns whether this {@code GraphicsConfiguration} supports
* the {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT
* PERPIXEL_TRANSLUCENT} kind of translucency.
*
* @return whether the given GraphicsConfiguration supports
* the translucency effects.
*
* @see Window#setBackground(Color)
*
* @since 1.7
*/
public boolean isTranslucencyCapable() {
// Overridden in subclasses
return false;
}
}