001: /*
002: * @(#)Image.java 1.35 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027: package java.awt;
028:
029: import java.awt.image.ImageProducer;
030: import java.awt.image.ImageObserver;
031: import java.awt.image.ImageFilter;
032: import java.awt.image.FilteredImageSource;
033: import java.awt.image.AreaAveragingScaleFilter;
034: import java.awt.image.ReplicateScaleFilter;
035:
036: /**
037: * The abstract class <code>Image</code> is the superclass of all
038: * classes that represent graphical images. The image must be
039: * obtained in a platform-specific manner.
040: * <h3>Compatibility</h3>
041: * The Image class in Personal Java supported GIF(CompuServ 89a),
042: * JPEG(JFIF), and XBM(X Bitmap). In addition to these, Personal
043: * Profile supports the PNG image file format. Images are created using
044: * the <code>Toolkit.createImage()</code> method or by an imageProducer.
045: *
046: * @version 1.31, 08/19/02
047: * @author Sami Shaio
048: * @author Arthur van Hoff
049: * @see java.awt.Toolkit#createImage
050: * @since JDK1.0
051: */
052: public abstract class Image {
053: /**
054: * Determines the width of the image. If the width is not yet known,
055: * this method returns <code>-1</code> and the specified
056: * <code>ImageObserver</code> object is notified later.
057: * @param observer an object waiting for the image to be loaded.
058: * @return the width of this image, or <code>-1</code>
059: * if the width is not yet known.
060: * @see java.awt.Image#getHeight
061: * @see java.awt.image.ImageObserver
062: * @since JDK1.0
063: */
064: public abstract int getWidth(ImageObserver observer);
065:
066: /**
067: * Determines the height of the image. If the height is not yet known,
068: * this method returns <code>-1</code> and the specified
069: * <code>ImageObserver</code> object is notified later.
070: * @param observer an object waiting for the image to be loaded.
071: * @return the height of this image, or <code>-1</code>
072: * if the height is not yet known.
073: * @see java.awt.Image#getWidth
074: * @see java.awt.image.ImageObserver
075: * @since JDK1.0
076: */
077: public abstract int getHeight(ImageObserver observer);
078:
079: /**
080: * Gets the object that produces the pixels for the image.
081: * This method is called by the image filtering classes and by
082: * methods that perform image conversion and scaling.
083: * @return the image producer that produces the pixels
084: * for this image.
085: * @see java.awt.image.ImageProducer
086: */
087: public abstract ImageProducer getSource();
088:
089: /**
090: * Creates a graphics context for drawing to an off-screen image.
091: * This method can only be called for off-screen images.
092: * @return a graphics context to draw to the off-screen image.
093: * @see java.awt.Graphics
094: * @see java.awt.Component#createImage(int, int)
095: * @since JDK1.0
096: */
097: public abstract Graphics getGraphics();
098:
099: /**
100: * Gets a property of this image by name.
101: * <p>
102: * Individual property names are defined by the various image
103: * formats. If a property is not defined for a particular image, this
104: * method returns the <code>UndefinedProperty</code> object.
105: * <p>
106: * If the properties for this image are not yet known, this method
107: * returns <code>null</code>, and the <code>ImageObserver</code>
108: * object is notified later.
109: * <p>
110: * The property name <code>"comment"</code> should be used to store
111: * an optional comment which can be presented to the application as a
112: * description of the image, its source, or its author.
113: * @param name a property name.
114: * @param observer an object waiting for this image to be loaded.
115: * @return the value of the named property.
116: * @see java.awt.image.ImageObserver
117: * @see java.awt.Image#UndefinedProperty
118: * @since JDK1.0
119: */
120: public abstract Object getProperty(String name,
121: ImageObserver observer);
122:
123: /**
124: * The <code>UndefinedProperty</code> object should be returned whenever a
125: * property which was not defined for a particular image is fetched.
126: * @since JDK1.0
127: */
128: public static final Object UndefinedProperty = new Object();
129:
130: /**
131: * Creates a scaled version of this image.
132: * A new <code>Image</code> object is returned which will render
133: * the image at the specified <code>width</code> and
134: * <code>height</code> by default. The new <code>Image</code> object
135: * may be loaded asynchronously even if the original source image
136: * has already been loaded completely. If either the <code>width</code>
137: * or <code>height</code> is a negative number then a value is
138: * substituted to maintain the aspect ratio of the original image
139: * dimensions.
140: * @param width the width to which to scale the image.
141: * @param height the height to which to scale the image.
142: * @param hints flags to indicate the type of algorithm to use
143: * for image resampling.
144: * @return a scaled version of the image.
145: * @see java.awt.Image#SCALE_DEFAULT
146: * @see java.awt.Image#SCALE_FAST
147: * @see java.awt.Image#SCALE_SMOOTH
148: * @see java.awt.Image#SCALE_REPLICATE
149: * @see java.awt.Image#SCALE_AREA_AVERAGING
150: * @since JDK1.1
151: */
152: public Image getScaledInstance(int width, int height, int hints) {
153: ImageFilter filter;
154: if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
155: filter = new AreaAveragingScaleFilter(width, height);
156: } else {
157: filter = new ReplicateScaleFilter(width, height);
158: }
159: ImageProducer prod;
160: prod = new FilteredImageSource(getSource(), filter);
161: return Toolkit.getDefaultToolkit().createImage(prod);
162: }
163:
164: /**
165: * Use the default image-scaling algorithm.
166: * @since JDK1.1
167: */
168: public static final int SCALE_DEFAULT = 1;
169: /**
170: * Choose an image-scaling algorithm that gives higher priority
171: * to scaling speed than smoothness of the scaled image.
172: * @since JDK1.1
173: */
174: public static final int SCALE_FAST = 2;
175: /**
176: * Choose an image-scaling algorithm that gives higher priority
177: * to image smoothness than scaling speed.
178: * @since JDK1.1
179: */
180: public static final int SCALE_SMOOTH = 4;
181: /**
182: * Use the image scaling algorithm embodied in the
183: * <code>ReplicateScaleFilter</code> class.
184: * The <code>Image</code> object is free to substitute a different filter
185: * that performs the same algorithm yet integrates more efficiently
186: * into the imaging infrastructure supplied by the toolkit.
187: * @see java.awt.image.ReplicateScaleFilter
188: * @since JDK1.1
189: */
190: public static final int SCALE_REPLICATE = 8;
191: /**
192: * Use the Area Averaging image scaling algorithm. The
193: * image object is free to substitute a different filter that
194: * performs the same algorithm yet integrates more efficiently
195: * into the image infrastructure supplied by the toolkit.
196: * @see java.awt.image.AreaAveragingScaleFilter
197: * @since JDK1.1
198: */
199: public static final int SCALE_AREA_AVERAGING = 16;
200:
201: /**
202: * Flushes all resources being used by this Image object. This
203: * includes any pixel data that is being cached for rendering to
204: * the screen as well as any system resources that are being used
205: * to store data or pixels for the image. The image is reset to
206: * a state similar to when it was first created so that if it is
207: * again rendered, the image data will have to be recreated or
208: * fetched again from its source.
209: * @since JDK1.0
210: */
211: public abstract void flush();
212: }
|