001/* VolatileImage.java -- a hardware-accelerated image buffer
002   Copyright (C) 2002, 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt.image;
040
041import java.awt.Graphics;
042import java.awt.Graphics2D;
043import java.awt.GraphicsConfiguration;
044import java.awt.Image;
045import java.awt.Transparency;
046import 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 */
066public 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}