001/* Image.java -- superclass for images
002   Copyright (C) 1999, 2002, 2004, 2005, 2006  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt;
040
041import java.awt.image.AreaAveragingScaleFilter;
042import java.awt.image.FilteredImageSource;
043import java.awt.image.ImageFilter;
044import java.awt.image.ImageObserver;
045import java.awt.image.ImageProducer;
046import java.awt.image.ReplicateScaleFilter;
047
048/**
049 * This is the abstract superclass of all image objects in Java.
050 *
051 * @author Aaron M. Renn (arenn@urbanophile.com)
052 * @since 1.0
053 * @status updated to 1.5
054 */
055public abstract class Image
056{
057  /**
058   * This variable is returned whenever a property that is not defined
059   * is requested.
060   */
061  // For debug purposes, this might as well be a unique string.
062  public static final Object UndefinedProperty
063    = new String("undefined property");
064
065  /**
066   * Constant indicating that the default scaling algorithm should be used.
067   *
068   * @since 1.1
069   */
070  public static final int SCALE_DEFAULT = 1;
071
072  /**
073   * Constant indicating that a fast scaling algorithm should be used.
074   *
075   * @since 1.1
076   */
077  public static final int SCALE_FAST = 2;
078
079  /**
080   * Constant indicating that a smooth scaling algorithm should be used.
081   *
082   * @since 1.1
083   */
084  public static final int SCALE_SMOOTH = 4;
085
086  /**
087   * Constant indicating that the <code>ReplicateScaleFilter</code> class
088   * algorithm should be used for scaling.
089   *
090   * @see ReplicateScaleFilter
091   * @since 1.1
092   */
093  public static final int SCALE_REPLICATE = 8;
094
095  /**
096   * Constant indicating that the area averaging scaling algorithm should be
097   * used.
098   *
099   * @see java.awt.image.AreaAveragingScaleFilter
100   * @since 1.1
101   */
102  public static final int SCALE_AREA_AVERAGING = 16;
103
104  /**
105   * The acceleration priority of the image
106   * @since 1.5
107   */
108  protected float accelerationPriority;
109
110  /**
111   * A default constructor for subclasses.
112   */
113  public Image()
114  {
115  }
116
117  /**
118   * Returns the width of the image, or -1 if it is unknown.  If the
119   * image width is unknown, the observer object will be notified when
120   * the value is known.
121   *
122   * @param observer the image observer for this object
123   * @return the width in pixels
124   * @see #getHeight(ImageObserver)
125   */
126  public abstract int getWidth(ImageObserver observer);
127
128  /**
129   * Returns the height of the image, or -1 if it is unknown.  If the
130   * image height is unknown, the observer object will be notified when
131   * the value is known.
132   *
133   * @param observer the image observer for this object
134   * @return the height in pixels
135   * @see #getWidth(ImageObserver)
136   */
137  public abstract int getHeight(ImageObserver observer);
138
139  /**
140   * Returns the image producer object for this object. The producer is the
141   * object which generates pixels for this image.
142   *
143   * @return the image producer for this object
144   */
145  public abstract ImageProducer getSource();
146
147  /**
148   * Returns a graphics context object for drawing an off-screen object.
149   * This method is only valid for off-screen objects.
150   *
151   * @return a graphics context object for an off-screen object
152   */
153  public abstract Graphics getGraphics();
154
155  /**
156   * This method requests a named property for an object.  The value of the
157   * property is returned. The value <code>UndefinedProperty</code> is
158   * returned if there is no property with the specified name.  The value
159   * <code>null</code> is returned if the properties for the object are
160   * not yet known.  In this case, the specified image observer is notified
161   * when the properties are known.
162   *
163   * @param name the requested property name
164   * @param observer the image observer for this object
165   * @return the named property, if available
166   * @see #UndefinedProperty
167   */
168  public abstract Object getProperty(String name, ImageObserver observer);
169
170  /**
171   * Scales the image to the requested dimension. A new Image with asynchronous
172   * loading will be produced according to the hints of the algorithm
173   * requested. If either the width or height is non-positive, it is adjusted
174   * to preserve the original aspect ratio.
175   * If an illegal value of <code>flags</code> is passed,
176   * the default algorithm is used.
177   *
178   * @param width the width of the scaled image
179   * @param height the height of the scaled image
180   * @param flags a value indicating the algorithm to use
181   * @return the scaled <code>Image</code> object
182   * @see #SCALE_DEFAULT
183   * @see #SCALE_FAST
184   * @see #SCALE_SMOOTH
185   * @see #SCALE_REPLICATE
186   * @see #SCALE_AREA_AVERAGING
187   * @since 1.1
188   */
189  public Image getScaledInstance(int width, int height, int flags)
190  {
191    ImageFilter filter;
192    switch (flags)
193    {
194      case SCALE_AREA_AVERAGING:
195      case SCALE_SMOOTH:
196        filter = new AreaAveragingScaleFilter(width, height);
197        break;
198      case SCALE_DEFAULT:
199      case SCALE_FAST:
200      case SCALE_REPLICATE:
201      default:
202        filter = new ReplicateScaleFilter(width, height);
203    }
204
205    ImageProducer producer = new FilteredImageSource(getSource(), filter);
206    return Toolkit.getDefaultToolkit().createImage(producer);
207  }
208
209  /**
210   * Flushes (that is, destroys) any resources used for this image.  This
211   * includes the actual image data.
212   */
213  public abstract void flush();
214
215  /**
216   * Sets the acceleration priority of the image.
217   * This is a value from 0 (lowest) to 1 (highest), which may
218   * be used as a hint for image acceleration.
219   * E.g. higher priority images may be stored in video memory.
220   * @param priority - the priority
221   * @throws IllegalArgumentException if priority is not >= 0 and <= 1.
222   *
223   * @since 1.5
224   */
225  public void setAccelerationPriority(float priority)
226  {
227    if( priority < 0f || priority > 1f)
228      throw new IllegalArgumentException("Invalid priority value.");
229    accelerationPriority = priority;
230  }
231
232  /**
233   * Returns the acceleration priority of the image.
234   *
235   * @see #setAccelerationPriority(float)
236   * @since 1.5
237   */
238  public float getAccelerationPriority()
239  {
240    return accelerationPriority;
241  }
242} // class Image