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} 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     /**
 182      * Use the default image-scaling algorithm.
 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
 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} 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
 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 }