1 /*
2 * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 package java.awt;
26
27 import java.awt.image.ImageProducer;
28 import java.awt.image.ImageObserver;
29 import java.awt.image.ImageFilter;
30 import java.awt.image.FilteredImageSource;
31 import java.awt.image.AreaAveragingScaleFilter;
32 import java.awt.image.ReplicateScaleFilter;
33
34 import sun.awt.image.SurfaceManager;
35
36 /**
37 * The abstract class <code>Image</code> is the superclass of all
38 * classes that represent graphical images. The image must be
39 * obtained in a platform-specific manner.
40 *
41 * @author Sami Shaio
42 * @author Arthur van Hoff
43 * @since JDK1.0
44 */
45 public abstract class Image {
46
47 /**
48 * convenience object; we can use this single static object for
49 * all images that do not create their own image caps; it holds the
50 * default (unaccelerated) properties.
51 */
52 private static ImageCapabilities defaultImageCaps =
53 new ImageCapabilities(false);
54
55 /**
56 * Priority for accelerating this image. Subclasses are free to
57 * set different default priorities and applications are free to
58 * set the priority for specific images via the
59 * <code>setAccelerationPriority(float)</code> method.
60 * @since 1.5
61 */
62 protected float accelerationPriority = .5f;
63
64 /**
65 * Determines the width of the image. If the width is not yet known,
66 * this method returns <code>-1</code> and the specified
67 * <code>ImageObserver</code> object is notified later.
68 * @param observer an object waiting for the image to be loaded.
69 * @return the width of this image, or <code>-1</code>
70 * if the width is not yet known.
71 * @see java.awt.Image#getHeight
72 * @see java.awt.image.ImageObserver
73 */
74 public abstract int getWidth(ImageObserver observer);
75
76 /**
77 * Determines the height of the image. If the height is not yet known,
78 * this method returns <code>-1</code> and the specified
79 * <code>ImageObserver</code> object is notified later.
80 * @param observer an object waiting for the image to be loaded.
81 * @return the height of this image, or <code>-1</code>
82 * if the height is not yet known.
83 * @see java.awt.Image#getWidth
84 * @see java.awt.image.ImageObserver
85 */
86 public abstract int getHeight(ImageObserver observer);
87
88 /**
89 * Gets the object that produces the pixels for the image.
90 * This method is called by the image filtering classes and by
91 * methods that perform image conversion and scaling.
92 * @return the image producer that produces the pixels
93 * for this image.
94 * @see java.awt.image.ImageProducer
95 */
96 public abstract ImageProducer getSource();
97
98 /**
99 * Creates a graphics context for drawing to an off-screen image.
100 * This method can only be called for off-screen images.
101 * @return a graphics context to draw to the off-screen image.
102 * @exception UnsupportedOperationException if called for a
103 * non-off-screen image.
104 * @see java.awt.Graphics
105 * @see java.awt.Component#createImage(int, int)
106 */
107 public abstract Graphics getGraphics();
108
109 /**
110 * Gets a property of this image by name.
111 * <p>
112 * Individual property names are defined by the various image
113 * formats. If a property is not defined for a particular image, this
114 * method returns the <code>UndefinedProperty</code> object.
115 * <p>
116 * If the properties for this image are not yet known, this method
117 * returns <code>null</code>, and the <code>ImageObserver</code>
118 * object is notified later.
119 * <p>
120 * The property name <code>"comment"</code> should be used to store
121 * an optional comment which can be presented to the application as a
122 * description of the image, its source, or its author.
123 * @param name a property name.
124 * @param observer an object waiting for this image to be loaded.
125 * @return the value of the named property.
126 * @throws <code>NullPointerException</code> if the property name is null.
127 * @see java.awt.image.ImageObserver
128 * @see java.awt.Image#UndefinedProperty
129 */
130 public abstract Object getProperty(String name, ImageObserver observer);
131
132 /**
133 * The <code>UndefinedProperty</code> object should be returned whenever a
134 * property which was not defined for a particular image is fetched.
135 */
136 public static final Object UndefinedProperty = new Object();
137
138 /**
139 * Creates a scaled version of this image.
140 * A new <code>Image</code> object is returned which will render
141 * the image at the specified <code>width</code> and
142 * <code>height</code> by default. The new <code>Image</code> object
143 * may be loaded asynchronously even if the original source image
144 * has already been loaded completely.
145 *
146 * <p>
147 *
148 * If either <code>width</code>
149 * or <code>height</code> is a negative number then a value is
150 * substituted to maintain the aspect ratio of the original image
151 * dimensions. If both <code>width</code> and <code>height</code>
152 * are negative, then the original image dimensions are used.
153 *
154 * @param width the width to which to scale the image.
155 * @param height the height to which to scale the image.
156 * @param hints flags to indicate the type of algorithm to use
157 * for image resampling.
158 * @return a scaled version of the image.
159 * @exception IllegalArgumentException if <code>width</code>
160 * or <code>height</code> is zero.
161 * @see java.awt.Image#SCALE_DEFAULT
162 * @see java.awt.Image#SCALE_FAST
163 * @see java.awt.Image#SCALE_SMOOTH
164 * @see java.awt.Image#SCALE_REPLICATE
165 * @see java.awt.Image#SCALE_AREA_AVERAGING
166 * @since JDK1.1
167 */
168 public Image getScaledInstance(int width, int height, int hints) {
169 ImageFilter filter;
170 if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
171 filter = new AreaAveragingScaleFilter(width, height);
172 } else {
173 filter = new ReplicateScaleFilter(width, height);
174 }
175 ImageProducer prod;
176 prod = new FilteredImageSource(getSource(), filter);
177 return Toolkit.getDefaultToolkit().createImage(prod);
178 }
179
180 /**
181 * Use the default image-scaling algorithm.
182 * @since JDK1.1
183 */
184 public static final int SCALE_DEFAULT = 1;
185
186 /**
187 * Choose an image-scaling algorithm that gives higher priority
188 * to scaling speed than smoothness of the scaled image.
189 * @since JDK1.1
190 */
191 public static final int SCALE_FAST = 2;
192
193 /**
194 * Choose an image-scaling algorithm that gives higher priority
195 * to image smoothness than scaling speed.
196 * @since JDK1.1
197 */
198 public static final int SCALE_SMOOTH = 4;
199
200 /**
201 * Use the image scaling algorithm embodied in the
202 * <code>ReplicateScaleFilter</code> class.
203 * The <code>Image</code> object is free to substitute a different filter
204 * that performs the same algorithm yet integrates more efficiently
205 * into the imaging infrastructure supplied by the toolkit.
206 * @see java.awt.image.ReplicateScaleFilter
207 * @since JDK1.1
208 */
209 public static final int SCALE_REPLICATE = 8;
210
211 /**
212 * Use the Area Averaging image scaling algorithm. The
213 * image object is free to substitute a different filter that
214 * performs the same algorithm yet integrates more efficiently
215 * into the image infrastructure supplied by the toolkit.
216 * @see java.awt.image.AreaAveragingScaleFilter
217 * @since JDK1.1
218 */
219 public static final int SCALE_AREA_AVERAGING = 16;
220
221 /**
222 * Flushes all reconstructable resources being used by this Image object.
223 * This includes any pixel data that is being cached for rendering to
224 * the screen as well as any system resources that are being used
225 * to store data or pixels for the image if they can be recreated.
226 * The image is reset to a state similar to when it was first created
227 * so that if it is again rendered, the image data will have to be
228 * recreated or fetched again from its source.
229 * <p>
230 * Examples of how this method affects specific types of Image object:
231 * <ul>
232 * <li>
233 * BufferedImage objects leave the primary Raster which stores their
234 * pixels untouched, but flush any information cached about those
235 * pixels such as copies uploaded to the display hardware for
236 * accelerated blits.
237 * <li>
238 * Image objects created by the Component methods which take a
239 * width and height leave their primary buffer of pixels untouched,
240 * but have all cached information released much like is done for
241 * BufferedImage objects.
242 * <li>
243 * VolatileImage objects release all of their pixel resources
244 * including their primary copy which is typically stored on
245 * the display hardware where resources are scarce.
246 * These objects can later be restored using their
247 * {@link java.awt.image.VolatileImage#validate validate}
248 * method.
249 * <li>
250 * Image objects created by the Toolkit and Component classes which are
251 * loaded from files, URLs or produced by an {@link ImageProducer}
252 * are unloaded and all local resources are released.
253 * These objects can later be reloaded from their original source
254 * as needed when they are rendered, just as when they were first
255 * created.
256 * </ul>
257 */
258 public void flush() {
259 if (surfaceManager != null) {
260 surfaceManager.flush();
261 }
262 }
263
264 /**
265 * Returns an ImageCapabilities object which can be
266 * inquired as to the capabilities of this
267 * Image on the specified GraphicsConfiguration.
268 * This allows programmers to find
269 * out more runtime information on the specific Image
270 * object that they have created. For example, the user
271 * might create a BufferedImage but the system may have
272 * no video memory left for creating an image of that
273 * size on the given GraphicsConfiguration, so although the object
274 * may be acceleratable in general, it
275 * does not have that capability on this GraphicsConfiguration.
276 * @param gc a <code>GraphicsConfiguration</code> object. A value of null
277 * for this parameter will result in getting the image capabilities
278 * for the default <code>GraphicsConfiguration</code>.
279 * @return an <code>ImageCapabilities</code> object that contains
280 * the capabilities of this <code>Image</code> on the specified
281 * GraphicsConfiguration.
282 * @see java.awt.image.VolatileImage#getCapabilities()
283 * VolatileImage.getCapabilities()
284 * @since 1.5
285 */
286 public ImageCapabilities getCapabilities(GraphicsConfiguration gc) {
287 if (surfaceManager != null) {
288 return surfaceManager.getCapabilities(gc);
289 }
290 // Note: this is just a default object that gets returned in the
291 // absence of any more specific information from a surfaceManager.
292 // Subclasses of Image should either override this method or
293 // make sure that they always have a non-null SurfaceManager
294 // to return an ImageCapabilities object that is appropriate
295 // for their given subclass type.
296 return defaultImageCaps;
297 }
298
299 /**
300 * Sets a hint for this image about how important acceleration is.
301 * This priority hint is used to compare to the priorities of other
302 * Image objects when determining how to use scarce acceleration
303 * resources such as video memory. When and if it is possible to
304 * accelerate this Image, if there are not enough resources available
305 * to provide that acceleration but enough can be freed up by
306 * de-accelerating some other image of lower priority, then that other
307 * Image may be de-accelerated in deference to this one. Images
308 * that have the same priority take up resources on a first-come,
309 * first-served basis.
310 * @param priority a value between 0 and 1, inclusive, where higher
311 * values indicate more importance for acceleration. A value of 0
312 * means that this Image should never be accelerated. Other values
313 * are used simply to determine acceleration priority relative to other
314 * Images.
315 * @throws IllegalArgumentException if <code>priority</code> is less
316 * than zero or greater than 1.
317 * @since 1.5
318 */
319 public void setAccelerationPriority(float priority) {
320 if (priority < 0 || priority > 1) {
321 throw new IllegalArgumentException("Priority must be a value " +
322 "between 0 and 1, inclusive");
323 }
324 accelerationPriority = priority;
325 if (surfaceManager != null) {
326 surfaceManager.setAccelerationPriority(accelerationPriority);
327 }
328 }
329
330 /**
331 * Returns the current value of the acceleration priority hint.
332 * @see #setAccelerationPriority(float priority) setAccelerationPriority
333 * @return value between 0 and 1, inclusive, which represents the current
334 * priority value
335 * @since 1.5
336 */
337 public float getAccelerationPriority() {
338 return accelerationPriority;
339 }
340
341 SurfaceManager surfaceManager;
342
343 static {
344 SurfaceManager.setImageAccessor(new SurfaceManager.ImageAccessor() {
345 public SurfaceManager getSurfaceManager(Image img) {
346 return img.surfaceManager;
347 }
348 public void setSurfaceManager(Image img, SurfaceManager mgr) {
349 img.surfaceManager = mgr;
350 }
351 });
352 }
353 }
Save This Page