001 /*
002 * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.awt.image.ImageProducer;
028 import java.awt.image.ImageObserver;
029 import java.awt.image.ImageFilter;
030 import java.awt.image.FilteredImageSource;
031 import java.awt.image.AreaAveragingScaleFilter;
032 import java.awt.image.ReplicateScaleFilter;
033
034 import sun.awt.image.SurfaceManager;
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 *
041 * @version 1.50, 05/05/07
042 * @author Sami Shaio
043 * @author Arthur van Hoff
044 * @since JDK1.0
045 */
046 public abstract class Image {
047
048 /**
049 * convenience object; we can use this single static object for
050 * all images that do not create their own image caps; it holds the
051 * default (unaccelerated) properties.
052 */
053 private static ImageCapabilities defaultImageCaps = new ImageCapabilities(
054 false);
055
056 /**
057 * Priority for accelerating this image. Subclasses are free to
058 * set different default priorities and applications are free to
059 * set the priority for specific images via the
060 * <code>setAccelerationPriority(float)</code> method.
061 * @since 1.5
062 */
063 protected float accelerationPriority = .5f;
064
065 /**
066 * Determines the width of the image. If the width is not yet known,
067 * this method returns <code>-1</code> and the specified
068 * <code>ImageObserver</code> object is notified later.
069 * @param observer an object waiting for the image to be loaded.
070 * @return the width of this image, or <code>-1</code>
071 * if the width is not yet known.
072 * @see java.awt.Image#getHeight
073 * @see java.awt.image.ImageObserver
074 */
075 public abstract int getWidth(ImageObserver observer);
076
077 /**
078 * Determines the height of the image. If the height is not yet known,
079 * this method returns <code>-1</code> and the specified
080 * <code>ImageObserver</code> object is notified later.
081 * @param observer an object waiting for the image to be loaded.
082 * @return the height of this image, or <code>-1</code>
083 * if the height is not yet known.
084 * @see java.awt.Image#getWidth
085 * @see java.awt.image.ImageObserver
086 */
087 public abstract int getHeight(ImageObserver observer);
088
089 /**
090 * Gets the object that produces the pixels for the image.
091 * This method is called by the image filtering classes and by
092 * methods that perform image conversion and scaling.
093 * @return the image producer that produces the pixels
094 * for this image.
095 * @see java.awt.image.ImageProducer
096 */
097 public abstract ImageProducer getSource();
098
099 /**
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</code> object.
116 * <p>
117 * If the properties for this image are not yet known, this method
118 * returns <code>null</code>, and the <code>ImageObserver</code>
119 * object is notified later.
120 * <p>
121 * The property name <code>"comment"</code> 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 <code>NullPointerException</code> 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,
132 ImageObserver observer);
133
134 /**
135 * The <code>UndefinedProperty</code> object should be returned whenever a
136 * property which was not defined for a particular image is fetched.
137 */
138 public static final Object UndefinedProperty = new Object();
139
140 /**
141 * Creates a scaled version of this image.
142 * A new <code>Image</code> object is returned which will render
143 * the image at the specified <code>width</code> and
144 * <code>height</code> by default. The new <code>Image</code> object
145 * may be loaded asynchronously even if the original source image
146 * has already been loaded completely.
147 *
148 * <p>
149 *
150 * If either <code>width</code>
151 * or <code>height</code> is a negative number then a value is
152 * substituted to maintain the aspect ratio of the original image
153 * dimensions. If both <code>width</code> and <code>height</code>
154 * are negative, then the original image dimensions are used.
155 *
156 * @param width the width to which to scale the image.
157 * @param height the height to which to scale the image.
158 * @param hints flags to indicate the type of algorithm to use
159 * for image resampling.
160 * @return a scaled version of the image.
161 * @exception IllegalArgumentException if <code>width</code>
162 * or <code>height</code> is zero.
163 * @see java.awt.Image#SCALE_DEFAULT
164 * @see java.awt.Image#SCALE_FAST
165 * @see java.awt.Image#SCALE_SMOOTH
166 * @see java.awt.Image#SCALE_REPLICATE
167 * @see java.awt.Image#SCALE_AREA_AVERAGING
168 * @since JDK1.1
169 */
170 public Image getScaledInstance(int width, int height, int hints) {
171 ImageFilter filter;
172 if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
173 filter = new AreaAveragingScaleFilter(width, height);
174 } else {
175 filter = new ReplicateScaleFilter(width, height);
176 }
177 ImageProducer prod;
178 prod = new FilteredImageSource(getSource(), filter);
179 return Toolkit.getDefaultToolkit().createImage(prod);
180 }
181
182 /**
183 * Use the default image-scaling algorithm.
184 * @since JDK1.1
185 */
186 public static final int SCALE_DEFAULT = 1;
187
188 /**
189 * Choose an image-scaling algorithm that gives higher priority
190 * to scaling speed than smoothness of the scaled image.
191 * @since JDK1.1
192 */
193 public static final int SCALE_FAST = 2;
194
195 /**
196 * Choose an image-scaling algorithm that gives higher priority
197 * to image smoothness than scaling speed.
198 * @since JDK1.1
199 */
200 public static final int SCALE_SMOOTH = 4;
201
202 /**
203 * Use the image scaling algorithm embodied in the
204 * <code>ReplicateScaleFilter</code> class.
205 * The <code>Image</code> object is free to substitute a different filter
206 * that performs the same algorithm yet integrates more efficiently
207 * into the imaging infrastructure supplied by the toolkit.
208 * @see java.awt.image.ReplicateScaleFilter
209 * @since JDK1.1
210 */
211 public static final int SCALE_REPLICATE = 8;
212
213 /**
214 * Use the Area Averaging image scaling algorithm. The
215 * image object is free to substitute a different filter that
216 * performs the same algorithm yet integrates more efficiently
217 * into the image infrastructure supplied by the toolkit.
218 * @see java.awt.image.AreaAveragingScaleFilter
219 * @since JDK1.1
220 */
221 public static final int SCALE_AREA_AVERAGING = 16;
222
223 /**
224 * Flushes all reconstructable resources being used by this Image object.
225 * This includes any pixel data that is being cached for rendering to
226 * the screen as well as any system resources that are being used
227 * to store data or pixels for the image if they can be recreated.
228 * The image is reset to a state similar to when it was first created
229 * so that if it is again rendered, the image data will have to be
230 * recreated or fetched again from its source.
231 * <p>
232 * Examples of how this method affects specific types of Image object:
233 * <ul>
234 * <li>
235 * BufferedImage objects leave the primary Raster which stores their
236 * pixels untouched, but flush any information cached about those
237 * pixels such as copies uploaded to the display hardware for
238 * accelerated blits.
239 * <li>
240 * Image objects created by the Component methods which take a
241 * width and height leave their primary buffer of pixels untouched,
242 * but have all cached information released much like is done for
243 * BufferedImage objects.
244 * <li>
245 * VolatileImage objects release all of their pixel resources
246 * including their primary copy which is typically stored on
247 * the display hardware where resources are scarce.
248 * These objects can later be restored using their
249 * {@link java.awt.image.VolatileImage#validate validate}
250 * method.
251 * <li>
252 * Image objects created by the Toolkit and Component classes which are
253 * loaded from files, URLs or produced by an {@link ImageProducer}
254 * are unloaded and all local resources are released.
255 * These objects can later be reloaded from their original source
256 * as needed when they are rendered, just as when they were first
257 * created.
258 * </ul>
259 */
260 public void flush() {
261 if (surfaceManager != null) {
262 surfaceManager.flush();
263 }
264 }
265
266 /**
267 * Returns an ImageCapabilities object which can be
268 * inquired as to the capabilities of this
269 * Image on the specified GraphicsConfiguration.
270 * This allows programmers to find
271 * out more runtime information on the specific Image
272 * object that they have created. For example, the user
273 * might create a BufferedImage but the system may have
274 * no video memory left for creating an image of that
275 * size on the given GraphicsConfiguration, so although the object
276 * may be acceleratable in general, it
277 * does not have that capability on this GraphicsConfiguration.
278 * @param gc a <code>GraphicsConfiguration</code> object. A value of null
279 * for this parameter will result in getting the image capabilities
280 * for the default <code>GraphicsConfiguration</code>.
281 * @return an <code>ImageCapabilities</code> object that contains
282 * the capabilities of this <code>Image</code> on the specified
283 * GraphicsConfiguration.
284 * @see java.awt.image.VolatileImage#getCapabilities()
285 * VolatileImage.getCapabilities()
286 * @since 1.5
287 */
288 public ImageCapabilities getCapabilities(GraphicsConfiguration gc) {
289 if (surfaceManager != null) {
290 return surfaceManager.getCapabilities(gc);
291 }
292 // Note: this is just a default object that gets returned in the
293 // absence of any more specific information from a surfaceManager.
294 // Subclasses of Image should either override this method or
295 // make sure that they always have a non-null SurfaceManager
296 // to return an ImageCapabilities object that is appropriate
297 // for their given subclass type.
298 return defaultImageCaps;
299 }
300
301 /**
302 * Sets a hint for this image about how important acceleration is.
303 * This priority hint is used to compare to the priorities of other
304 * Image objects when determining how to use scarce acceleration
305 * resources such as video memory. When and if it is possible to
306 * accelerate this Image, if there are not enough resources available
307 * to provide that acceleration but enough can be freed up by
308 * de-accelerating some other image of lower priority, then that other
309 * Image may be de-accelerated in deference to this one. Images
310 * that have the same priority take up resources on a first-come,
311 * first-served basis.
312 * @param priority a value between 0 and 1, inclusive, where higher
313 * values indicate more importance for acceleration. A value of 0
314 * means that this Image should never be accelerated. Other values
315 * are used simply to determine acceleration priority relative to other
316 * Images.
317 * @throws IllegalArgumentException if <code>priority</code> is less
318 * than zero or greater than 1.
319 * @since 1.5
320 */
321 public void setAccelerationPriority(float priority) {
322 if (priority < 0 || priority > 1) {
323 throw new IllegalArgumentException(
324 "Priority must be a value "
325 + "between 0 and 1, inclusive");
326 }
327 accelerationPriority = priority;
328 if (surfaceManager != null) {
329 surfaceManager
330 .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
349 .setImageAccessor(new SurfaceManager.ImageAccessor() {
350 public SurfaceManager getSurfaceManager(Image img) {
351 return img.surfaceManager;
352 }
353
354 public void setSurfaceManager(Image img,
355 SurfaceManager mgr) {
356 img.surfaceManager = mgr;
357 }
358 });
359 }
360 }
|