001    /* VolatileImage.java -- a hardware-accelerated image buffer
002       Copyright (C) 2002, 2005 Free Software Foundation, Inc.
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.image;
040    
041    import java.awt.Graphics;
042    import java.awt.Graphics2D;
043    import java.awt.GraphicsConfiguration;
044    import java.awt.Image;
045    import java.awt.Transparency;
046    import java.awt.ImageCapabilities;
047    
048    /**
049     * VolatileImage represents a hardware-accelerated graphics buffer.
050     * The native graphics system may free or damage the resources
051     * occupied by a VolatileImage at any time.  As such, one must
052     * frequently check the "validity" of the image buffer's resources.
053     *
054     * A volatile image's "validity" depends on multiple factors.  Its
055     * resources may have become unavailble in which case you must
056     * reallocate them.  If you move the image from one output device to
057     * another, you may need to recreate the image's resources if the new
058     * output device's capabilities don't match the old one's.  Finally,
059     * if the contents of the image's buffer have been damaged you must
060     * re-render the image.
061     *
062     * VolatileImages should always be created using either
063     * Component.createVolatileImage or
064     * GraphicsConfiguration.createCompatibleVolatileImage.
065     */
066    public abstract class VolatileImage extends Image
067      implements Transparency
068    {
069      /**
070       * One of validate's possible return values.  Indicates that the
071       * image buffer matches its graphics configuration's capabilities
072       * and that its resources are initialized and ready to be drawn
073       * into.  Also implies that any existing image rendered to the
074       * buffer is intact and need not be re-rendered.
075       */
076      public static final int IMAGE_OK = 0;
077    
078      /**
079       * One of validate's possible return values.  Indicates that the
080       * image buffer has been restored, meaning that it is valid and
081       * ready-to-use but that its previous contents have been lost.  This
082       * return value implies that the image needs to be re-rendered.
083       */
084      public static final int IMAGE_RESTORED = 1;
085    
086      /**
087       * One of validate's possible return values.  Indicates that the
088       * image buffer type is unsupported by the current graphics
089       * configuration.  The graphics configuration may have changed, for
090       * example if the image moved from one output device to another.
091       * This return value implies that the image buffer's resources
092       * should be re-acquired.
093       */
094      public static final int IMAGE_INCOMPATIBLE = 2;
095    
096      /**
097       * This image's transparency type.  One of Transparency.BITMASK,
098       * Transparency.OPAQUE or Transparency.TRANSLUCENT.
099       *
100       * @since 1.5
101       */
102      protected int transparency;
103    
104      /**
105       * Default constructor.  VolatileImages should not be created
106       * directly.  Rather, you should use Component.createVolatileImage
107       * or GraphicsConfiguration.createCompatibleVolatileImage.
108       */
109      public VolatileImage()
110      {
111      }
112    
113      /**
114       * Returns an image representing the current state of the volatile
115       * image buffer.  The returned image is static meaning that it is
116       * not updated after being created.  It is a snapshot of the
117       * volatile image buffer at the time getSnapshot is called.
118       *
119       * This method, which reads pixels from the volatile image buffer,
120       * may be less-performant than methods that write pixels since
121       * VolatileImages are typically optimized for writing.
122       *
123       * @return a BufferedImage representing this VolatileImage
124       */
125      public abstract BufferedImage getSnapshot();
126    
127      /**
128       * Returns the width of this image buffer.
129       *
130       * @return the width of this VolatileImage
131       */
132      public abstract int getWidth();
133    
134      /**
135       * Returns the height of this image buffer.
136       *
137       * @return the height of this VolatileImage
138       */
139      public abstract int getHeight();
140    
141      /**
142       * Calling this method is equivalent to calling
143       * getSnapshot().getSource().  The ImageProducer produces pixels
144       * from the BufferedImage snapshot and not from the VolatileImage
145       * itself.  Thus, changes to the VolatileImage that occur after this
146       * ImageProducer has been retrieved will not be reflected in the
147       * produced pixels.
148       *
149       * This method, which reads pixels from the volatile image buffer,
150       * may be less-performant than methods that write pixels since
151       * VolatileImages are typically optimized for writing.
152       *
153       * @return an ImageProducer for a static BufferedImage snapshot of
154       * this image buffer
155       */
156      public ImageProducer getSource()
157      {
158        return getSnapshot().getSource();
159      }
160    
161      /**
162       * Releases the system resources taken by this image.
163       */
164      public void flush()
165      {
166      }
167    
168      /**
169       * Returns a Graphics2D object that can be used to draw onto this
170       * image.  This method is present for backwards-compatibility.  It
171       * simply returns the result of createGraphics.
172       *
173       * @return a Graphics2D object that can be used to draw onto this
174       * image
175       */
176      public Graphics getGraphics()
177      {
178        return createGraphics();
179      }
180    
181      /**
182       * Returns a Graphics2D object that can be used to draw onto this
183       * image.
184       *
185       * @return a Graphics2D object that can be used to draw onto this
186       * image
187       */
188      public abstract Graphics2D createGraphics();
189    
190      /**
191       * Validates and restores this image.  If the image buffer has
192       * become unavailable for further use since the last call to
193       * validate, validate will allocate a new image buffer.  The image
194       * is also "validated" against the GraphicsConfiguration parameter.
195       *
196       * "Validating" the image means checking that the capabilities it
197       * requires of the output device are indeed supported by the given
198       * output device.  If the image's characteristics, which can be
199       * highly output device-specific, are not supported by the graphics
200       * configuration, then IMAGE_INCOMPATIBLE will be returned.  This
201       * can happen, for example, if this image was created on one output
202       * device, then validated against a different output device with
203       * different capabilities.  Calling validate with a NULL gc argument
204       * causes validate to skip the validation test.
205       *
206       * @param gc graphics configuration against which to validate or
207       * NULL
208       *
209       * @return a code indicating the result of validation. One of:
210       * <ul>
211       *   <li><code>IMAGE_OK</code> if the image did not need to be
212       *   validated and didn't need to be restored</li>
213       *   <li><code>IMAGE_RESTORED</code> if the image may need to be
214       *   re-rendered.</li>
215       *   <li><code>IMAGE_INCOMPATIBLE</code> if this image's
216       *   requirements are not fulfilled by the graphics configuration
217       *   parameter.  This implies that you need to create a new
218       *   VolatileImage for the different GraphicsConfiguration or
219       *   Component. This return value implies nothing about whether the
220       *   image is valid or needs to be re-rendered.</li>
221       * </ul>
222       */
223      public abstract int validate(GraphicsConfiguration gc);
224    
225      /**
226       * Returns true if the contents of the image buffer have been
227       * damaged or if the image buffer's resources have been reclaimed by
228       * the graphics system.  You should call this method after a series
229       * of rendering operations to or from the image, to see if the image
230       * buffer needs to be revalidated or the image re-rendered.
231       *
232       * @return true if the validate should be called, false otherwise
233       */
234      public abstract boolean contentsLost();
235    
236      /**
237       * Returns the capabilities of this image buffer.
238       *
239       * @return the capabilities of this image buffer
240       */
241      public abstract ImageCapabilities getCapabilities();
242    
243      /**
244       * Returns the transparency type of this image.
245       *
246       * @return Transparency.OPAQUE, Transparency.BITMASK or
247       * Transparency.TRANSLUCENT
248       */
249      public int getTransparency()
250      {
251        return transparency;
252      }
253    }