/* VolatileImage.java -- a hardware-accelerated image buffer
   Copyright (C) 2002, 2005 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package java.awt.image;

import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.GraphicsConfiguration;
import java.awt.Image;
import java.awt.Transparency;
import java.awt.ImageCapabilities;

/**
 * VolatileImage represents a hardware-accelerated graphics buffer.
 * The native graphics system may free or damage the resources
 * occupied by a VolatileImage at any time.  As such, one must
 * frequently check the "validity" of the image buffer's resources.
 *
 * A volatile image's "validity" depends on multiple factors.  Its
 * resources may have become unavailble in which case you must
 * reallocate them.  If you move the image from one output device to
 * another, you may need to recreate the image's resources if the new
 * output device's capabilities don't match the old one's.  Finally,
 * if the contents of the image's buffer have been damaged you must
 * re-render the image.
 *
 * VolatileImages should always be created using either
 * Component.createVolatileImage or
 * GraphicsConfiguration.createCompatibleVolatileImage.
 */
public abstract class VolatileImage extends Image
  implements Transparency
{
  /**
   * One of validate's possible return values.  Indicates that the
   * image buffer matches its graphics configuration's capabilities
   * and that its resources are initialized and ready to be drawn
   * into.  Also implies that any existing image rendered to the
   * buffer is intact and need not be re-rendered.
   */
  public static final int IMAGE_OK = 0;

  /**
   * One of validate's possible return values.  Indicates that the
   * image buffer has been restored, meaning that it is valid and
   * ready-to-use but that its previous contents have been lost.  This
   * return value implies that the image needs to be re-rendered.
   */
  public static final int IMAGE_RESTORED = 1;

  /**
   * One of validate's possible return values.  Indicates that the
   * image buffer type is unsupported by the current graphics
   * configuration.  The graphics configuration may have changed, for
   * example if the image moved from one output device to another.
   * This return value implies that the image buffer's resources
   * should be re-acquired.
   */
  public static final int IMAGE_INCOMPATIBLE = 2;

  /**
   * This image's transparency type.  One of Transparency.BITMASK,
   * Transparency.OPAQUE or Transparency.TRANSLUCENT.
   *
   * @since 1.5
   */
  protected int transparency;

  /**
   * Default constructor.  VolatileImages should not be created
   * directly.  Rather, you should use Component.createVolatileImage
   * or GraphicsConfiguration.createCompatibleVolatileImage.
   */
  public VolatileImage()
  {
  }

  /**
   * Returns an image representing the current state of the volatile
   * image buffer.  The returned image is static meaning that it is
   * not updated after being created.  It is a snapshot of the
   * volatile image buffer at the time getSnapshot is called.
   *
   * This method, which reads pixels from the volatile image buffer,
   * may be less-performant than methods that write pixels since
   * VolatileImages are typically optimized for writing.
   *
   * @return a BufferedImage representing this VolatileImage
   */
  public abstract BufferedImage getSnapshot();

  /**
   * Returns the width of this image buffer.
   *
   * @return the width of this VolatileImage
   */
  public abstract int getWidth();

  /**
   * Returns the height of this image buffer.
   *
   * @return the height of this VolatileImage
   */
  public abstract int getHeight();

  /**
   * Calling this method is equivalent to calling
   * getSnapshot().getSource().  The ImageProducer produces pixels
   * from the BufferedImage snapshot and not from the VolatileImage
   * itself.  Thus, changes to the VolatileImage that occur after this
   * ImageProducer has been retrieved will not be reflected in the
   * produced pixels.
   *
   * This method, which reads pixels from the volatile image buffer,
   * may be less-performant than methods that write pixels since
   * VolatileImages are typically optimized for writing.
   *
   * @return an ImageProducer for a static BufferedImage snapshot of
   * this image buffer
   */
  public ImageProducer getSource()
  {
    return getSnapshot().getSource();
  }

  /**
   * Releases the system resources taken by this image.
   */
  public void flush()
  {
  }

  /**
   * Returns a Graphics2D object that can be used to draw onto this
   * image.  This method is present for backwards-compatibility.  It
   * simply returns the result of createGraphics.
   *
   * @return a Graphics2D object that can be used to draw onto this
   * image
   */
  public Graphics getGraphics()
  {
    return createGraphics();
  }

  /**
   * Returns a Graphics2D object that can be used to draw onto this
   * image.
   *
   * @return a Graphics2D object that can be used to draw onto this
   * image
   */
  public abstract Graphics2D createGraphics();

  /**
   * Validates and restores this image.  If the image buffer has
   * become unavailable for further use since the last call to
   * validate, validate will allocate a new image buffer.  The image
   * is also "validated" against the GraphicsConfiguration parameter.
   *
   * "Validating" the image means checking that the capabilities it
   * requires of the output device are indeed supported by the given
   * output device.  If the image's characteristics, which can be
   * highly output device-specific, are not supported by the graphics
   * configuration, then IMAGE_INCOMPATIBLE will be returned.  This
   * can happen, for example, if this image was created on one output
   * device, then validated against a different output device with
   * different capabilities.  Calling validate with a NULL gc argument
   * causes validate to skip the validation test.
   *
   * @param gc graphics configuration against which to validate or
   * NULL
   *
   * @return a code indicating the result of validation. One of:
   * <ul>
   *   <li><code>IMAGE_OK</code> if the image did not need to be
   *   validated and didn't need to be restored</li>
   *   <li><code>IMAGE_RESTORED</code> if the image may need to be
   *   re-rendered.</li>
   *   <li><code>IMAGE_INCOMPATIBLE</code> if this image's
   *   requirements are not fulfilled by the graphics configuration
   *   parameter.  This implies that you need to create a new
   *   VolatileImage for the different GraphicsConfiguration or
   *   Component. This return value implies nothing about whether the
   *   image is valid or needs to be re-rendered.</li>
   * </ul>
   */
  public abstract int validate(GraphicsConfiguration gc);

  /**
   * Returns true if the contents of the image buffer have been
   * damaged or if the image buffer's resources have been reclaimed by
   * the graphics system.  You should call this method after a series
   * of rendering operations to or from the image, to see if the image
   * buffer needs to be revalidated or the image re-rendered.
   *
   * @return true if the validate should be called, false otherwise
   */
  public abstract boolean contentsLost();

  /**
   * Returns the capabilities of this image buffer.
   *
   * @return the capabilities of this image buffer
   */
  public abstract ImageCapabilities getCapabilities();

  /**
   * Returns the transparency type of this image.
   *
   * @return Transparency.OPAQUE, Transparency.BITMASK or
   * Transparency.TRANSLUCENT
   */
  public int getTransparency()
  {
    return transparency;
  }
}