KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > GraphicsConfiguration


1 /*
2  * @(#)GraphicsConfiguration.java 1.38 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.awt;
9
10 import java.awt.geom.AffineTransform JavaDoc;
11 import java.awt.image.BufferedImage JavaDoc;
12 import java.awt.image.ColorModel JavaDoc;
13 import java.awt.image.VolatileImage JavaDoc;
14
15 /**
16  * The <code>GraphicsConfiguration</code> class describes the
17  * characteristics of a graphics destination such as a printer or monitor.
18  * There can be many <code>GraphicsConfiguration</code> objects associated
19  * with a single graphics device, representing different drawing modes or
20  * capabilities. The corresponding native structure will vary from platform
21  * to platform. For example, on X11 windowing systems,
22  * each visual is a different <code>GraphicsConfiguration</code>.
23  * On Microsoft Windows, <code>GraphicsConfiguration</code>s represent
24  * PixelFormats available in the current resolution and color depth.
25  * <p>
26  * In a virtual device multi-screen environment in which the desktop
27  * area could span multiple physical screen devices, the bounds of the
28  * <code>GraphicsConfiguration</code> objects are relative to the
29  * virtual coordinate system. When setting the location of a
30  * component, use {@link #getBounds() getBounds} to get the bounds of
31  * the desired <code>GraphicsConfiguration</code> and offset the location
32  * with the coordinates of the <code>GraphicsConfiguration</code>,
33  * as the following code sample illustrates:
34  * </p>
35  *
36  * <pre>
37  * Frame f = new Frame(gc); // where gc is a GraphicsConfiguration
38  * Rectangle bounds = gc.getBounds();
39  * f.setLocation(10 + bounds.x, 10 + bounds.y); </pre>
40  *
41  * <p>
42  * To determine if your environment is a virtual device
43  * environment, call <code>getBounds</code> on all of the
44  * <code>GraphicsConfiguration</code> objects in your system. If
45  * any of the origins of the returned bounds is not (0,&nbsp;0),
46  * your environment is a virtual device environment.
47  *
48  * <p>
49  * You can also use <code>getBounds</code> to determine the bounds
50  * of the virtual device. To do this, first call <code>getBounds</code> on all
51  * of the <code>GraphicsConfiguration</code> objects in your
52  * system. Then calculate the union of all of the bounds returned
53  * from the calls to <code>getBounds</code>. The union is the
54  * bounds of the virtual device. The following code sample
55  * calculates the bounds of the virtual device.
56  *
57  * <pre>
58  * Rectangle virtualBounds = new Rectangle();
59  * GraphicsEnvironment ge = GraphicsEnvironment.
60  * getLocalGraphicsEnvironment();
61  * GraphicsDevice[] gs =
62  * ge.getScreenDevices();
63  * for (int j = 0; j < gs.length; j++) {
64  * GraphicsDevice gd = gs[j];
65  * GraphicsConfiguration[] gc =
66  * gd.getConfigurations();
67  * for (int i=0; i < gc.length; i++) {
68  * virtualBounds =
69  * virtualBounds.union(gc[i].getBounds());
70  * }
71  * } </pre>
72  *
73  * @see Window
74  * @see Frame
75  * @see GraphicsEnvironment
76  * @see GraphicsDevice
77  */

78 /*
79  * REMIND: What to do about capabilities?
80  * The
81  * capabilities of the device can be determined by enumerating the possible
82  * capabilities and checking if the GraphicsConfiguration
83  * implements the interface for that capability.
84  *
85  * @version 1.38, 12/19/03
86  */

87
88
89 public abstract class GraphicsConfiguration {
90
91     private static BufferCapabilities JavaDoc defaultBufferCaps;
92     private static ImageCapabilities JavaDoc defaultImageCaps;
93     
94     /**
95      * This is an abstract class that cannot be instantiated directly.
96      * Instances must be obtained from a suitable factory or query method.
97      *
98      * @see GraphicsDevice#getConfigurations
99      * @see GraphicsDevice#getDefaultConfiguration
100      * @see GraphicsDevice#getBestConfiguration
101      * @see Graphics2D#getDeviceConfiguration
102      */

103     protected GraphicsConfiguration() {
104     }
105
106     /**
107      * Returns the {@link GraphicsDevice} associated with this
108      * <code>GraphicsConfiguration</code>.
109      * @return a <code>GraphicsDevice</code> object that is
110      * associated with this <code>GraphicsConfiguration</code>.
111      */

112     public abstract GraphicsDevice JavaDoc getDevice();
113
114     /**
115      * Returns a {@link BufferedImage} with a data layout and color model
116      * compatible with this <code>GraphicsConfiguration</code>. This
117      * method has nothing to do with memory-mapping
118      * a device. The returned <code>BufferedImage</code> has
119      * a layout and color model that is closest to this native device
120      * configuration and can therefore be optimally blitted to this
121      * device.
122      * @param width the width of the returned <code>BufferedImage</code>
123      * @param height the height of the returned <code>BufferedImage</code>
124      * @return a <code>BufferedImage</code> whose data layout and color
125      * model is compatible with this <code>GraphicsConfiguration</code>.
126      */

127     public abstract BufferedImage JavaDoc createCompatibleImage(int width, int height);
128
129     /**
130      * Returns a {@link VolatileImage} with a data layout and color model
131      * compatible with this <code>GraphicsConfiguration</code>.
132      * The returned <code>VolatileImage</code>
133      * may have data that is stored optimally for the underlying graphics
134      * device and may therefore benefit from platform-specific rendering
135      * acceleration.
136      * @param width the width of the returned <code>VolatileImage</code>
137      * @param height the height of the returned <code>VolatileImage</code>
138      * @return a <code>VolatileImage</code> whose data layout and color
139      * model is compatible with this <code>GraphicsConfiguration</code>.
140      * @see Component#createVolatileImage(int, int)
141      */

142     public abstract VolatileImage JavaDoc createCompatibleVolatileImage(int width,
143                                 int height);
144
145     /**
146      * Returns a {@link VolatileImage} with a data layout and color model
147      * compatible with this <code>GraphicsConfiguration</code>.
148      * The returned <code>VolatileImage</code>
149      * may have data that is stored optimally for the underlying graphics
150      * device and may therefore benefit from platform-specific rendering
151      * acceleration.
152      * @param width the width of the returned <code>VolatileImage</code>
153      * @param height the height of the returned <code>VolatileImage</code>
154      * @param transparency the specified transparency mode
155      * @return a <code>VolatileImage</code> whose data layout and color
156      * model is compatible with this <code>GraphicsConfiguration</code>.
157      * @throws IllegalArgumentException if the transparency is not a valid value
158      * @see Transparency#OPAQUE
159      * @see Transparency#BITMASK
160      * @see Transparency#TRANSLUCENT
161      * @see Component#createVolatileImage(int, int)
162      * @since 1.5
163      */

164     public abstract VolatileImage JavaDoc
165         createCompatibleVolatileImage(int width, int height, int transparency);
166
167     /**
168      * Returns a {@link VolatileImage} with a data layout and color model
169      * compatible with this <code>GraphicsConfiguration</code>, using
170      * the specified image capabilities.
171      * The returned <code>VolatileImage</code> has
172      * a layout and color model that is closest to this native device
173      * configuration and can therefore be optimally blitted to this
174      * device.
175      * @return a <code>VolatileImage</code> whose data layout and color
176      * model is compatible with this <code>GraphicsConfiguration</code>.
177      * @param width the width of the returned <code>VolatileImage</code>
178      * @param height the height of the returned <code>VolatileImage</code>
179      * @param caps the image capabilities
180      * @exception AWTException if the supplied image capabilities could not
181      * be met by this graphics configuration
182      * @since 1.4
183      */

184     public VolatileImage JavaDoc createCompatibleVolatileImage(int width, int height,
185         ImageCapabilities JavaDoc caps) throws AWTException JavaDoc {
186         // REMIND : check caps
187
return createCompatibleVolatileImage(width, height);
188     }
189
190     /**
191      * Returns a {@link VolatileImage} with a data layout and color model
192      * compatible with this <code>GraphicsConfiguration</code>, using
193      * the specified image capabilities and transparency value.
194      * The returned <code>VolatileImage</code> has
195      * a layout and color model that is closest to this native device
196      * configuration and can therefore be optimally blitted to this
197      * device.
198      * @param width the width of the returned <code>VolatileImage</code>
199      * @param height the height of the returned <code>VolatileImage</code>
200      * @param caps the image capabilities
201      * @param transparency the specified transparency mode
202      * @return a <code>VolatileImage</code> whose data layout and color
203      * model is compatible with this <code>GraphicsConfiguration</code>.
204      * @see Transparency#OPAQUE
205      * @see Transparency#BITMASK
206      * @see Transparency#TRANSLUCENT
207      * @throws IllegalArgumentException if the transparency is not a valid value
208      * @exception AWTException if the supplied image capabilities could not
209      * be met by this graphics configuration
210      * @see Component#createVolatileImage(int, int)
211      * @since 1.5
212      */

213     public VolatileImage JavaDoc createCompatibleVolatileImage(int width, int height,
214     ImageCapabilities JavaDoc caps, int transparency) throws AWTException JavaDoc
215     {
216         // REMIND : check caps
217
return createCompatibleVolatileImage(width, height, transparency);
218     }
219
220     /**
221      * Returns a <code>BufferedImage</code> that supports the specified
222      * transparency and has a data layout and color model
223      * compatible with this <code>GraphicsConfiguration</code>. This
224      * method has nothing to do with memory-mapping
225      * a device. The returned <code>BufferedImage</code> has a layout and
226      * color model that can be optimally blitted to a device
227      * with this <code>GraphicsConfiguration</code>.
228      * @param width the width of the returned <code>BufferedImage</code>
229      * @param height the height of the returned <code>BufferedImage</code>
230      * @param transparency the specified transparency mode
231      * @return a <code>BufferedImage</code> whose data layout and color
232      * model is compatible with this <code>GraphicsConfiguration</code>
233      * and also supports the specified transparency.
234      * @throws IllegalArgumentException if the transparency is not a valid value
235      * @see Transparency#OPAQUE
236      * @see Transparency#BITMASK
237      * @see Transparency#TRANSLUCENT
238      */

239     public abstract BufferedImage JavaDoc createCompatibleImage(int width, int height,
240                                                         int transparency);
241
242     /**
243      * Returns the {@link ColorModel} associated with this
244      * <code>GraphicsConfiguration</code>.
245      * @return a <code>ColorModel</code> object that is associated with
246      * this <code>GraphicsConfiguration</code>.
247      */

248     public abstract ColorModel JavaDoc getColorModel();
249
250     /**
251      * Returns the <code>ColorModel</code> associated with this
252      * <code>GraphicsConfiguration</code> that supports the specified
253      * transparency.
254      * @param transparency the specified transparency mode
255      * @return a <code>ColorModel</code> object that is associated with
256      * this <code>GraphicsConfiguration</code> and supports the
257      * specified transparency or null if the transparency is not a valid
258      * value.
259      * @see Transparency#OPAQUE
260      * @see Transparency#BITMASK
261      * @see Transparency#TRANSLUCENT
262      */

263     public abstract ColorModel JavaDoc getColorModel(int transparency);
264
265     /**
266      * Returns the default {@link AffineTransform} for this
267      * <code>GraphicsConfiguration</code>. This
268      * <code>AffineTransform</code> is typically the Identity transform
269      * for most normal screens. The default <code>AffineTransform</code>
270      * maps coordinates onto the device such that 72 user space
271      * coordinate units measure approximately 1 inch in device
272      * space. The normalizing transform can be used to make
273      * this mapping more exact. Coordinates in the coordinate space
274      * defined by the default <code>AffineTransform</code> for screen and
275      * printer devices have the origin in the upper left-hand corner of
276      * the target region of the device, with X coordinates
277      * increasing to the right and Y coordinates increasing downwards.
278      * For image buffers not associated with a device, such as those not
279      * created by <code>createCompatibleImage</code>,
280      * this <code>AffineTransform</code> is the Identity transform.
281      * @return the default <code>AffineTransform</code> for this
282      * <code>GraphicsConfiguration</code>.
283      */

284     public abstract AffineTransform JavaDoc getDefaultTransform();
285
286     /**
287      *
288      * Returns a <code>AffineTransform</code> that can be concatenated
289      * with the default <code>AffineTransform</code>
290      * of a <code>GraphicsConfiguration</code> so that 72 units in user
291      * space equals 1 inch in device space.
292      * <p>
293      * For a particular {@link Graphics2D}, g, one
294      * can reset the transformation to create
295      * such a mapping by using the following pseudocode:
296      * <pre>
297      * GraphicsConfiguration gc = g.getGraphicsConfiguration();
298      *
299      * g.setTransform(gc.getDefaultTransform());
300      * g.transform(gc.getNormalizingTransform());
301      * </pre>
302      * Note that sometimes this <code>AffineTransform</code> is identity,
303      * such as for printers or metafile output, and that this
304      * <code>AffineTransform</code> is only as accurate as the information
305      * supplied by the underlying system. For image buffers not
306      * associated with a device, such as those not created by
307      * <code>createCompatibleImage</code>, this
308      * <code>AffineTransform</code> is the Identity transform
309      * since there is no valid distance measurement.
310      * @return an <code>AffineTransform</code> to concatenate to the
311      * default <code>AffineTransform</code> so that 72 units in user
312      * space is mapped to 1 inch in device space.
313      */

314     public abstract AffineTransform JavaDoc getNormalizingTransform();
315
316     /**
317      * Returns the bounds of the <code>GraphicsConfiguration</code>
318      * in the device coordinates. In a multi-screen environment
319      * with a virtual device, the bounds can have negative X
320      * or Y origins.
321      * @return the bounds of the area covered by this
322      * <code>GraphicsConfiguration</code>.
323      * @since 1.3
324      */

325     public abstract Rectangle JavaDoc getBounds();
326     
327     private static class DefaultBufferCapabilities extends BufferCapabilities JavaDoc {
328         public DefaultBufferCapabilities(ImageCapabilities JavaDoc imageCaps) {
329             super(imageCaps, imageCaps, null);
330         }
331     }
332     
333     /**
334      * Returns the buffering capabilities of this
335      * <code>GraphicsConfiguration</code>.
336      * @return the buffering capabilities of this graphics
337      * configuration object
338      * @since 1.4
339      */

340     public BufferCapabilities JavaDoc getBufferCapabilities() {
341         if (defaultBufferCaps == null) {
342             defaultBufferCaps = new DefaultBufferCapabilities(
343                 getImageCapabilities());
344         }
345         return defaultBufferCaps;
346     }
347     
348     /**
349      * Returns the image capabilities of this
350      * <code>GraphicsConfiguration</code>.
351      * @return the image capabilities of this graphics
352      * configuration object
353      * @since 1.4
354      */

355     public ImageCapabilities JavaDoc getImageCapabilities() {
356         if (defaultImageCaps == null) {
357             defaultImageCaps = new ImageCapabilities JavaDoc(false);
358         }
359         return defaultImageCaps;
360     }
361     }
362
363
364
Popular Tags