001: /*
002: * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.awt;
027:
028: import java.awt.geom.AffineTransform;
029: import java.awt.image.BufferedImage;
030: import java.awt.image.ColorModel;
031: import java.awt.image.VolatileImage;
032: import java.awt.image.WritableRaster;
033:
034: import sun.awt.image.SunVolatileImage;
035:
036: /**
037: * The <code>GraphicsConfiguration</code> class describes the
038: * characteristics of a graphics destination such as a printer or monitor.
039: * There can be many <code>GraphicsConfiguration</code> objects associated
040: * with a single graphics device, representing different drawing modes or
041: * capabilities. The corresponding native structure will vary from platform
042: * to platform. For example, on X11 windowing systems,
043: * each visual is a different <code>GraphicsConfiguration</code>.
044: * On Microsoft Windows, <code>GraphicsConfiguration</code>s represent
045: * PixelFormats available in the current resolution and color depth.
046: * <p>
047: * In a virtual device multi-screen environment in which the desktop
048: * area could span multiple physical screen devices, the bounds of the
049: * <code>GraphicsConfiguration</code> objects are relative to the
050: * virtual coordinate system. When setting the location of a
051: * component, use {@link #getBounds() getBounds} to get the bounds of
052: * the desired <code>GraphicsConfiguration</code> and offset the location
053: * with the coordinates of the <code>GraphicsConfiguration</code>,
054: * as the following code sample illustrates:
055: * </p>
056: *
057: * <pre>
058: * Frame f = new Frame(gc); // where gc is a GraphicsConfiguration
059: * Rectangle bounds = gc.getBounds();
060: * f.setLocation(10 + bounds.x, 10 + bounds.y); </pre>
061: *
062: * <p>
063: * To determine if your environment is a virtual device
064: * environment, call <code>getBounds</code> on all of the
065: * <code>GraphicsConfiguration</code> objects in your system. If
066: * any of the origins of the returned bounds is not (0, 0),
067: * your environment is a virtual device environment.
068: *
069: * <p>
070: * You can also use <code>getBounds</code> to determine the bounds
071: * of the virtual device. To do this, first call <code>getBounds</code> on all
072: * of the <code>GraphicsConfiguration</code> objects in your
073: * system. Then calculate the union of all of the bounds returned
074: * from the calls to <code>getBounds</code>. The union is the
075: * bounds of the virtual device. The following code sample
076: * calculates the bounds of the virtual device.
077: *
078: * <pre>
079: * Rectangle virtualBounds = new Rectangle();
080: * GraphicsEnvironment ge = GraphicsEnvironment.
081: * getLocalGraphicsEnvironment();
082: * GraphicsDevice[] gs =
083: * ge.getScreenDevices();
084: * for (int j = 0; j < gs.length; j++) {
085: * GraphicsDevice gd = gs[j];
086: * GraphicsConfiguration[] gc =
087: * gd.getConfigurations();
088: * for (int i=0; i < gc.length; i++) {
089: * virtualBounds =
090: * virtualBounds.union(gc[i].getBounds());
091: * }
092: * } </pre>
093: *
094: * @see Window
095: * @see Frame
096: * @see GraphicsEnvironment
097: * @see GraphicsDevice
098: */
099: /*
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: * @version 1.48, 05/05/07
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 = model.createCompatibleWritableRaster(
150: width, height);
151: return new BufferedImage(model, raster, model
152: .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: if (getColorModel().getTransparency() == transparency) {
177: return createCompatibleImage(width, height);
178: }
179:
180: ColorModel cm = getColorModel(transparency);
181: if (cm == null) {
182: throw new IllegalArgumentException("Unknown transparency: "
183: + transparency);
184: }
185: WritableRaster wr = cm.createCompatibleWritableRaster(width,
186: height);
187: return new BufferedImage(cm, wr, cm.isAlphaPremultiplied(),
188: null);
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,
206: int height) {
207: VolatileImage vi = null;
208: try {
209: vi = createCompatibleVolatileImage(width, height, null,
210: Transparency.OPAQUE);
211: } catch (AWTException e) {
212: // shouldn't happen: we're passing in null caps
213: assert false;
214: }
215: return vi;
216: }
217:
218: /**
219: * Returns a {@link VolatileImage} with a data layout and color model
220: * compatible with this <code>GraphicsConfiguration</code>.
221: * The returned <code>VolatileImage</code>
222: * may have data that is stored optimally for the underlying graphics
223: * device and may therefore benefit from platform-specific rendering
224: * acceleration.
225: * @param width the width of the returned <code>VolatileImage</code>
226: * @param height the height of the returned <code>VolatileImage</code>
227: * @param transparency the specified transparency mode
228: * @return a <code>VolatileImage</code> whose data layout and color
229: * model is compatible with this <code>GraphicsConfiguration</code>.
230: * @throws IllegalArgumentException if the transparency is not a valid value
231: * @see Transparency#OPAQUE
232: * @see Transparency#BITMASK
233: * @see Transparency#TRANSLUCENT
234: * @see Component#createVolatileImage(int, int)
235: * @since 1.5
236: */
237: public VolatileImage createCompatibleVolatileImage(int width,
238: int height, int transparency) {
239: VolatileImage vi = null;
240: try {
241: vi = createCompatibleVolatileImage(width, height, null,
242: transparency);
243: } catch (AWTException e) {
244: // shouldn't happen: we're passing in null caps
245: assert false;
246: }
247: return vi;
248: }
249:
250: /**
251: * Returns a {@link VolatileImage} with a data layout and color model
252: * compatible with this <code>GraphicsConfiguration</code>, using
253: * the specified image capabilities.
254: * If the <code>caps</code> parameter is null, it is effectively ignored
255: * and this method will create a VolatileImage without regard to
256: * <code>ImageCapabilities</code> constraints.
257: *
258: * The returned <code>VolatileImage</code> has
259: * a layout and color model that is closest to this native device
260: * configuration and can therefore be optimally blitted to this
261: * device.
262: * @return a <code>VolatileImage</code> whose data layout and color
263: * model is compatible with this <code>GraphicsConfiguration</code>.
264: * @param width the width of the returned <code>VolatileImage</code>
265: * @param height the height of the returned <code>VolatileImage</code>
266: * @param caps the image capabilities
267: * @exception AWTException if the supplied image capabilities could not
268: * be met by this graphics configuration
269: * @since 1.4
270: */
271: public VolatileImage createCompatibleVolatileImage(int width,
272: int height, ImageCapabilities caps) throws AWTException {
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,
305: int height, ImageCapabilities caps, int transparency)
306: throws AWTException {
307: VolatileImage vi = new SunVolatileImage(this , width, height,
308: transparency, caps);
309: if (caps != null && caps.isAccelerated()
310: && !vi.getCapabilities().isAccelerated()) {
311: throw new AWTException(
312: "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
404: BufferCapabilities {
405: public DefaultBufferCapabilities(ImageCapabilities imageCaps) {
406: super (imageCaps, imageCaps, null);
407: }
408: }
409:
410: /**
411: * Returns the buffering capabilities of this
412: * <code>GraphicsConfiguration</code>.
413: * @return the buffering capabilities of this graphics
414: * configuration object
415: * @since 1.4
416: */
417: public BufferCapabilities getBufferCapabilities() {
418: if (defaultBufferCaps == null) {
419: defaultBufferCaps = new DefaultBufferCapabilities(
420: getImageCapabilities());
421: }
422: return defaultBufferCaps;
423: }
424:
425: /**
426: * Returns the image capabilities of this
427: * <code>GraphicsConfiguration</code>.
428: * @return the image capabilities of this graphics
429: * configuration object
430: * @since 1.4
431: */
432: public ImageCapabilities getImageCapabilities() {
433: if (defaultImageCaps == null) {
434: defaultImageCaps = new ImageCapabilities(false);
435: }
436: return defaultImageCaps;
437: }
438: }
|
