< prev index next >

src/java.desktop/share/classes/java/awt/Image.java

Print this page




  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       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)</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      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     /**


 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</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      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


 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


  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     /**


 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


 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
< prev index next >