--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/awt/Image.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,353 @@
+/*
+ * Copyright 1995-2007 Sun Microsystems, Inc. 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. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+package java.awt;
+
+import java.awt.image.ImageProducer;
+import java.awt.image.ImageObserver;
+import java.awt.image.ImageFilter;
+import java.awt.image.FilteredImageSource;
+import java.awt.image.AreaAveragingScaleFilter;
+import java.awt.image.ReplicateScaleFilter;
+
+import sun.awt.image.SurfaceManager;
+
+/**
+ * The abstract class <code>Image</code> is the superclass of all
+ * classes that represent graphical images. The image must be
+ * obtained in a platform-specific manner.
+ *
+ * @author Sami Shaio
+ * @author Arthur van Hoff
+ * @since JDK1.0
+ */
+public abstract class Image {
+
+ /**
+ * convenience object; we can use this single static object for
+ * all images that do not create their own image caps; it holds the
+ * default (unaccelerated) properties.
+ */
+ private static ImageCapabilities defaultImageCaps =
+ new ImageCapabilities(false);
+
+ /**
+ * Priority for accelerating this image. Subclasses are free to
+ * set different default priorities and applications are free to
+ * set the priority for specific images via the
+ * <code>setAccelerationPriority(float)</code> method.
+ * @since 1.5
+ */
+ protected float accelerationPriority = .5f;
+
+ /**
+ * Determines the width of the image. If the width is not yet known,
+ * this method returns <code>-1</code> and the specified
+ * <code>ImageObserver</code> object is notified later.
+ * @param observer an object waiting for the image to be loaded.
+ * @return the width of this image, or <code>-1</code>
+ * if the width is not yet known.
+ * @see java.awt.Image#getHeight
+ * @see java.awt.image.ImageObserver
+ */
+ public abstract int getWidth(ImageObserver observer);
+
+ /**
+ * Determines the height of the image. If the height is not yet known,
+ * this method returns <code>-1</code> and the specified
+ * <code>ImageObserver</code> object is notified later.
+ * @param observer an object waiting for the image to be loaded.
+ * @return the height of this image, or <code>-1</code>
+ * if the height is not yet known.
+ * @see java.awt.Image#getWidth
+ * @see java.awt.image.ImageObserver
+ */
+ public abstract int getHeight(ImageObserver observer);
+
+ /**
+ * Gets the object that produces the pixels for the image.
+ * This method is called by the image filtering classes and by
+ * methods that perform image conversion and scaling.
+ * @return the image producer that produces the pixels
+ * for this image.
+ * @see java.awt.image.ImageProducer
+ */
+ public abstract ImageProducer getSource();
+
+ /**
+ * Creates a graphics context for drawing to an off-screen image.
+ * This method can only be called for off-screen images.
+ * @return a graphics context to draw to the off-screen image.
+ * @exception UnsupportedOperationException if called for a
+ * non-off-screen image.
+ * @see java.awt.Graphics
+ * @see java.awt.Component#createImage(int, int)
+ */
+ public abstract Graphics getGraphics();
+
+ /**
+ * Gets a property of this image by name.
+ * <p>
+ * Individual property names are defined by the various image
+ * formats. If a property is not defined for a particular image, this
+ * method returns the <code>UndefinedProperty</code> object.
+ * <p>
+ * If the properties for this image are not yet known, this method
+ * returns <code>null</code>, and the <code>ImageObserver</code>
+ * object is notified later.
+ * <p>
+ * The property name <code>"comment"</code> should be used to store
+ * an optional comment which can be presented to the application as a
+ * description of the image, its source, or its author.
+ * @param name a property name.
+ * @param observer an object waiting for this image to be loaded.
+ * @return the value of the named property.
+ * @throws <code>NullPointerException</code> if the property name is null.
+ * @see java.awt.image.ImageObserver
+ * @see java.awt.Image#UndefinedProperty
+ */
+ public abstract Object getProperty(String name, ImageObserver observer);
+
+ /**
+ * The <code>UndefinedProperty</code> object should be returned whenever a
+ * property which was not defined for a particular image is fetched.
+ */
+ public static final Object UndefinedProperty = new Object();
+
+ /**
+ * Creates a scaled version of this image.
+ * A new <code>Image</code> object is returned which will render
+ * the image at the specified <code>width</code> and
+ * <code>height</code> by default. The new <code>Image</code> object
+ * may be loaded asynchronously even if the original source image
+ * has already been loaded completely.
+ *
+ * <p>
+ *
+ * If either <code>width</code>
+ * or <code>height</code> is a negative number then a value is
+ * substituted to maintain the aspect ratio of the original image
+ * dimensions. If both <code>width</code> and <code>height</code>
+ * are negative, then the original image dimensions are used.
+ *
+ * @param width the width to which to scale the image.
+ * @param height the height to which to scale the image.
+ * @param hints flags to indicate the type of algorithm to use
+ * for image resampling.
+ * @return a scaled version of the image.
+ * @exception IllegalArgumentException if <code>width</code>
+ * or <code>height</code> is zero.
+ * @see java.awt.Image#SCALE_DEFAULT
+ * @see java.awt.Image#SCALE_FAST
+ * @see java.awt.Image#SCALE_SMOOTH
+ * @see java.awt.Image#SCALE_REPLICATE
+ * @see java.awt.Image#SCALE_AREA_AVERAGING
+ * @since JDK1.1
+ */
+ public Image getScaledInstance(int width, int height, int hints) {
+ ImageFilter filter;
+ if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
+ filter = new AreaAveragingScaleFilter(width, height);
+ } else {
+ filter = new ReplicateScaleFilter(width, height);
+ }
+ ImageProducer prod;
+ prod = new FilteredImageSource(getSource(), filter);
+ return Toolkit.getDefaultToolkit().createImage(prod);
+ }
+
+ /**
+ * Use the default image-scaling algorithm.
+ * @since JDK1.1
+ */
+ public static final int SCALE_DEFAULT = 1;
+
+ /**
+ * Choose an image-scaling algorithm that gives higher priority
+ * to scaling speed than smoothness of the scaled image.
+ * @since JDK1.1
+ */
+ public static final int SCALE_FAST = 2;
+
+ /**
+ * Choose an image-scaling algorithm that gives higher priority
+ * to image smoothness than scaling speed.
+ * @since JDK1.1
+ */
+ public static final int SCALE_SMOOTH = 4;
+
+ /**
+ * Use the image scaling algorithm embodied in the
+ * <code>ReplicateScaleFilter</code> class.
+ * The <code>Image</code> object is free to substitute a different filter
+ * that performs the same algorithm yet integrates more efficiently
+ * into the imaging infrastructure supplied by the toolkit.
+ * @see java.awt.image.ReplicateScaleFilter
+ * @since JDK1.1
+ */
+ public static final int SCALE_REPLICATE = 8;
+
+ /**
+ * Use the Area Averaging image scaling algorithm. The
+ * image object is free to substitute a different filter that
+ * performs the same algorithm yet integrates more efficiently
+ * into the image infrastructure supplied by the toolkit.
+ * @see java.awt.image.AreaAveragingScaleFilter
+ * @since JDK1.1
+ */
+ public static final int SCALE_AREA_AVERAGING = 16;
+
+ /**
+ * Flushes all reconstructable resources being used by this Image object.
+ * This includes any pixel data that is being cached for rendering to
+ * the screen as well as any system resources that are being used
+ * to store data or pixels for the image if they can be recreated.
+ * The image is reset to a state similar to when it was first created
+ * so that if it is again rendered, the image data will have to be
+ * recreated or fetched again from its source.
+ * <p>
+ * Examples of how this method affects specific types of Image object:
+ * <ul>
+ * <li>
+ * BufferedImage objects leave the primary Raster which stores their
+ * pixels untouched, but flush any information cached about those
+ * pixels such as copies uploaded to the display hardware for
+ * accelerated blits.
+ * <li>
+ * Image objects created by the Component methods which take a
+ * width and height leave their primary buffer of pixels untouched,
+ * but have all cached information released much like is done for
+ * BufferedImage objects.
+ * <li>
+ * VolatileImage objects release all of their pixel resources
+ * including their primary copy which is typically stored on
+ * the display hardware where resources are scarce.
+ * These objects can later be restored using their
+ * {@link java.awt.image.VolatileImage#validate validate}
+ * method.
+ * <li>
+ * Image objects created by the Toolkit and Component classes which are
+ * loaded from files, URLs or produced by an {@link ImageProducer}
+ * are unloaded and all local resources are released.
+ * These objects can later be reloaded from their original source
+ * as needed when they are rendered, just as when they were first
+ * created.
+ * </ul>
+ */
+ public void flush() {
+ if (surfaceManager != null) {
+ surfaceManager.flush();
+ }
+ }
+
+ /**
+ * Returns an ImageCapabilities object which can be
+ * inquired as to the capabilities of this
+ * Image on the specified GraphicsConfiguration.
+ * This allows programmers to find
+ * out more runtime information on the specific Image
+ * object that they have created. For example, the user
+ * might create a BufferedImage but the system may have
+ * no video memory left for creating an image of that
+ * size on the given GraphicsConfiguration, so although the object
+ * may be acceleratable in general, it
+ * does not have that capability on this GraphicsConfiguration.
+ * @param gc a <code>GraphicsConfiguration</code> object. A value of null
+ * for this parameter will result in getting the image capabilities
+ * for the default <code>GraphicsConfiguration</code>.
+ * @return an <code>ImageCapabilities</code> object that contains
+ * the capabilities of this <code>Image</code> on the specified
+ * GraphicsConfiguration.
+ * @see java.awt.image.VolatileImage#getCapabilities()
+ * VolatileImage.getCapabilities()
+ * @since 1.5
+ */
+ public ImageCapabilities getCapabilities(GraphicsConfiguration gc) {
+ if (surfaceManager != null) {
+ return surfaceManager.getCapabilities(gc);
+ }
+ // Note: this is just a default object that gets returned in the
+ // absence of any more specific information from a surfaceManager.
+ // Subclasses of Image should either override this method or
+ // make sure that they always have a non-null SurfaceManager
+ // to return an ImageCapabilities object that is appropriate
+ // for their given subclass type.
+ return defaultImageCaps;
+ }
+
+ /**
+ * Sets a hint for this image about how important acceleration is.
+ * This priority hint is used to compare to the priorities of other
+ * Image objects when determining how to use scarce acceleration
+ * resources such as video memory. When and if it is possible to
+ * accelerate this Image, if there are not enough resources available
+ * to provide that acceleration but enough can be freed up by
+ * de-accelerating some other image of lower priority, then that other
+ * Image may be de-accelerated in deference to this one. Images
+ * that have the same priority take up resources on a first-come,
+ * first-served basis.
+ * @param priority a value between 0 and 1, inclusive, where higher
+ * values indicate more importance for acceleration. A value of 0
+ * means that this Image should never be accelerated. Other values
+ * are used simply to determine acceleration priority relative to other
+ * Images.
+ * @throws IllegalArgumentException if <code>priority</code> is less
+ * than zero or greater than 1.
+ * @since 1.5
+ */
+ public void setAccelerationPriority(float priority) {
+ if (priority < 0 || priority > 1) {
+ throw new IllegalArgumentException("Priority must be a value " +
+ "between 0 and 1, inclusive");
+ }
+ accelerationPriority = priority;
+ if (surfaceManager != null) {
+ surfaceManager.setAccelerationPriority(accelerationPriority);
+ }
+ }
+
+ /**
+ * Returns the current value of the acceleration priority hint.
+ * @see #setAccelerationPriority(float priority) setAccelerationPriority
+ * @return value between 0 and 1, inclusive, which represents the current
+ * priority value
+ * @since 1.5
+ */
+ public float getAccelerationPriority() {
+ return accelerationPriority;
+ }
+
+ SurfaceManager surfaceManager;
+
+ static {
+ SurfaceManager.setImageAccessor(new SurfaceManager.ImageAccessor() {
+ public SurfaceManager getSurfaceManager(Image img) {
+ return img.surfaceManager;
+ }
+ public void setSurfaceManager(Image img, SurfaceManager mgr) {
+ img.surfaceManager = mgr;
+ }
+ });
+ }
+}