001    /* GraphicsConfiguration.java -- describes characteristics of graphics
002       Copyright (C) 2000, 2001, 2002 Free Software Foundation
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath 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 for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt;
040    
041    import java.awt.geom.AffineTransform;
042    import java.awt.image.BufferedImage;
043    import java.awt.image.ColorModel;
044    import java.awt.image.VolatileImage;
045    
046    /**
047     * This class describes the configuration of various graphics devices, such
048     * as a monitor or printer. Different configurations may exist for the same
049     * device, according to the different native modes supported.
050     *
051     * <p>Virtual devices are supported (for example, in a multiple screen
052     * environment, a virtual device covers all screens simultaneously); the
053     * configuration will have a non-zero relative coordinate system in such
054     * a case.
055     *
056     * @author Eric Blake (ebb9@email.byu.edu)
057     * @see Window
058     * @see Frame
059     * @see GraphicsEnvironment
060     * @see GraphicsDevice
061     * @since 1.0
062     * @status updated to 1.4
063     */
064    public abstract class GraphicsConfiguration
065    {
066    
067      /** The cached image capabilities. */
068      private ImageCapabilities imageCapabilities;
069    
070      /** The cached buffer capabilities. */
071      private BufferCapabilities bufferCapabilities;
072    
073      /**
074       * The default constructor.
075       *
076       * @see GraphicsDevice#getConfigurations()
077       * @see GraphicsDevice#getDefaultConfiguration()
078       * @see GraphicsDevice#getBestConfiguration(GraphicsConfigTemplate)
079       * @see Graphics2D#getDeviceConfiguration()
080       */
081      protected GraphicsConfiguration ()
082      {
083      }
084    
085      /**
086       * Gets the associated device that this configuration describes.
087       *
088       * @return the device
089       */
090      public abstract GraphicsDevice getDevice();
091    
092      /**
093       * Returns a buffered image optimized to this device, so that blitting can
094       * be supported in the buffered image.
095       *
096       * @param w the width of the buffer
097       * @param h the height of the buffer
098       * @return the buffered image, or null if none is supported
099       */
100      public abstract BufferedImage createCompatibleImage(int w, int h);
101    
102      /**
103       * Returns a buffered volatile image optimized to this device, so that
104       * blitting can be supported in the buffered image. Because the buffer is
105       * volatile, it can be optimized by native graphics accelerators.
106       *
107       * @param w the width of the buffer
108       * @param h the height of the buffer
109       * @return the buffered image, or null if none is supported
110       * @see Component#createVolatileImage(int, int)
111       * @since 1.4
112       */
113      public abstract VolatileImage createCompatibleVolatileImage(int w, int h);
114    
115      /**
116       * Returns a buffered volatile image optimized to this device, and with the
117       * given capabilities, so that blitting can be supported in the buffered
118       * image. Because the buffer is volatile, it can be optimized by native
119       * graphics accelerators.
120       *
121       * @param w the width of the buffer
122       * @param h the height of the buffer
123       * @param caps the desired capabilities of the image buffer
124       * @return the buffered image, or null if none is supported
125       * @throws AWTException if the capabilities cannot be met
126       * @since 1.4
127       */
128      public VolatileImage createCompatibleVolatileImage(int w, int h,
129                                                         ImageCapabilities caps)
130        throws AWTException
131      {
132        // Must be overridden by implementations to check caps.
133        return createCompatibleVolatileImage(w, h);
134      }
135    
136      /**
137       * Returns a buffered volatile image optimized to this device, and
138       * with the given transparency. Because the buffer is volatile, it
139       * can be optimized by native graphics accelerators.
140       *
141       * @param width the width of the buffer
142       * @param height the height of the buffer
143       * @param transparency the transparency value for the buffer
144       * @return the buffered image, or null if none is supported
145       * @since 1.5
146       */
147      public abstract VolatileImage createCompatibleVolatileImage(int width,
148                                                                  int height,
149                                                                  int transparency);
150    
151      /**
152       * Creates a volatile image with the specified capabilities and transparency.
153       * If the backend cannot meet the requested capabilities and transparency,
154       * an AWTException is thrown.
155       *
156       * @param width the width of the image
157       * @param height the height of the image
158       * @param caps the requested capabilities
159       * @param transparency the required transparency
160       *
161       * @return a volatile image with the specified capabilites and transparency
162       *
163       * @throws AWTException if the required capabilities and transparency cannot
164       *         be met
165       *
166       * @since 1.5
167       */
168      public VolatileImage createCompatibleVolatileImage(int width, int height,
169                                                         ImageCapabilities caps,
170                                                         int transparency)
171        throws AWTException
172      {
173        // Must be overridden by implementations to check caps.
174        return createCompatibleVolatileImage(width, height, transparency);
175      }
176    
177      /**
178       * Returns a buffered image optimized to this device, and with the specified
179       * transparency, so that blitting can be supported in the buffered image.
180       *
181       * @param w the width of the buffer
182       * @param h the height of the buffer
183       * @param transparency the transparency of the buffer
184       * @return the buffered image, or null if none is supported
185       * @see Transparency#OPAQUE
186       * @see Transparency#BITMASK
187       * @see Transparency#TRANSLUCENT
188       */
189      public abstract BufferedImage createCompatibleImage(int w, int h,
190                                                          int transparency);
191    
192      /**
193       * Gets the color model of the corresponding device.
194       *
195       * @return the color model
196       */
197      public abstract ColorModel getColorModel();
198    
199      /**
200       * Gets a color model for the corresponding device which supports the desired
201       * transparency level.
202       *
203       * @param transparency the transparency of the model
204       * @return the color model, with transparency
205       * @see Transparency#OPAQUE
206       * @see Transparency#BITMASK
207       * @see Transparency#TRANSLUCENT
208       */
209      public abstract ColorModel getColorModel(int transparency);
210    
211      /**
212       * Returns a transform that maps user coordinates to device coordinates. The
213       * preferred mapping is about 72 user units to 1 inch (2.54 cm) of physical
214       * space. This is often the identity transform. The device coordinates have
215       * the origin at the upper left, with increasing x to the right, and
216       * increasing y to the bottom.
217       *
218       * @return the transformation from user space to device space
219       * @see #getNormalizingTransform()
220       */
221      public abstract AffineTransform getDefaultTransform();
222    
223      /**
224       * Returns a transform that maps user coordinates to device coordinates. The
225       * exact mapping is 72 user units to 1 inch (2.54 cm) of physical space.
226       * This is often the identity transform. The device coordinates have the
227       * origin at the upper left, with increasing x to the right, and increasing
228       * y to the bottom. Note that this is more accurate (and thus, sometimes more
229       * costly) than the default transform.
230       *
231       * @return the normalized transformation from user space to device space
232       * @see #getDefaultTransform()
233       */
234      public abstract AffineTransform getNormalizingTransform();
235    
236      /**
237       * Returns the bounds of the configuration, in device coordinates. If this
238       * is a virtual device (for example, encompassing several screens), the
239       * bounds may have a non-zero origin.
240       *
241       * @return the device bounds
242       * @since 1.3
243       */
244      public abstract Rectangle getBounds();
245    
246      /**
247       * Returns the buffering capabilities of this configuration.
248       *
249       * @return the buffer capabilities
250       * @since 1.4
251       */
252      public BufferCapabilities getBufferCapabilities()
253      {
254        if (imageCapabilities == null)
255          getImageCapabilities();
256    
257        if (bufferCapabilities == null)
258          bufferCapabilities = new BufferCapabilities(imageCapabilities,
259                                                      imageCapabilities, null);
260        return bufferCapabilities;
261      }
262    
263      /**
264       * Returns the imaging capabilities of this configuration.
265       *
266       * @return the image capabilities
267       * @since 1.4
268       */
269      public ImageCapabilities getImageCapabilities()
270      {
271        if (imageCapabilities == null)
272          imageCapabilities = new ImageCapabilities(false);
273        return imageCapabilities;
274      }
275    } // class GraphicsConfiguration