View Javadoc
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</code> 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       JDK1.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)</code> 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</code> and the specified
68       * <code>ImageObserver</code> 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</code>
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</code> and the specified
80       * <code>ImageObserver</code> 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</code>
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</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      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</code> 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</code> object is returned which will render
142      * the image at the specified <code>width</code> and
143      * <code>height</code> by default.  The new <code>Image</code> 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</code>
150      * or <code>height</code> 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</code> and <code>height</code>
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</code>
161      *             or <code>height</code> 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      JDK1.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 JDK1.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 JDK1.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 JDK1.1
198      */
199     public static final int SCALE_SMOOTH = 4;
200 
201     /**
202      * Use the image scaling algorithm embodied in the
203      * <code>ReplicateScaleFilter</code> class.
204      * The <code>Image</code> 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      JDK1.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 JDK1.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</code> object.  A value of null
278      * for this parameter will result in getting the image capabilities
279      * for the default <code>GraphicsConfiguration</code>.
280      * @return an <code>ImageCapabilities</code> object that contains
281      * the capabilities of this <code>Image</code> 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</code> 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 }