KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > Image


1 /*
2  * @(#)Image.java 1.39 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7 package java.awt;
8
9 import java.awt.image.ImageProducer JavaDoc;
10 import java.awt.image.ImageObserver JavaDoc;
11 import java.awt.image.ImageFilter JavaDoc;
12 import java.awt.image.FilteredImageSource JavaDoc;
13 import java.awt.image.AreaAveragingScaleFilter JavaDoc;
14 import java.awt.image.ReplicateScaleFilter JavaDoc;
15
16 /**
17  * The abstract class <code>Image</code> is the superclass of all
18  * classes that represent graphical images. The image must be
19  * obtained in a platform-specific manner.
20  *
21  * @version 1.39, 12/19/03
22  * @author Sami Shaio
23  * @author Arthur van Hoff
24  * @since JDK1.0
25  */

26 public abstract class Image {
27     
28     /**
29      * convenience object; we can use this single static object for
30      * all images that do not create their own image caps; it holds the
31      * default (unaccelerated) properties.
32      */

33     private static ImageCapabilities JavaDoc defaultImageCaps =
34     new ImageCapabilities JavaDoc(false);
35
36     /**
37      * Priority for accelerating this image. Subclasses are free to
38      * set different default priorities and applications are free to
39      * set the priority for specific images via the
40      * <code>setAccelerationPriority(float)</code> method.
41      * @since 1.5
42      */

43     protected float accelerationPriority = .5f;
44
45     /**
46      * Determines the width of the image. If the width is not yet known,
47      * this method returns <code>-1</code> and the specified
48      * <code>ImageObserver</code> object is notified later.
49      * @param observer an object waiting for the image to be loaded.
50      * @return the width of this image, or <code>-1</code>
51      * if the width is not yet known.
52      * @see java.awt.Image#getHeight
53      * @see java.awt.image.ImageObserver
54      */

55     public abstract int getWidth(ImageObserver JavaDoc observer);
56
57     /**
58      * Determines the height of the image. If the height is not yet known,
59      * this method returns <code>-1</code> and the specified
60      * <code>ImageObserver</code> object is notified later.
61      * @param observer an object waiting for the image to be loaded.
62      * @return the height of this image, or <code>-1</code>
63      * if the height is not yet known.
64      * @see java.awt.Image#getWidth
65      * @see java.awt.image.ImageObserver
66      */

67     public abstract int getHeight(ImageObserver JavaDoc observer);
68
69     /**
70      * Gets the object that produces the pixels for the image.
71      * This method is called by the image filtering classes and by
72      * methods that perform image conversion and scaling.
73      * @return the image producer that produces the pixels
74      * for this image.
75      * @see java.awt.image.ImageProducer
76      */

77     public abstract ImageProducer JavaDoc getSource();
78
79     /**
80      * Creates a graphics context for drawing to an off-screen image.
81      * This method can only be called for off-screen images.
82      * @return a graphics context to draw to the off-screen image.
83      * @exception UnsupportedOperationException if called for a
84      * non-off-screen image.
85      * @see java.awt.Graphics
86      * @see java.awt.Component#createImage(int, int)
87      */

88     public abstract Graphics JavaDoc getGraphics();
89
90     /**
91      * Gets a property of this image by name.
92      * <p>
93      * Individual property names are defined by the various image
94      * formats. If a property is not defined for a particular image, this
95      * method returns the <code>UndefinedProperty</code> object.
96      * <p>
97      * If the properties for this image are not yet known, this method
98      * returns <code>null</code>, and the <code>ImageObserver</code>
99      * object is notified later.
100      * <p>
101      * The property name <code>"comment"</code> should be used to store
102      * an optional comment which can be presented to the application as a
103      * description of the image, its source, or its author.
104      * @param name a property name.
105      * @param observer an object waiting for this image to be loaded.
106      * @return the value of the named property.
107      * @throws <code>NullPointerException<code> if the property name is null.
108      * @see java.awt.image.ImageObserver
109      * @see java.awt.Image#UndefinedProperty
110      */

111     public abstract Object JavaDoc getProperty(String JavaDoc name, ImageObserver JavaDoc observer);
112
113     /**
114      * The <code>UndefinedProperty</code> object should be returned whenever a
115      * property which was not defined for a particular image is fetched.
116      */

117     public static final Object JavaDoc UndefinedProperty = new Object JavaDoc();
118
119     /**
120      * Creates a scaled version of this image.
121      * A new <code>Image</code> object is returned which will render
122      * the image at the specified <code>width</code> and
123      * <code>height</code> by default. The new <code>Image</code> object
124      * may be loaded asynchronously even if the original source image
125      * has already been loaded completely.
126      *
127      * <p>
128      *
129      * If either <code>width</code>
130      * or <code>height</code> is a negative number then a value is
131      * substituted to maintain the aspect ratio of the original image
132      * dimensions. If both <code>width</code> and <code>height</code>
133      * are negative, then the original image dimensions are used.
134      *
135      * @param width the width to which to scale the image.
136      * @param height the height to which to scale the image.
137      * @param hints flags to indicate the type of algorithm to use
138      * for image resampling.
139      * @return a scaled version of the image.
140      * @exception IllegalArgumentException if <code>width</code>
141      * or <code>height</code> is zero.
142      * @see java.awt.Image#SCALE_DEFAULT
143      * @see java.awt.Image#SCALE_FAST
144      * @see java.awt.Image#SCALE_SMOOTH
145      * @see java.awt.Image#SCALE_REPLICATE
146      * @see java.awt.Image#SCALE_AREA_AVERAGING
147      * @since JDK1.1
148      */

149     public Image JavaDoc getScaledInstance(int width, int height, int hints) {
150     ImageFilter JavaDoc filter;
151     if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
152         filter = new AreaAveragingScaleFilter JavaDoc(width, height);
153     } else {
154         filter = new ReplicateScaleFilter JavaDoc(width, height);
155     }
156     ImageProducer JavaDoc prod;
157     prod = new FilteredImageSource JavaDoc(getSource(), filter);
158     return Toolkit.getDefaultToolkit().createImage(prod);
159     }
160
161     /**
162      * Use the default image-scaling algorithm.
163      * @since JDK1.1
164      */

165     public static final int SCALE_DEFAULT = 1;
166
167     /**
168      * Choose an image-scaling algorithm that gives higher priority
169      * to scaling speed than smoothness of the scaled image.
170      * @since JDK1.1
171      */

172     public static final int SCALE_FAST = 2;
173
174     /**
175      * Choose an image-scaling algorithm that gives higher priority
176      * to image smoothness than scaling speed.
177      * @since JDK1.1
178      */

179     public static final int SCALE_SMOOTH = 4;
180
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     /**
193      * Use the Area Averaging image scaling algorithm. The
194      * image object is free to substitute a different filter that
195      * performs the same algorithm yet integrates more efficiently
196      * into the image infrastructure supplied by the toolkit.
197      * @see java.awt.image.AreaAveragingScaleFilter
198      * @since JDK1.1
199      */

200     public static final int SCALE_AREA_AVERAGING = 16;
201
202     /**
203      * Flushes all resources being used by this Image object. This
204      * includes any pixel data that is being cached for rendering to
205      * the screen as well as any system resources that are being used
206      * to store data or pixels for the image. The image is reset to
207      * a state similar to when it was first created so that if it is
208      * again rendered, the image data will have to be recreated or
209      * fetched again from its source.
210      * <p>
211      * This method always leaves the image in a state such that it can
212      * be reconstructed. This means the method applies only to cached
213      * or other secondary representations of images such as those that
214      * have been generated from an <tt>ImageProducer</tt> (read from a
215      * file, for example). It does nothing for off-screen images that
216      * have only one copy of their data.
217      */

218     public abstract void flush();
219
220     /**
221      * Returns an ImageCapabilities object which can be
222      * inquired as to the capabilities of this
223      * Image on the specified GraphicsConfiguration.
224      * This allows programmers to find
225      * out more runtime information on the specific Image
226      * object that they have created. For example, the user
227      * might create a BufferedImage but the system may have
228      * no video memory left for creating an image of that
229      * size on the given GraphicsConfiguration, so although the object
230      * may be acceleratable in general, it is
231      * does not have that capability on this GraphicsConfiguration.
232      * @param gc a <code>GraphicsConfiguration</code> object. A value of null
233      * for this parameter will result in getting the image capabilities
234      * for the default <code>GraphicsConfiguration</code>.
235      * @return an <code>ImageCapabilities</code> object that contains
236      * the capabilities of this <code>Image</code> on the specified
237      * GraphicsConfiguration.
238      * @see #java.awt.image.VolatileImage.getCapabilities()
239      * VolatileImage.getCapabilities()
240      * @since 1.5
241      */

242     public ImageCapabilities JavaDoc getCapabilities(GraphicsConfiguration JavaDoc gc) {
243     // Note: this is just a default object that gets returned by the
244
// base Image object. Subclasses of Image should override this
245
// method and return an ImageCapabilities object that is appropriate
246
// for a given instance of that subclass.
247
return defaultImageCaps;
248     }
249     
250     /**
251      * Sets a hint for this image about how important acceleration is.
252      * This priority hint is used to compare to the priorities of other
253      * Image objects when determining how to use scarce acceleration
254      * resources such as video memory. When and if it is possible to
255      * accelerate this Image, if there are not enough resources available
256      * to provide that acceleration but enough can be freed up by
257      * de-acceleration some other image of lower priority, then that other
258      * Image may be de-accelerated in deference to this one. Images
259      * that have the same priority take up resources on a first-come,
260      * first-served basis.
261      * @param priority a value between 0 and 1, inclusive, where higher
262      * values indicate more importance for acceleration. A value of 0
263      * means that this Image should never be accelerated. Other values
264      * are used simply to determine acceleration priority relative to other
265      * Images.
266      * @throws IllegalArgumentException if <code>priority</code> is less
267      * than zero or greater than 1.
268      * @since 1.5
269      */

270     public void setAccelerationPriority(float priority) {
271         if (priority < 0 || priority > 1) {
272             throw new IllegalArgumentException JavaDoc("Priority must be a value " +
273                            "between 0 and 1, inclusive");
274         }
275     accelerationPriority = priority;
276     }
277
278     /**
279      * Returns the current value of the acceleration priority hint.
280      * @see #setAccelerationPriority(float priority) setAccelerationPriority
281      * @return value between 0 and 1, inclusive, which represents the current
282      * priority value
283      * @since 1.5
284      */

285     public float getAccelerationPriority() {
286     return accelerationPriority;
287     }
288 }
289
Popular Tags