Back to index...

	/*
	* Copyright (c) 1995, 2013, 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;

	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 NullPointerException 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;
	}
	});
	}
	}

Back to index...