Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1995, 2007, 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    * The abstract class <code>Image</code> is the superclass of all
   38    * classes that represent graphical images. The image must be
   39    * obtained in a platform-specific manner.
   40    *
   41    * @author      Sami Shaio
   42    * @author      Arthur van Hoff
   43    * @since       JDK1.0
   44    */
   45   public abstract class Image {
   46   
   47       /**
   48        * convenience object; we can use this single static object for
   49        * all images that do not create their own image caps; it holds the
   50        * default (unaccelerated) properties.
   51        */
   52       private static ImageCapabilities defaultImageCaps =
   53           new ImageCapabilities(false);
   54   
   55       /**
   56        * Priority for accelerating this image.  Subclasses are free to
   57        * set different default priorities and applications are free to
   58        * set the priority for specific images via the
   59        * <code>setAccelerationPriority(float)</code> method.
   60        * @since 1.5
   61        */
   62       protected float accelerationPriority = .5f;
   63   
   64       /**
   65        * Determines the width of the image. If the width is not yet known,
   66        * this method returns <code>-1</code> and the specified
   67        * <code>ImageObserver</code> object is notified later.
   68        * @param     observer   an object waiting for the image to be loaded.
   69        * @return    the width of this image, or <code>-1</code>
   70        *                   if the width is not yet known.
   71        * @see       java.awt.Image#getHeight
   72        * @see       java.awt.image.ImageObserver
   73        */
   74       public abstract int getWidth(ImageObserver observer);
   75   
   76       /**
   77        * Determines the height of the image. If the height is not yet known,
   78        * this method returns <code>-1</code> and the specified
   79        * <code>ImageObserver</code> object is notified later.
   80        * @param     observer   an object waiting for the image to be loaded.
   81        * @return    the height of this image, or <code>-1</code>
   82        *                   if the height is not yet known.
   83        * @see       java.awt.Image#getWidth
   84        * @see       java.awt.image.ImageObserver
   85        */
   86       public abstract int getHeight(ImageObserver observer);
   87   
   88       /**
   89        * Gets the object that produces the pixels for the image.
   90        * This method is called by the image filtering classes and by
   91        * methods that perform image conversion and scaling.
   92        * @return     the image producer that produces the pixels
   93        *                                  for this image.
   94        * @see        java.awt.image.ImageProducer
   95        */
   96       public abstract ImageProducer getSource();
   97   
   98       /**
   99        * Creates a graphics context for drawing to an off-screen image.
  100        * This method can only be called for off-screen images.
  101        * @return  a graphics context to draw to the off-screen image.
  102        * @exception UnsupportedOperationException if called for a
  103        *            non-off-screen image.
  104        * @see     java.awt.Graphics
  105        * @see     java.awt.Component#createImage(int, int)
  106        */
  107       public abstract Graphics getGraphics();
  108   
  109       /**
  110        * Gets a property of this image by name.
  111        * <p>
  112        * Individual property names are defined by the various image
  113        * formats. If a property is not defined for a particular image, this
  114        * method returns the <code>UndefinedProperty</code> object.
  115        * <p>
  116        * If the properties for this image are not yet known, this method
  117        * returns <code>null</code>, and the <code>ImageObserver</code>
  118        * object is notified later.
  119        * <p>
  120        * The property name <code>"comment"</code> should be used to store
  121        * an optional comment which can be presented to the application as a
  122        * description of the image, its source, or its author.
  123        * @param       name   a property name.
  124        * @param       observer   an object waiting for this image to be loaded.
  125        * @return      the value of the named property.
  126        * @throws      <code>NullPointerException</code> if the property name is null.
  127        * @see         java.awt.image.ImageObserver
  128        * @see         java.awt.Image#UndefinedProperty
  129        */
  130       public abstract Object getProperty(String name, ImageObserver observer);
  131   
  132       /**
  133        * The <code>UndefinedProperty</code> object should be returned whenever a
  134        * property which was not defined for a particular image is fetched.
  135        */
  136       public static final Object UndefinedProperty = new Object();
  137   
  138       /**
  139        * Creates a scaled version of this image.
  140        * A new <code>Image</code> object is returned which will render
  141        * the image at the specified <code>width</code> and
  142        * <code>height</code> by default.  The new <code>Image</code> object
  143        * may be loaded asynchronously even if the original source image
  144        * has already been loaded completely.
  145        *
  146        * <p>
  147        *
  148        * If either <code>width</code>
  149        * or <code>height</code> is a negative number then a value is
  150        * substituted to maintain the aspect ratio of the original image
  151        * dimensions. If both <code>width</code> and <code>height</code>
  152        * are negative, then the original image dimensions are used.
  153        *
  154        * @param width the width to which to scale the image.
  155        * @param height the height to which to scale the image.
  156        * @param hints flags to indicate the type of algorithm to use
  157        * for image resampling.
  158        * @return     a scaled version of the image.
  159        * @exception IllegalArgumentException if <code>width</code>
  160        *             or <code>height</code> is zero.
  161        * @see        java.awt.Image#SCALE_DEFAULT
  162        * @see        java.awt.Image#SCALE_FAST
  163        * @see        java.awt.Image#SCALE_SMOOTH
  164        * @see        java.awt.Image#SCALE_REPLICATE
  165        * @see        java.awt.Image#SCALE_AREA_AVERAGING
  166        * @since      JDK1.1
  167        */
  168       public Image getScaledInstance(int width, int height, int hints) {
  169           ImageFilter filter;
  170           if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
  171               filter = new AreaAveragingScaleFilter(width, height);
  172           } else {
  173               filter = new ReplicateScaleFilter(width, height);
  174           }
  175           ImageProducer prod;
  176           prod = new FilteredImageSource(getSource(), filter);
  177           return Toolkit.getDefaultToolkit().createImage(prod);
  178       }
  179   
  180       /**
  181        * Use the default image-scaling algorithm.
  182        * @since JDK1.1
  183        */
  184       public static final int SCALE_DEFAULT = 1;
  185   
  186       /**
  187        * Choose an image-scaling algorithm that gives higher priority
  188        * to scaling speed than smoothness of the scaled image.
  189        * @since JDK1.1
  190        */
  191       public static final int SCALE_FAST = 2;
  192   
  193       /**
  194        * Choose an image-scaling algorithm that gives higher priority
  195        * to image smoothness than scaling speed.
  196        * @since JDK1.1
  197        */
  198       public static final int SCALE_SMOOTH = 4;
  199   
  200       /**
  201        * Use the image scaling algorithm embodied in the
  202        * <code>ReplicateScaleFilter</code> class.
  203        * The <code>Image</code> object is free to substitute a different filter
  204        * that performs the same algorithm yet integrates more efficiently
  205        * into the imaging infrastructure supplied by the toolkit.
  206        * @see        java.awt.image.ReplicateScaleFilter
  207        * @since      JDK1.1
  208        */
  209       public static final int SCALE_REPLICATE = 8;
  210   
  211       /**
  212        * Use the Area Averaging image scaling algorithm.  The
  213        * image object is free to substitute a different filter that
  214        * performs the same algorithm yet integrates more efficiently
  215        * into the image infrastructure supplied by the toolkit.
  216        * @see java.awt.image.AreaAveragingScaleFilter
  217        * @since JDK1.1
  218        */
  219       public static final int SCALE_AREA_AVERAGING = 16;
  220   
  221       /**
  222        * Flushes all reconstructable resources being used by this Image object.
  223        * This includes any pixel data that is being cached for rendering to
  224        * the screen as well as any system resources that are being used
  225        * to store data or pixels for the image if they can be recreated.
  226        * The image is reset to a state similar to when it was first created
  227        * so that if it is again rendered, the image data will have to be
  228        * recreated or fetched again from its source.
  229        * <p>
  230        * Examples of how this method affects specific types of Image object:
  231        * <ul>
  232        * <li>
  233        * BufferedImage objects leave the primary Raster which stores their
  234        * pixels untouched, but flush any information cached about those
  235        * pixels such as copies uploaded to the display hardware for
  236        * accelerated blits.
  237        * <li>
  238        * Image objects created by the Component methods which take a
  239        * width and height leave their primary buffer of pixels untouched,
  240        * but have all cached information released much like is done for
  241        * BufferedImage objects.
  242        * <li>
  243        * VolatileImage objects release all of their pixel resources
  244        * including their primary copy which is typically stored on
  245        * the display hardware where resources are scarce.
  246        * These objects can later be restored using their
  247        * {@link java.awt.image.VolatileImage#validate validate}
  248        * method.
  249        * <li>
  250        * Image objects created by the Toolkit and Component classes which are
  251        * loaded from files, URLs or produced by an {@link ImageProducer}
  252        * are unloaded and all local resources are released.
  253        * These objects can later be reloaded from their original source
  254        * as needed when they are rendered, just as when they were first
  255        * created.
  256        * </ul>
  257        */
  258       public void flush() {
  259           if (surfaceManager != null) {
  260               surfaceManager.flush();
  261           }
  262       }
  263   
  264       /**
  265        * Returns an ImageCapabilities object which can be
  266        * inquired as to the capabilities of this
  267        * Image on the specified GraphicsConfiguration.
  268        * This allows programmers to find
  269        * out more runtime information on the specific Image
  270        * object that they have created.  For example, the user
  271        * might create a BufferedImage but the system may have
  272        * no video memory left for creating an image of that
  273        * size on the given GraphicsConfiguration, so although the object
  274        * may be acceleratable in general, it
  275        * does not have that capability on this GraphicsConfiguration.
  276        * @param gc a <code>GraphicsConfiguration</code> object.  A value of null
  277        * for this parameter will result in getting the image capabilities
  278        * for the default <code>GraphicsConfiguration</code>.
  279        * @return an <code>ImageCapabilities</code> object that contains
  280        * the capabilities of this <code>Image</code> on the specified
  281        * GraphicsConfiguration.
  282        * @see java.awt.image.VolatileImage#getCapabilities()
  283        * VolatileImage.getCapabilities()
  284        * @since 1.5
  285        */
  286       public ImageCapabilities getCapabilities(GraphicsConfiguration gc) {
  287           if (surfaceManager != null) {
  288               return surfaceManager.getCapabilities(gc);
  289           }
  290           // Note: this is just a default object that gets returned in the
  291           // absence of any more specific information from a surfaceManager.
  292           // Subclasses of Image should either override this method or
  293           // make sure that they always have a non-null SurfaceManager
  294           // to return an ImageCapabilities object that is appropriate
  295           // for their given subclass type.
  296           return defaultImageCaps;
  297       }
  298   
  299       /**
  300        * Sets a hint for this image about how important acceleration is.
  301        * This priority hint is used to compare to the priorities of other
  302        * Image objects when determining how to use scarce acceleration
  303        * resources such as video memory.  When and if it is possible to
  304        * accelerate this Image, if there are not enough resources available
  305        * to provide that acceleration but enough can be freed up by
  306        * de-accelerating some other image of lower priority, then that other
  307        * Image may be de-accelerated in deference to this one.  Images
  308        * that have the same priority take up resources on a first-come,
  309        * first-served basis.
  310        * @param priority a value between 0 and 1, inclusive, where higher
  311        * values indicate more importance for acceleration.  A value of 0
  312        * means that this Image should never be accelerated.  Other values
  313        * are used simply to determine acceleration priority relative to other
  314        * Images.
  315        * @throws IllegalArgumentException if <code>priority</code> is less
  316        * than zero or greater than 1.
  317        * @since 1.5
  318        */
  319       public void setAccelerationPriority(float priority) {
  320           if (priority < 0 || priority > 1) {
  321               throw new IllegalArgumentException("Priority must be a value " +
  322                                                  "between 0 and 1, inclusive");
  323           }
  324           accelerationPriority = priority;
  325           if (surfaceManager != null) {
  326               surfaceManager.setAccelerationPriority(accelerationPriority);
  327           }
  328       }
  329   
  330       /**
  331        * Returns the current value of the acceleration priority hint.
  332        * @see #setAccelerationPriority(float priority) setAccelerationPriority
  333        * @return value between 0 and 1, inclusive, which represents the current
  334        * priority value
  335        * @since 1.5
  336        */
  337       public float getAccelerationPriority() {
  338           return accelerationPriority;
  339       }
  340   
  341       SurfaceManager surfaceManager;
  342   
  343       static {
  344           SurfaceManager.setImageAccessor(new SurfaceManager.ImageAccessor() {
  345               public SurfaceManager getSurfaceManager(Image img) {
  346                   return img.surfaceManager;
  347               }
  348               public void setSurfaceManager(Image img, SurfaceManager mgr) {
  349                   img.surfaceManager = mgr;
  350               }
  351           });
  352       }
  353   }

Home » openjdk-7 » java » awt » [javadoc | source]