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