1 /*
2 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.awt;
27
28 import java.awt.geom.AffineTransform;
29 import java.awt.image.BufferedImage;
30 import java.awt.image.ColorModel;
31 import java.awt.image.VolatileImage;
32 import java.awt.image.WritableRaster;
33
34 import sun.awt.image.SunVolatileImage;
35
36 /**
37 * The <code>GraphicsConfiguration</code> class describes the
38 * characteristics of a graphics destination such as a printer or monitor.
39 * There can be many <code>GraphicsConfiguration</code> objects associated
40 * with a single graphics device, representing different drawing modes or
41 * capabilities. The corresponding native structure will vary from platform
42 * to platform. For example, on X11 windowing systems,
43 * each visual is a different <code>GraphicsConfiguration</code>.
44 * On Microsoft Windows, <code>GraphicsConfiguration</code>s represent
45 * PixelFormats available in the current resolution and color depth.
46 * <p>
47 * In a virtual device multi-screen environment in which the desktop
48 * area could span multiple physical screen devices, the bounds of the
49 * <code>GraphicsConfiguration</code> objects are relative to the
50 * virtual coordinate system. When setting the location of a
51 * component, use {@link #getBounds() getBounds} to get the bounds of
52 * the desired <code>GraphicsConfiguration</code> and offset the location
53 * with the coordinates of the <code>GraphicsConfiguration</code>,
54 * as the following code sample illustrates:
55 * </p>
56 *
57 * <pre>
58 * Frame f = new Frame(gc); // where gc is a GraphicsConfiguration
59 * Rectangle bounds = gc.getBounds();
60 * f.setLocation(10 + bounds.x, 10 + bounds.y); </pre>
61 *
62 * <p>
63 * To determine if your environment is a virtual device
64 * environment, call <code>getBounds</code> on all of the
65 * <code>GraphicsConfiguration</code> objects in your system. If
66 * any of the origins of the returned bounds is not (0, 0),
67 * your environment is a virtual device environment.
68 *
69 * <p>
70 * You can also use <code>getBounds</code> to determine the bounds
71 * of the virtual device. To do this, first call <code>getBounds</code> on all
72 * of the <code>GraphicsConfiguration</code> objects in your
73 * system. Then calculate the union of all of the bounds returned
74 * from the calls to <code>getBounds</code>. The union is the
75 * bounds of the virtual device. The following code sample
76 * calculates the bounds of the virtual device.
77 *
78 * <pre>
79 * Rectangle virtualBounds = new Rectangle();
80 * GraphicsEnvironment ge = GraphicsEnvironment.
81 * getLocalGraphicsEnvironment();
82 * GraphicsDevice[] gs =
83 * ge.getScreenDevices();
84 * for (int j = 0; j < gs.length; j++) {
85 * GraphicsDevice gd = gs[j];
86 * GraphicsConfiguration[] gc =
87 * gd.getConfigurations();
88 * for (int i=0; i < gc.length; i++) {
89 * virtualBounds =
90 * virtualBounds.union(gc[i].getBounds());
91 * }
92 * } </pre>
93 *
94 * @see Window
95 * @see Frame
96 * @see GraphicsEnvironment
97 * @see GraphicsDevice
98 */
99 /*
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 */
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 =
150 model.createCompatibleWritableRaster(width, height);
151 return new BufferedImage(model, raster,
152 model.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 {
177 if (getColorModel().getTransparency() == transparency) {
178 return createCompatibleImage(width, height);
179 }
180
181 ColorModel cm = getColorModel(transparency);
182 if (cm == null) {
183 throw new IllegalArgumentException("Unknown transparency: " +
184 transparency);
185 }
186 WritableRaster wr = cm.createCompatibleWritableRaster(width, height);
187 return new BufferedImage(cm, wr, cm.isAlphaPremultiplied(), null);
188 }
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, int height) {
206 VolatileImage vi = null;
207 try {
208 vi = createCompatibleVolatileImage(width, height,
209 null, Transparency.OPAQUE);
210 } catch (AWTException e) {
211 // shouldn't happen: we're passing in null caps
212 assert false;
213 }
214 return vi;
215 }
216
217 /**
218 * Returns a {@link VolatileImage} with a data layout and color model
219 * compatible with this <code>GraphicsConfiguration</code>.
220 * The returned <code>VolatileImage</code>
221 * may have data that is stored optimally for the underlying graphics
222 * device and may therefore benefit from platform-specific rendering
223 * acceleration.
224 * @param width the width of the returned <code>VolatileImage</code>
225 * @param height the height of the returned <code>VolatileImage</code>
226 * @param transparency the specified transparency mode
227 * @return a <code>VolatileImage</code> whose data layout and color
228 * model is compatible with this <code>GraphicsConfiguration</code>.
229 * @throws IllegalArgumentException if the transparency is not a valid value
230 * @see Transparency#OPAQUE
231 * @see Transparency#BITMASK
232 * @see Transparency#TRANSLUCENT
233 * @see Component#createVolatileImage(int, int)
234 * @since 1.5
235 */
236 public VolatileImage createCompatibleVolatileImage(int width, int height,
237 int transparency)
238 {
239 VolatileImage vi = null;
240 try {
241 vi = createCompatibleVolatileImage(width, height, null, transparency);
242 } catch (AWTException e) {
243 // shouldn't happen: we're passing in null caps
244 assert false;
245 }
246 return vi;
247 }
248
249 /**
250 * Returns a {@link VolatileImage} with a data layout and color model
251 * compatible with this <code>GraphicsConfiguration</code>, using
252 * the specified image capabilities.
253 * If the <code>caps</code> parameter is null, it is effectively ignored
254 * and this method will create a VolatileImage without regard to
255 * <code>ImageCapabilities</code> constraints.
256 *
257 * The returned <code>VolatileImage</code> has
258 * a layout and color model that is closest to this native device
259 * configuration and can therefore be optimally blitted to this
260 * device.
261 * @return a <code>VolatileImage</code> whose data layout and color
262 * model is compatible with this <code>GraphicsConfiguration</code>.
263 * @param width the width of the returned <code>VolatileImage</code>
264 * @param height the height of the returned <code>VolatileImage</code>
265 * @param caps the image capabilities
266 * @exception AWTException if the supplied image capabilities could not
267 * be met by this graphics configuration
268 * @since 1.4
269 */
270 public VolatileImage createCompatibleVolatileImage(int width, int height,
271 ImageCapabilities caps) throws AWTException
272 {
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, int height,
305 ImageCapabilities caps, int transparency) throws AWTException
306 {
307 VolatileImage vi =
308 new SunVolatileImage(this, width, height, transparency, caps);
309 if (caps != null && caps.isAccelerated() &&
310 !vi.getCapabilities().isAccelerated())
311 {
312 throw new AWTException("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 BufferCapabilities {
404 public DefaultBufferCapabilities(ImageCapabilities imageCaps) {
405 super(imageCaps, imageCaps, null);
406 }
407 }
408
409 /**
410 * Returns the buffering capabilities of this
411 * <code>GraphicsConfiguration</code>.
412 * @return the buffering capabilities of this graphics
413 * configuration object
414 * @since 1.4
415 */
416 public BufferCapabilities getBufferCapabilities() {
417 if (defaultBufferCaps == null) {
418 defaultBufferCaps = new DefaultBufferCapabilities(
419 getImageCapabilities());
420 }
421 return defaultBufferCaps;
422 }
423
424 /**
425 * Returns the image capabilities of this
426 * <code>GraphicsConfiguration</code>.
427 * @return the image capabilities of this graphics
428 * configuration object
429 * @since 1.4
430 */
431 public ImageCapabilities getImageCapabilities() {
432 if (defaultImageCaps == null) {
433 defaultImageCaps = new ImageCapabilities(false);
434 }
435 return defaultImageCaps;
436 }
437 }
Save This Page