1. /*

  2.  * @(#)Image.java	1.31 00/02/02

  3.  *

  4.  * Copyright 1995-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. package java.awt;

  11. 

  12. import java.awt.image.ImageProducer;

  13. import java.awt.image.ImageObserver;

  14. import java.awt.image.ImageFilter;

  15. import java.awt.image.FilteredImageSource;

  16. import java.awt.image.AreaAveragingScaleFilter;

  17. import java.awt.image.ReplicateScaleFilter;

  18. 

  19. /**

  20.  * The abstract class <code>Image</code> is the superclass of all 

  21.  * classes that represent graphical images. The image must be 

  22.  * obtained in a platform-specific manner.

  23.  *

  24.  * @version 	1.31, 02/02/00

  25.  * @author 	Sami Shaio

  26.  * @author 	Arthur van Hoff

  27.  * @since       JDK1.0

  28.  */

  29. public abstract class Image {

  30.     /**

  31.      * Determines the width of the image. If the width is not yet known, 

  32.      * this method returns <code>-1</code> and the specified   

  33.      * <code>ImageObserver</code> object is notified later.

  34.      * @param     observer   an object waiting for the image to be loaded.

  35.      * @return    the width of this image, or <code>-1</code> 

  36.      *                   if the width is not yet known.

  37.      * @see       java.awt.Image#getHeight

  38.      * @see       java.awt.image.ImageObserver

  39.      */

  40.     public abstract int getWidth(ImageObserver observer);

  41. 

  42.     /**

  43.      * Determines the height of the image. If the height is not yet known, 

  44.      * this method returns <code>-1</code> and the specified  

  45.      * <code>ImageObserver</code> object is notified later.

  46.      * @param     observer   an object waiting for the image to be loaded.

  47.      * @return    the height of this image, or <code>-1</code> 

  48.      *                   if the height is not yet known.

  49.      * @see       java.awt.Image#getWidth

  50.      * @see       java.awt.image.ImageObserver

  51.      */

  52.     public abstract int getHeight(ImageObserver observer);

  53. 

  54.     /**

  55.      * Gets the object that produces the pixels for the image.

  56.      * This method is called by the image filtering classes and by 

  57.      * methods that perform image conversion and scaling.

  58.      * @return     the image producer that produces the pixels 

  59.      *                                  for this image.

  60.      * @see        java.awt.image.ImageProducer

  61.      */

  62.     public abstract ImageProducer getSource();

  63. 

  64.     /**

  65.      * Creates a graphics context for drawing to an off-screen image. 

  66.      * This method can only be called for off-screen images. 

  67.      * @return  a graphics context to draw to the off-screen image. 

  68.      * @see     java.awt.Graphics

  69.      * @see     java.awt.Component#createImage(int, int)

  70.      */

  71.     public abstract Graphics getGraphics();

  72. 

  73.     /**

  74.      * Gets a property of this image by name. 

  75.      * <p>

  76.      * Individual property names are defined by the various image 

  77.      * formats. If a property is not defined for a particular image, this 

  78.      * method returns the <code>UndefinedProperty</code> object. 

  79.      * <p>

  80.      * If the properties for this image are not yet known, this method 

  81.      * returns <code>null</code>, and the <code>ImageObserver</code> 

  82.      * object is notified later. 

  83.      * <p>

  84.      * The property name <code>"comment"</code> should be used to store 

  85.      * an optional comment which can be presented to the application as a 

  86.      * description of the image, its source, or its author. 

  87.      * @param       name   a property name.

  88.      * @param       observer   an object waiting for this image to be loaded.

  89.      * @return      the value of the named property.

  90.      * @see         java.awt.image.ImageObserver

  91.      * @see         java.awt.Image#UndefinedProperty

  92.      */

  93.     public abstract Object getProperty(String name, ImageObserver observer);

  94. 

  95.     /**

  96.      * The <code>UndefinedProperty</code> object should be returned whenever a

  97.      * property which was not defined for a particular image is fetched.

  98.      */

  99.     public static final Object UndefinedProperty = new Object();

  100. 

  101.     /**

  102.      * Creates a scaled version of this image.

  103.      * A new <code>Image</code> object is returned which will render 

  104.      * the image at the specified <code>width</code> and 

  105.      * <code>height</code> by default.  The new <code>Image</code> object

  106.      * may be loaded asynchronously even if the original source image

  107.      * has already been loaded completely.  If either the <code>width</code> 

  108.      * or <code>height</code> is a negative number then a value is 

  109.      * substituted to maintain the aspect ratio of the original image 

  110.      * dimensions.

  111.      * @param width the width to which to scale the image.

  112.      * @param height the height to which to scale the image.

  113.      * @param hints flags to indicate the type of algorithm to use

  114.      * for image resampling.

  115.      * @return     a scaled version of the image.

  116.      * @see        java.awt.Image#SCALE_DEFAULT

  117.      * @see        java.awt.Image#SCALE_FAST 

  118.      * @see        java.awt.Image#SCALE_SMOOTH

  119.      * @see        java.awt.Image#SCALE_REPLICATE

  120.      * @see        java.awt.Image#SCALE_AREA_AVERAGING

  121.      * @since      JDK1.1

  122.      */

  123.     public Image getScaledInstance(int width, int height, int hints) {

  124. 	ImageFilter filter;

  125. 	if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {

  126. 	    filter = new AreaAveragingScaleFilter(width, height);

  127. 	} else {

  128. 	    filter = new ReplicateScaleFilter(width, height);

  129. 	}

  130. 	ImageProducer prod;

  131. 	prod = new FilteredImageSource(getSource(), filter);

  132. 	return Toolkit.getDefaultToolkit().createImage(prod);

  133.     }

  134. 

  135.     /**

  136.      * Use the default image-scaling algorithm.

  137.      * @since JDK1.1

  138.      */

  139.     public static final int SCALE_DEFAULT = 1;

  140. 

  141.     /**

  142.      * Choose an image-scaling algorithm that gives higher priority

  143.      * to scaling speed than smoothness of the scaled image.

  144.      * @since JDK1.1

  145.      */

  146.     public static final int SCALE_FAST = 2;

  147. 

  148.     /**

  149.      * Choose an image-scaling algorithm that gives higher priority

  150.      * to image smoothness than scaling speed.

  151.      * @since JDK1.1

  152.      */

  153.     public static final int SCALE_SMOOTH = 4;

  154. 

  155.     /**

  156.      * Use the image scaling algorithm embodied in the 

  157.      * <code>ReplicateScaleFilter</code> class.  

  158.      * The <code>Image</code> object is free to substitute a different filter 

  159.      * that performs the same algorithm yet integrates more efficiently

  160.      * into the imaging infrastructure supplied by the toolkit.

  161.      * @see        java.awt.image.ReplicateScaleFilter

  162.      * @since      JDK1.1

  163.      */

  164.     public static final int SCALE_REPLICATE = 8;

  165. 

  166.     /**

  167.      * Use the Area Averaging image scaling algorithm.  The

  168.      * image object is free to substitute a different filter that

  169.      * performs the same algorithm yet integrates more efficiently

  170.      * into the image infrastructure supplied by the toolkit.

  171.      * @see java.awt.image.AreaAveragingScaleFilter

  172.      * @since JDK1.1

  173.      */

  174.     public static final int SCALE_AREA_AVERAGING = 16;

  175. 

  176.     /**

  177.      * Flushes all resources being used by this Image object.  This

  178.      * includes any pixel data that is being cached for rendering to

  179.      * the screen as well as any system resources that are being used

  180.      * to store data or pixels for the image.  The image is reset to

  181.      * a state similar to when it was first created so that if it is

  182.      * again rendered, the image data will have to be recreated or

  183.      * fetched again from its source.

  184.      * <p>

  185.      * This method always leaves the image in a state such that it can 

  186.      * be reconstructed.  This means the method applies only to cached 

  187.      * or other secondary representations of images such as those that 

  188.      * have been generated from an <tt>ImageProducer</tt> (read from a 

  189.      * file, for example). It does nothing for off-screen images that 

  190.      * have only one copy of their data.

  191.      */

  192.     public abstract void flush();

  193. }