/*

 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt.image;

import java.awt.Color;

import java.awt.Graphics;

import java.awt.Graphics2D;

import java.awt.GraphicsConfiguration;

import java.awt.GraphicsDevice;

import java.awt.Image;

import java.awt.ImageCapabilities;

import java.awt.Toolkit;

import java.awt.Transparency;

/**

 * VolatileImage is an image which can lose its

 * contents at any time due to circumstances beyond the control of the

 * application (e.g., situations caused by the operating system or by

 * other applications). Because of the potential for hardware acceleration,

 * a VolatileImage object can have significant performance benefits on

 * some platforms.

 * <p>

 * The drawing surface of an image (the memory where the image contents

 * actually reside) can be lost or invalidated, causing the contents of that

 * memory to go away.  The drawing surface thus needs to be restored

 * or recreated and the contents of that surface need to be

 * re-rendered.  VolatileImage provides an interface for

 * allowing the user to detect these problems and fix them

 * when they occur.

 * <p>

 * When a VolatileImage object is created, limited system resources

 * such as video memory (VRAM) may be allocated in order to support

 * the image.

 * When a VolatileImage object is no longer used, it may be

 * garbage-collected and those system resources will be returned,

 * but this process does not happen at guaranteed times.

 * Applications that create many VolatileImage objects (for example,

 * a resizing window may force recreation of its back buffer as the

 * size changes) may run out of optimal system resources for new

 * VolatileImage objects simply because the old objects have not

 * yet been removed from the system.

 * (New VolatileImage objects may still be created, but they

 * may not perform as well as those created in accelerated

 * memory).

 * The flush method may be called at any time to proactively release

 * the resources used by a VolatileImage so that it does not prevent

 * subsequent VolatileImage objects from being accelerated.

 * In this way, applications can have more control over the state

 * of the resources taken up by obsolete VolatileImage objects.

 * <p>

 * This image should not be subclassed directly but should be created

 * by using the {@link java.awt.Component#createVolatileImage(int, int)

 * Component.createVolatileImage} or

 * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)

 * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.

 * <P>

 * An example of using a VolatileImage object follows:

 * <pre>

 * // image creation

 * VolatileImage vImg = createVolatileImage(w, h);

 *

 *

 * // rendering to the image

 * void renderOffscreen() {

 *      do {

 *          if (vImg.validate(getGraphicsConfiguration()) ==

 *              VolatileImage.IMAGE_INCOMPATIBLE)

 *          {

 *              // old vImg doesn't work with new GraphicsConfig; re-create it

 *              vImg = createVolatileImage(w, h);

 *          }

 *          Graphics2D g = vImg.createGraphics();

 *          //

 *          // miscellaneous rendering commands...

 *          //

 *          g.dispose();

 *      } while (vImg.contentsLost());

 * }

 *

 *

 * // copying from the image (here, gScreen is the Graphics

 * // object for the onscreen window)

 * do {

 *      int returnCode = vImg.validate(getGraphicsConfiguration());

 *      if (returnCode == VolatileImage.IMAGE_RESTORED) {

 *          // Contents need to be restored

 *          renderOffscreen();      // restore contents

 *      } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {

 *          // old vImg doesn't work with new GraphicsConfig; re-create it

 *          vImg = createVolatileImage(w, h);

 *          renderOffscreen();

 *      }

 *      gScreen.drawImage(vImg, 0, 0, this);

 * } while (vImg.contentsLost());

 * </pre>

 * <P>

 * Note that this class subclasses from the {@link Image} class, which

 * includes methods that take an {@link ImageObserver} parameter for

 * asynchronous notifications as information is received from

 * a potential {@link ImageProducer}.  Since this <code>VolatileImage</code>

 * is not loaded from an asynchronous source, the various methods that take

 * an <code>ImageObserver</code> parameter will behave as if the data has

 * already been obtained from the <code>ImageProducer</code>.

 * Specifically, this means that the return values from such methods

 * will never indicate that the information is not yet available and

 * the <code>ImageObserver</code> used in such methods will never

 * need to be recorded for an asynchronous callback notification.

 * @since 1.4

 */

public abstract class VolatileImage extends Image implements Transparency

{

    // Return codes for validate() method

    /**

     * Validated image is ready to use as-is.

     */

    public static final int IMAGE_OK = 0;

    /**

     * Validated image has been restored and is now ready to use.

     * Note that restoration causes contents of the image to be lost.

     */

    public static final int IMAGE_RESTORED = 1;

    /**

     * Validated image is incompatible with supplied

     * <code>GraphicsConfiguration</code> object and should be

     * re-created as appropriate.  Usage of the image as-is

     * after receiving this return code from <code>validate</code>

     * is undefined.

     */

    public static final int IMAGE_INCOMPATIBLE = 2;

    /**

     * Returns a static snapshot image of this object.  The

     * <code>BufferedImage</code> returned is only current with

     * the <code>VolatileImage</code> at the time of the request

     * and will not be updated with any future changes to the

     * <code>VolatileImage</code>.

     * @return a {@link BufferedImage} representation of this

     *          <code>VolatileImage</code>

     * @see BufferedImage

     */

    public abstract BufferedImage getSnapshot();

    /**

     * Returns the width of the <code>VolatileImage</code>.

     * @return the width of this <code>VolatileImage</code>.

     */

    public abstract int getWidth();

    /**

     * Returns the height of the <code>VolatileImage</code>.

     * @return the height of this <code>VolatileImage</code>.

     */

    public abstract int getHeight();

    // Image overrides

    /**

     * This returns an ImageProducer for this VolatileImage.

     * Note that the VolatileImage object is optimized for

     * rendering operations and blitting to the screen or other

     * VolatileImage objects, as opposed to reading back the

     * pixels of the image.  Therefore, operations such as

     * <code>getSource</code> may not perform as fast as

     * operations that do not rely on reading the pixels.

     * Note also that the pixel values read from the image are current

     * with those in the image only at the time that they are

     * retrieved. This method takes a snapshot

     * of the image at the time the request is made and the

     * ImageProducer object returned works with

     * that static snapshot image, not the original VolatileImage.

     * Calling getSource()

     * is equivalent to calling getSnapshot().getSource().

     * @return an {@link ImageProducer} that can be used to produce the

     * pixels for a <code>BufferedImage</code> representation of

     * this Image.

     * @see ImageProducer

     * @see #getSnapshot()

     */

    public ImageProducer getSource() {

        // REMIND: Make sure this functionality is in line with the

        // spec.  In particular, we are returning the Source for a

        // static image (the snapshot), not a changing image (the

        // VolatileImage).  So if the user expects the Source to be

        // up-to-date with the current contents of the VolatileImage,

        // they will be disappointed...

        // REMIND: This assumes that getSnapshot() returns something

        // valid and not the default null object returned by this class

        // (so it assumes that the actual VolatileImage object is

        // subclassed off something that does the right thing

        // (e.g., SunVolatileImage).

        return getSnapshot().getSource();

    }

    // REMIND: if we want any decent performance for getScaledInstance(),

    // we should override the Image implementation of it...

    /**

     * This method returns a {@link Graphics2D}, but is here

     * for backwards compatibility.  {@link #createGraphics() createGraphics} is more

     * convenient, since it is declared to return a

     * <code>Graphics2D</code>.

     * @return a <code>Graphics2D</code>, which can be used to draw into

     *          this image.

     */

    public Graphics getGraphics() {

        return createGraphics();

    }

    /**

     * Creates a <code>Graphics2D</code>, which can be used to draw into

     * this <code>VolatileImage</code>.

     * @return a <code>Graphics2D</code>, used for drawing into this

     *          image.

     */

    public abstract Graphics2D createGraphics();

    // Volatile management methods

    /**

     * Attempts to restore the drawing surface of the image if the surface

     * had been lost since the last <code>validate</code> call.  Also

     * validates this image against the given GraphicsConfiguration

     * parameter to see whether operations from this image to the

     * GraphicsConfiguration are compatible.  An example of an

     * incompatible combination might be a situation where a VolatileImage

     * object was created on one graphics device and then was used

     * to render to a different graphics device.  Since VolatileImage

     * objects tend to be very device-specific, this operation might

     * not work as intended, so the return code from this validate

     * call would note that incompatibility.  A null or incorrect

     * value for gc may cause incorrect values to be returned from

     * <code>validate</code> and may cause later problems with rendering.

     *

     * @param   gc   a <code>GraphicsConfiguration</code> object for this

     *          image to be validated against.  A null gc implies that the

     *          validate method should skip the compatibility test.

     * @return  <code>IMAGE_OK</code> if the image did not need validation<BR>

     *          <code>IMAGE_RESTORED</code> if the image needed restoration.

     *          Restoration implies that the contents of the image may have

     *          been affected and the image may need to be re-rendered.<BR>

     *          <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible

     *          with the <code>GraphicsConfiguration</code> object passed

     *          into the <code>validate</code> method.  Incompatibility

     *          implies that the image may need to be recreated with a

     *          new <code>Component</code> or

     *          <code>GraphicsConfiguration</code> in order to get an image

     *          that can be used successfully with this

     *          <code>GraphicsConfiguration</code>.

     *          An incompatible image is not checked for whether restoration

     *          was necessary, so the state of the image is unchanged

     *          after a return value of <code>IMAGE_INCOMPATIBLE</code>

     *          and this return value implies nothing about whether the

     *          image needs to be restored.

     * @see java.awt.GraphicsConfiguration

     * @see java.awt.Component

     * @see #IMAGE_OK

     * @see #IMAGE_RESTORED

     * @see #IMAGE_INCOMPATIBLE

     */

    public abstract int validate(GraphicsConfiguration gc);

    /**

     * Returns <code>true</code> if rendering data was lost since last

     * <code>validate</code> call.  This method should be called by the

     * application at the end of any series of rendering operations to

     * or from the image to see whether

     * the image needs to be validated and the rendering redone.

     * @return <code>true</code> if the drawing surface needs to be restored;

     * <code>false</code> otherwise.

     */

    public abstract boolean contentsLost();

    /**

     * Returns an ImageCapabilities object which can be

     * inquired as to the specific capabilities of this

     * VolatileImage.  This would allow programmers to find

     * out more runtime information on the specific VolatileImage

     * object that they have created.  For example, the user

     * might create a VolatileImage but the system may have

     * no video memory left for creating an image of that

     * size, so although the object is a VolatileImage, it is

     * not as accelerated as other VolatileImage objects on

     * this platform might be.  The user might want that

     * information to find other solutions to their problem.

     * @return an <code>ImageCapabilities</code> object that contains

     *         the capabilities of this <code>VolatileImage</code>.

     * @since 1.4

     */

    public abstract ImageCapabilities getCapabilities();

    /**

     * The transparency value with which this image was created.

     * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,

     *      int,int)

     * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,

     *      int,ImageCapabilities,int)

     * @see Transparency

     * @since 1.5

     */

    protected int transparency = TRANSLUCENT;

    /**

     * Returns the transparency.  Returns either OPAQUE, BITMASK,

     * or TRANSLUCENT.

     * @return the transparency of this <code>VolatileImage</code>.

     * @see Transparency#OPAQUE

     * @see Transparency#BITMASK

     * @see Transparency#TRANSLUCENT

     * @since 1.5

     */

    public int getTransparency() {

        return transparency;

    }

}