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