awt/java/awt/Image.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
/**
 * @author Igor V. Stolyarov
 * @version $Revision$
 */
package java.awt;

import java.awt.image.AreaAveragingScaleFilter;
import java.awt.image.FilteredImageSource;
import java.awt.image.ImageFilter;
import java.awt.image.ImageObserver;
import java.awt.image.ImageProducer;
import java.awt.image.ReplicateScaleFilter;

import org.apache.harmony.awt.internal.nls.Messages;

/**
 * The Image abstract class represents the graphic images. 
 */
public abstract class Image {

    /** 
     * The UndefinedProperty object should be returned if
     * property is not defined for a particular image. 
     */
    public static final Object UndefinedProperty = new Object();  //$NON-LOCK-1$

    /** 
     * The Constant SCALE_DEFAULT indicates the default image
     * scaling algorithm. 
     */
    public static final int SCALE_DEFAULT = 1;

    /** 
     * The Constant SCALE_FAST indicates an image scaling algorithm which 
     * places a higher priority on scaling speed than on the image's smoothness. 
     */
    public static final int SCALE_FAST = 2;

    /** 
     * The Constant SCALE_SMOOTH indicates an image scaling algorithm which 
     * places a higher priority on image smoothness than on scaling speed. 
     */
    public static final int SCALE_SMOOTH = 4;

    /** 
     * The Constant SCALE_REPLICATE indicates the image scaling 
     * algorithm in the ReplicateScaleFilter class. 
     */
    public static final int SCALE_REPLICATE = 8;

    /** 
     * The Constant SCALE_AREA_AVERAGING indicates  
     * the area averaging image scaling algorithm. 
     */
    public static final int SCALE_AREA_AVERAGING = 16;

    /** 
     * The acceleration priority indicates image acceleration.   
     */
    protected float accelerationPriority = 0.5f;

    /** The Constant capabilities. */
    private static final ImageCapabilities capabilities = new ImageCapabilities(false);

    /**
     * Gets the image property with the specified name.
     * The UndefinedProperty object should be return if the property is 
     * not specified for this image.  The return value should be null if the
     * property is currently unknown yet and the specified ImageObserver is
     * to be notified later. 
     * 
     * @param name the name of image's property.
     * @param observer the ImageObserver.
     * 
     * @return the Object which represents value of the specified property.
     */
    public abstract Object getProperty(String name, ImageObserver observer);

    /**
     * Gets the ImageProducer object which represents data of this Image.
     * 
     * @return the ImageProducer object which represents data of this Image.
     */
    public abstract ImageProducer getSource();

    /**
     * Gets the width of this image. The specified ImageObserver object 
     * is notified when the width of this image is available.
     * 
     * @param observer the ImageObserver object which is 
     * is notified when the width of this image is available.
     * 
     * @return the width of image, or -1 if the width of this image 
     * is not available.
     */
    public abstract int getWidth(ImageObserver observer);

    /**
     * Gets the height of this image. The specified ImageObserver object 
     * is notified when the height of this image is available.
     * 
     * @param observer the ImageObserver object which is 
     * is notified when the height of this image is available.
     * 
     * @return the height of image, or -1 if the height of this image 
     * is not available.
     */
    public abstract int getHeight(ImageObserver observer);

    /**
     * Gets the scaled instance of this Image. This method returns 
     * an Image object constructed from the source of this image 
     * with the specified width, height, and applied scaling
     * alghorithm.
     * 
     * @param width the width of scaled Image. 
     * @param height the height of scaled Image.
     * @param hints the constant which indicates scaling algorithm. 
     * 
     * @return the scaled Image.
     */
    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 producer = new FilteredImageSource(getSource(), filter);
        return Toolkit.getDefaultToolkit().createImage(producer);
    }

    /**
     * Gets a Graphics object for rendering this image. 
     * This method can be used for off-screen images.
     * 
     * @return a Graphics object for rendering to this image.
     */
    public abstract Graphics getGraphics();

    /**
     * Flushes resources which are used by this Image object. 
     * This method resets the image to the reconstructered state
     * from the image's source.
     */
    public abstract void flush();

    /**
     * Gets the acceleration priority of this image.
     * 
     * @return the acceleration priority of this image.
     */
    public float getAccelerationPriority() {
        return accelerationPriority;
    }

    /**
     * Sets the acceleration priority for this image.  
     *  
     * @param priority the new acceleration priority (value in the
     * range 0-1).
     */
    public void setAccelerationPriority(float priority) {
        if (priority < 0 || priority > 1) {
            // awt.10A=Priority must be a value between 0 and 1, inclusive
            throw new IllegalArgumentException(Messages.getString("awt.10A")); //$NON-NLS-1$
        }
        accelerationPriority = priority;
    }

    /**
     * Gets an ImageCapabilities object of this Image object
     * for the specified GraphicsConfiguration. 
     * 
     * @param gc the specified GraphicsConfiguration object 
     * (null value means default GraphicsConfiguration).
     * 
     * @return an ImageCapabilities object of this Image object
     * for the specified GraphicsConfiguration.
     */
    public ImageCapabilities getCapabilities(GraphicsConfiguration gc) {
        // Note: common image is not accelerated.
        return capabilities;
    }
}