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: }
| 