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  ;
11  import java.awt.image.BufferedImage  ;
12  import java.awt.image.ColorModel  ;
13  import java.awt.image.VolatileImage  ;
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   defaultBufferCaps;
92      private static ImageCapabilities   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   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   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   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  
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   createCompatibleVolatileImage(int width, int height,
185         ImageCapabilities   caps) throws AWTException   {
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   createCompatibleVolatileImage(int width, int height,
214     ImageCapabilities   caps, int transparency) throws AWTException  
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   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   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   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   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   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   getBounds();
326     
327     private static class DefaultBufferCapabilities extends BufferCapabilities   {
328         public DefaultBufferCapabilities(ImageCapabilities   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   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   getImageCapabilities() {
356         if (defaultImageCaps == null) {
357             defaultImageCaps = new ImageCapabilities  (false);
358         }
359         return defaultImageCaps;
360     }
361     }
362 
363 
364
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags