Image


1   /*
2    * @(#)Image.java   1.39 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.awt;
8   
9   import java.awt.image.ImageProducer  ;
10  import java.awt.image.ImageObserver  ;
11  import java.awt.image.ImageFilter  ;
12  import java.awt.image.FilteredImageSource  ;
13  import java.awt.image.AreaAveragingScaleFilter  ;
14  import java.awt.image.ReplicateScaleFilter  ;
15  
16  /**
17   * The abstract class <code>Image</code> is the superclass of all 
18   * classes that represent graphical images. The image must be 
19   * obtained in a platform-specific manner.
20   *
21   * @version     1.39, 12/19/03
22   * @author  Sami Shaio
23   * @author  Arthur van Hoff
24   * @since       JDK1.0
25   */
26  public abstract class Image {
27      
28      /**
29       * convenience object; we can use this single static object for 
30       * all images that do not create their own image caps; it holds the
31       * default (unaccelerated) properties.
32       */
33      private static ImageCapabilities   defaultImageCaps = 
34      new ImageCapabilities  (false);
35  
36      /**
37       * Priority for accelerating this image.  Subclasses are free to
38       * set different default priorities and applications are free to
39       * set the priority for specific images via the
40       * <code>setAccelerationPriority(float)</code> method.
41       * @since 1.5
42       */
43      protected float accelerationPriority = .5f;
44  
45      /**
46       * Determines the width of the image. If the width is not yet known, 
47       * this method returns <code>-1</code> and the specified   
48       * <code>ImageObserver</code> object is notified later.
49       * @param     observer   an object waiting for the image to be loaded.
50       * @return    the width of this image, or <code>-1</code> 
51       *                   if the width is not yet known.
52       * @see       java.awt.Image#getHeight
53       * @see       java.awt.image.ImageObserver
54       */
55      public abstract int getWidth(ImageObserver   observer);
56  
57      /**
58       * Determines the height of the image. If the height is not yet known, 
59       * this method returns <code>-1</code> and the specified  
60       * <code>ImageObserver</code> object is notified later.
61       * @param     observer   an object waiting for the image to be loaded.
62       * @return    the height of this image, or <code>-1</code> 
63       *                   if the height is not yet known.
64       * @see       java.awt.Image#getWidth
65       * @see       java.awt.image.ImageObserver
66       */
67      public abstract int getHeight(ImageObserver   observer);
68  
69      /**
70       * Gets the object that produces the pixels for the image.
71       * This method is called by the image filtering classes and by 
72       * methods that perform image conversion and scaling.
73       * @return     the image producer that produces the pixels 
74       *                                  for this image.
75       * @see        java.awt.image.ImageProducer
76       */
77      public abstract ImageProducer   getSource();
78  
79      /**
80       * Creates a graphics context for drawing to an off-screen image. 
81       * This method can only be called for off-screen images. 
82       * @return  a graphics context to draw to the off-screen image. 
83       * @exception UnsupportedOperationException if called for a 
84       *            non-off-screen image.
85       * @see     java.awt.Graphics
86       * @see     java.awt.Component#createImage(int, int)
87       */
88      public abstract Graphics   getGraphics();
89  
90      /**
91       * Gets a property of this image by name. 
92       * <p>
93       * Individual property names are defined by the various image 
94       * formats. If a property is not defined for a particular image, this 
95       * method returns the <code>UndefinedProperty</code> object. 
96       * <p>
97       * If the properties for this image are not yet known, this method 
98       * returns <code>null</code>, and the <code>ImageObserver</code> 
99       * object is notified later. 
100      * <p>
101      * The property name <code>"comment"</code> should be used to store 
102      * an optional comment which can be presented to the application as a 
103      * description of the image, its source, or its author. 
104      * @param       name   a property name.
105      * @param       observer   an object waiting for this image to be loaded.
106      * @return      the value of the named property.
107      * @throws      <code>NullPointerException<code> if the property name is null.
108      * @see         java.awt.image.ImageObserver
109      * @see         java.awt.Image#UndefinedProperty
110      */
111     public abstract Object   getProperty(String   name, ImageObserver   observer);
112 
113     /**
114      * The <code>UndefinedProperty</code> object should be returned whenever a
115      * property which was not defined for a particular image is fetched.
116      */
117     public static final Object   UndefinedProperty = new Object  ();
118 
119     /**
120      * Creates a scaled version of this image.
121      * A new <code>Image</code> object is returned which will render 
122      * the image at the specified <code>width</code> and 
123      * <code>height</code> by default.  The new <code>Image</code> object
124      * may be loaded asynchronously even if the original source image
125      * has already been loaded completely.  
126      *
127      * <p>
128      * 
129      * If either <code>width</code> 
130      * or <code>height</code> is a negative number then a value is 
131      * substituted to maintain the aspect ratio of the original image 
132      * dimensions. If both <code>width</code> and <code>height</code>
133      * are negative, then the original image dimensions are used.
134      *
135      * @param width the width to which to scale the image.
136      * @param height the height to which to scale the image.
137      * @param hints flags to indicate the type of algorithm to use
138      * for image resampling.
139      * @return     a scaled version of the image.
140      * @exception IllegalArgumentException if <code>width</code>
141      *             or <code>height</code> is zero.
142      * @see        java.awt.Image#SCALE_DEFAULT
143      * @see        java.awt.Image#SCALE_FAST 
144      * @see        java.awt.Image#SCALE_SMOOTH
145      * @see        java.awt.Image#SCALE_REPLICATE
146      * @see        java.awt.Image#SCALE_AREA_AVERAGING
147      * @since      JDK1.1
148      */
149     public Image   getScaledInstance(int width, int height, int hints) {
150     ImageFilter   filter;
151     if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
152         filter = new AreaAveragingScaleFilter  (width, height);
153     } else {
154         filter = new ReplicateScaleFilter  (width, height);
155     }
156     ImageProducer   prod;
157     prod = new FilteredImageSource  (getSource(), filter);
158     return Toolkit.getDefaultToolkit().createImage(prod);
159     }
160 
161     /**
162      * Use the default image-scaling algorithm.
163      * @since JDK1.1
164      */
165     public static final int SCALE_DEFAULT = 1;
166 
167     /**
168      * Choose an image-scaling algorithm that gives higher priority
169      * to scaling speed than smoothness of the scaled image.
170      * @since JDK1.1
171      */
172     public static final int SCALE_FAST = 2;
173 
174     /**
175      * Choose an image-scaling algorithm that gives higher priority
176      * to image smoothness than scaling speed.
177      * @since JDK1.1
178      */
179     public static final int SCALE_SMOOTH = 4;
180 
181     /**
182      * Use the image scaling algorithm embodied in the 
183      * <code>ReplicateScaleFilter</code> class.  
184      * The <code>Image</code> object is free to substitute a different filter 
185      * that performs the same algorithm yet integrates more efficiently
186      * into the imaging infrastructure supplied by the toolkit.
187      * @see        java.awt.image.ReplicateScaleFilter
188      * @since      JDK1.1
189      */
190     public static final int SCALE_REPLICATE = 8;
191 
192     /**
193      * Use the Area Averaging image scaling algorithm.  The
194      * image object is free to substitute a different filter that
195      * performs the same algorithm yet integrates more efficiently
196      * into the image infrastructure supplied by the toolkit.
197      * @see java.awt.image.AreaAveragingScaleFilter
198      * @since JDK1.1
199      */
200     public static final int SCALE_AREA_AVERAGING = 16;
201 
202     /**
203      * Flushes all resources being used by this Image object.  This
204      * includes any pixel data that is being cached for rendering to
205      * the screen as well as any system resources that are being used
206      * to store data or pixels for the image.  The image is reset to
207      * a state similar to when it was first created so that if it is
208      * again rendered, the image data will have to be recreated or
209      * fetched again from its source.
210      * <p>
211      * This method always leaves the image in a state such that it can 
212      * be reconstructed.  This means the method applies only to cached 
213      * or other secondary representations of images such as those that 
214      * have been generated from an <tt>ImageProducer</tt> (read from a 
215      * file, for example). It does nothing for off-screen images that 
216      * have only one copy of their data.
217      */
218     public abstract void flush();
219 
220     /**
221      * Returns an ImageCapabilities object which can be
222      * inquired as to the capabilities of this
223      * Image on the specified GraphicsConfiguration.
224      * This allows programmers to find
225      * out more runtime information on the specific Image
226      * object that they have created.  For example, the user
227      * might create a BufferedImage but the system may have
228      * no video memory left for creating an image of that
229      * size on the given GraphicsConfiguration, so although the object
230      * may be acceleratable in general, it is
231      * does not have that capability on this GraphicsConfiguration.
232      * @param gc a <code>GraphicsConfiguration</code> object.  A value of null
233      * for this parameter will result in getting the image capabilities
234      * for the default <code>GraphicsConfiguration</code>.
235      * @return an <code>ImageCapabilities</code> object that contains
236      * the capabilities of this <code>Image</code> on the specified
237      * GraphicsConfiguration.
238      * @see #java.awt.image.VolatileImage.getCapabilities()
239      * VolatileImage.getCapabilities()
240      * @since 1.5
241      */
242     public ImageCapabilities   getCapabilities(GraphicsConfiguration   gc) {
243     // Note: this is just a default object that gets returned by the
244     // base Image object.  Subclasses of Image should override this
245     // method and return an ImageCapabilities object that is appropriate
246     // for a given instance of that subclass.
247     return defaultImageCaps;
248     }
249     
250     /**
251      * Sets a hint for this image about how important acceleration is.
252      * This priority hint is used to compare to the priorities of other
253      * Image objects when determining how to use scarce acceleration
254      * resources such as video memory.  When and if it is possible to
255      * accelerate this Image, if there are not enough resources available
256      * to provide that acceleration but enough can be freed up by
257      * de-acceleration some other image of lower priority, then that other
258      * Image may be de-accelerated in deference to this one.  Images
259      * that have the same priority take up resources on a first-come,
260      * first-served basis.
261      * @param priority a value between 0 and 1, inclusive, where higher
262      * values indicate more importance for acceleration.  A value of 0
263      * means that this Image should never be accelerated.  Other values
264      * are used simply to determine acceleration priority relative to other
265      * Images.
266      * @throws IllegalArgumentException if <code>priority</code> is less
267      * than zero or greater than 1.
268      * @since 1.5
269      */
270     public void setAccelerationPriority(float priority) {
271         if (priority < 0 || priority > 1) {
272             throw new IllegalArgumentException  ("Priority must be a value " +
273                            "between 0 and 1, inclusive");
274         }
275     accelerationPriority = priority;
276     }
277 
278     /**
279      * Returns the current value of the acceleration priority hint.
280      * @see #setAccelerationPriority(float priority) setAccelerationPriority
281      * @return value between 0 and 1, inclusive, which represents the current
282      * priority value
283      * @since 1.5
284      */
285     public float getAccelerationPriority() {
286     return accelerationPriority;
287     }
288 }
289
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags