001: /*
002: * @(#)GraphicsConfiguration.java 1.12 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.awt;
029:
030: // import java.awt.geom.AffineTransform;
031: import java.awt.image.BufferedImage;
032: import java.awt.image.ColorModel;
033: import java.awt.image.VolatileImage;
034:
035: /**
036: * The <code>GraphicsConfiguration</code> class describes the
037: * characteristics of a graphics destination such as a printer or monitor.
038: * There can be many <code>GraphicsConfiguration</code> objects associated
039: * with a single graphics device, representing different drawing modes or
040: * capabilities. The corresponding native structure will vary from platform
041: * to platform. For example, on X11 windowing systems,
042: * each visual is a different <code>GraphicsConfiguration</code>.
043: * On win32, <code>GraphicsConfiguration</code>s represent PixelFormats
044: * available in the current resolution and color depth.
045: * <p>
046: * In a virtual device multi-screen environment in which the desktop
047: * area could span multiple physical screen devices, the bounds of the
048: * <code>GraphicsConfiguration</code> objects are relative to the
049: * virtual coordinate system. When setting the location of a
050: * component, use {@link #getBounds() getBounds} to get the bounds of
051: * the desired <code>GraphicsConfiguration</code> and offset the location
052: * with the coordinates of the <code>GraphicsConfiguration</code>,
053: * as the following code sample illustrates:
054: * <pre>
055: * Frame f = new Frame(GraphicsConfiguration gc);
056: * Rectangle bounds = gc.getBounds();
057: * f.setLocation(10 + bounds.x, 10 + bounds.y);
058: * </pre>
059: * To determine if your environment is a virtual device
060: * environment, call <code>getBounds</code> on all of the
061: * <code>GraphicsConfiguration</code> objects in your system. If
062: * any of the origins of the returned bounds are not (0, 0),
063: * your environment is a virtual device environment.
064: * <p>
065: * You can also use <code>getBounds</code> to determine the bounds
066: * of the virtual device. Call <code>getBounds</code> on all
067: * of the <code>GraphicsConfiguration</code> objects in your
068: * system. Then, calculate the union of all of the bounds returned
069: * from the calls to <code>getBounds</code>. The union is the
070: * bounds of the virtual device. The following code sample
071: * calculates the bounds of the virtual device.
072: * <pre>
073: * Rectangle virtualBounds = new Rectangle();
074: * GraphicsEnvironment ge = GraphicsEnvironment.
075: * getLocalGraphicsEnvironment();
076: * GraphicsDevice[] gs =
077: * ge.getScreenDevices();
078: * for (int j = 0; j < gs.length; j++) {
079: * GraphicsDevice gd = gs[j];
080: * GraphicsConfiguration[] gc =
081: * gd.getConfigurations();
082: * for (int i=0; i < gc.length; i++) {
083: * virtualBounds =
084: * virtualBounds.union(gc[i].getBounds());
085: * }
086: * }
087: * </pre>
088: * @see Window
089: * @see Frame
090: * @see GraphicsEnvironment
091: * @see GraphicsDevice
092: */
093:
094: /*
095: * NOTE: What to do about capabilities?
096: * The
097: * capabilities of the device can be determined by enumerating the possible
098: * capabilities and checking if the GraphicsConfiguration
099: * implements the interface for that capability.
100: *
101: * @version 1.28, 02/09/01
102: */
103:
104: public abstract class GraphicsConfiguration {
105: private static ImageCapabilities defaultImageCaps;
106:
107: /**
108: * This is an abstract class that cannot be instantiated directly.
109: * Instances must be obtained from a suitable factory or query method.
110: *
111: * @see GraphicsDevice#getConfigurations
112: * @see GraphicsDevice#getDefaultConfiguration
113: * @see GraphicsDevice#getBestConfiguration
114: * @see Graphics2D#getDeviceConfiguration
115: */
116: protected GraphicsConfiguration() {
117: }
118:
119: /**
120: * Returns the {@link GraphicsDevice} associated with this
121: * <code>GraphicsConfiguration</code>.
122: * @return a <code>GraphicsDevice</code> object that is
123: * associated with this <code>GraphicsConfiguration</code>.
124: */
125: public abstract GraphicsDevice getDevice();
126:
127: /**
128: * Returns a {@link BufferedImage} with a data layout and color model
129: * compatible with this <code>GraphicsConfiguration</code>. This
130: * method has nothing to do with memory-mapping
131: * a device. The returned <code>BufferedImage</code> has
132: * a layout and color model that is closest to this native device
133: * configuration and can therefore be optimally blitted to this
134: * device.
135: * @param width the width of the returned <code>BufferedImage</code>
136: * @param height the height of the returned <code>BufferedImage</code>
137: * @return a <code>BufferedImage</code> whose data layout and color
138: * model is compatible with this <code>GraphicsConfiguration</code>.
139: */
140: public abstract BufferedImage createCompatibleImage(int width,
141: int height);
142:
143: /**
144: * Returns a <code>BufferedImage</code> that supports the specified
145: * transparency and has a data layout and color model
146: * compatible with this <code>GraphicsConfiguration</code>. This
147: * method has nothing to do with memory-mapping
148: * a device. The returned <code>BufferedImage</code> has a layout and
149: * color model that can be optimally blitted to a device
150: * with this <code>GraphicsConfiguration</code>.
151: * @param width the width of the returned <code>BufferedImage</code>
152: * @param height the height of the returned <code>BufferedImage</code>
153: * @param transparency the specified transparency mode
154: * @return a <code>BufferedImage</code> whose data layout and color
155: * model is compatible with this <code>GraphicsConfiguration</code>
156: * and also supports the specified transparency.
157: * @see Transparency#OPAQUE
158: * @see Transparency#BITMASK
159: * @see Transparency#TRANSLUCENT
160: */
161:
162: /*
163: public abstract BufferedImage createCompatibleImage(int width, int height,
164: int transparency);
165: */
166:
167: /**
168: * Returns a {@link VolatileImage} with a data layout and color model
169: * compatible with this <code>GraphicsConfiguration</code>.
170: * The returned <code>VolatileImage</code>
171: * may have data that is stored optimally for the underlying graphics
172: * device and may therefore benefit from platform-specific rendering
173: * acceleration.
174: * @param width the width of the returned <code>VolatileImage</code>
175: * @param height the height of the returned <code>VolatileImage</code>
176: * @return a <code>VolatileImage</code> whose data layout and color
177: * model is compatible with this <code>GraphicsConfiguration</code>.
178: * @see Component#createVolatileImage(int, int)
179: */
180: public abstract VolatileImage createCompatibleVolatileImage(
181: int width, int height);
182:
183: /**
184: * Returns a {@link VolatileImage} with a data layout and color model
185: * compatible with this <code>GraphicsConfiguration</code>, using
186: * the specified image capabilities.
187: * The returned <code>VolatileImage</code> has
188: * a layout and color model that is closest to this native device
189: * configuration and can therefore be optimally blitted to this
190: * device.
191: * @return a <code>VolatileImage</code> whose data layout and color
192: * model is compatible with this <code>GraphicsConfiguration</code>.
193: * @param width the width of the returned <code>VolatileImage</code>
194: * @param height the height of the returned <code>VolatileImage</code>
195: * @param caps the image capabilities
196: * @exception AWTException if the supplied image capabilities could not
197: * be met by this graphics configuration
198: * @since 1.4
199: */
200: public VolatileImage createCompatibleVolatileImage(int width,
201: int height, ImageCapabilities caps) throws AWTException {
202: // NOTE: check caps
203: return createCompatibleVolatileImage(width, height);
204: }
205:
206: public ImageCapabilities getImageCapabilities() {
207: if (defaultImageCaps == null) {
208: defaultImageCaps = new ImageCapabilities(false);
209: }
210: return defaultImageCaps;
211: }
212:
213: /**
214: * Returns the {@link ColorModel} associated with this
215: * <code>GraphicsConfiguration</code>.
216: * @return a <code>ColorModel</code> object that is associated with
217: * this <code>GraphicsConfiguration</code>.
218: */
219: public abstract ColorModel getColorModel();
220:
221: /**
222: * Returns the <code>ColorModel</code> associated with this
223: * <code>GraphicsConfiguration</code> that supports the specified
224: * transparency.
225: * @param transparency the specified transparency mode
226: * @return a <code>ColorModel</code> object that is associated with
227: * this <code>GraphicsConfiguration</code> and supports the
228: * specified transparency.
229: */
230: // public abstract ColorModel getColorModel(int transparency);
231: /**
232: * Returns the default {@link AffineTransform} for this
233: * <code>GraphicsConfiguration</code>. This
234: * <code>AffineTransform</code> is typically the Identity transform
235: * for most normal screens. The default <code>AffineTransform</code>
236: * maps coordinates onto the device such that 72 user space
237: * coordinate units measure approximately 1 inch in device
238: * space. The normalizing transform can be used to make
239: * this mapping more exact. Coordinates in the coordinate space
240: * defined by the default <code>AffineTransform</code> for screen and
241: * printer devices have the origin in the upper left-hand corner of
242: * the target region of the device, with X coordinates
243: * increasing to the right and Y coordinates increasing downwards.
244: * For image buffers not associated with a device, such as those not
245: * created by <code>createCompatibleImage</code>,
246: * this <code>AffineTransform</code> is the Identity transform.
247: * @return the default <code>AffineTransform</code> for this
248: * <code>GraphicsConfiguration</code>.
249: */
250: // public abstract AffineTransform getDefaultTransform();
251: /**
252: *
253: * Returns a <code>AffineTransform</code> that can be concatenated
254: * with the default <code>AffineTransform</code>
255: * of a <code>GraphicsConfiguration</code> so that 72 units in user
256: * space equals 1 inch in device space.
257: * <p>
258: * For a particular {@link Graphics2D}, g, one
259: * can reset the transformation to create
260: * such a mapping by using the following pseudocode:
261: * <pre>
262: * GraphicsConfiguration gc = g.getGraphicsConfiguration();
263: *
264: * g.setTransform(gc.getDefaultTransform());
265: * g.transform(gc.getNormalizingTransform());
266: * </pre>
267: * Note that sometimes this <code>AffineTransform</code> is identity,
268: * such as for printers or metafile output, and that this
269: * <code>AffineTransform</code> is only as accurate as the information
270: * supplied by the underlying system. For image buffers not
271: * associated with a device, such as those not created by
272: * <code>createCompatibleImage</code>, this
273: * <code>AffineTransform</code> is the Identity transform
274: * since there is no valid distance measurement.
275: * @return an <code>AffineTransform</code> to concatenate to the
276: * default <code>AffineTransform</code> so that 72 units in user
277: * space is mapped to 1 inch in device space.
278: */
279: // public abstract AffineTransform getNormalizingTransform();
280: /**
281: * Returns the bounds of the <code>GraphicsConfiguration</code>
282: * in the device coordinates. In a multi-screen environment
283: * with a virtual device, the bounds can have negative X
284: * or Y origins.
285: * @return the bounds of the area covered by this
286: * <code>GraphicsConfiguration</code>.
287: * @since 1.3
288: */
289: public abstract Rectangle getBounds();
290: }
|