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

    1   /*
    2    * Copyright (c) 2000, 2006, 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   
   26   package java.awt.image;
   27   
   28   import java.awt.Color;
   29   import java.awt.Graphics;
   30   import java.awt.Graphics2D;
   31   import java.awt.GraphicsConfiguration;
   32   import java.awt.GraphicsDevice;
   33   import java.awt.Image;
   34   import java.awt.ImageCapabilities;
   35   import java.awt.Toolkit;
   36   import java.awt.Transparency;
   37   
   38   /**
   39    * VolatileImage is an image which can lose its
   40    * contents at any time due to circumstances beyond the control of the
   41    * application (e.g., situations caused by the operating system or by
   42    * other applications). Because of the potential for hardware acceleration,
   43    * a VolatileImage object can have significant performance benefits on
   44    * some platforms.
   45    * <p>
   46    * The drawing surface of an image (the memory where the image contents
   47    * actually reside) can be lost or invalidated, causing the contents of that
   48    * memory to go away.  The drawing surface thus needs to be restored
   49    * or recreated and the contents of that surface need to be
   50    * re-rendered.  VolatileImage provides an interface for
   51    * allowing the user to detect these problems and fix them
   52    * when they occur.
   53    * <p>
   54    * When a VolatileImage object is created, limited system resources
   55    * such as video memory (VRAM) may be allocated in order to support
   56    * the image.
   57    * When a VolatileImage object is no longer used, it may be
   58    * garbage-collected and those system resources will be returned,
   59    * but this process does not happen at guaranteed times.
   60    * Applications that create many VolatileImage objects (for example,
   61    * a resizing window may force recreation of its back buffer as the
   62    * size changes) may run out of optimal system resources for new
   63    * VolatileImage objects simply because the old objects have not
   64    * yet been removed from the system.
   65    * (New VolatileImage objects may still be created, but they
   66    * may not perform as well as those created in accelerated
   67    * memory).
   68    * The flush method may be called at any time to proactively release
   69    * the resources used by a VolatileImage so that it does not prevent
   70    * subsequent VolatileImage objects from being accelerated.
   71    * In this way, applications can have more control over the state
   72    * of the resources taken up by obsolete VolatileImage objects.
   73    * <p>
   74    * This image should not be subclassed directly but should be created
   75    * by using the {@link java.awt.Component#createVolatileImage(int, int)
   76    * Component.createVolatileImage} or
   77    * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
   78    * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
   79    * <P>
   80    * An example of using a VolatileImage object follows:
   81    * <pre>
   82    * // image creation
   83    * VolatileImage vImg = createVolatileImage(w, h);
   84    *
   85    *
   86    * // rendering to the image
   87    * void renderOffscreen() {
   88    *      do {
   89    *          if (vImg.validate(getGraphicsConfiguration()) ==
   90    *              VolatileImage.IMAGE_INCOMPATIBLE)
   91    *          {
   92    *              // old vImg doesn't work with new GraphicsConfig; re-create it
   93    *              vImg = createVolatileImage(w, h);
   94    *          }
   95    *          Graphics2D g = vImg.createGraphics();
   96    *          //
   97    *          // miscellaneous rendering commands...
   98    *          //
   99    *          g.dispose();
  100    *      } while (vImg.contentsLost());
  101    * }
  102    *
  103    *
  104    * // copying from the image (here, gScreen is the Graphics
  105    * // object for the onscreen window)
  106    * do {
  107    *      int returnCode = vImg.validate(getGraphicsConfiguration());
  108    *      if (returnCode == VolatileImage.IMAGE_RESTORED) {
  109    *          // Contents need to be restored
  110    *          renderOffscreen();      // restore contents
  111    *      } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
  112    *          // old vImg doesn't work with new GraphicsConfig; re-create it
  113    *          vImg = createVolatileImage(w, h);
  114    *          renderOffscreen();
  115    *      }
  116    *      gScreen.drawImage(vImg, 0, 0, this);
  117    * } while (vImg.contentsLost());
  118    * </pre>
  119    * <P>
  120    * Note that this class subclasses from the {@link Image} class, which
  121    * includes methods that take an {@link ImageObserver} parameter for
  122    * asynchronous notifications as information is received from
  123    * a potential {@link ImageProducer}.  Since this <code>VolatileImage</code>
  124    * is not loaded from an asynchronous source, the various methods that take
  125    * an <code>ImageObserver</code> parameter will behave as if the data has
  126    * already been obtained from the <code>ImageProducer</code>.
  127    * Specifically, this means that the return values from such methods
  128    * will never indicate that the information is not yet available and
  129    * the <code>ImageObserver</code> used in such methods will never
  130    * need to be recorded for an asynchronous callback notification.
  131    * @since 1.4
  132    */
  133   public abstract class VolatileImage extends Image implements Transparency
  134   {
  135   
  136       // Return codes for validate() method
  137   
  138       /**
  139        * Validated image is ready to use as-is.
  140        */
  141       public static final int IMAGE_OK = 0;
  142   
  143       /**
  144        * Validated image has been restored and is now ready to use.
  145        * Note that restoration causes contents of the image to be lost.
  146        */
  147       public static final int IMAGE_RESTORED = 1;
  148   
  149       /**
  150        * Validated image is incompatible with supplied
  151        * <code>GraphicsConfiguration</code> object and should be
  152        * re-created as appropriate.  Usage of the image as-is
  153        * after receiving this return code from <code>validate</code>
  154        * is undefined.
  155        */
  156       public static final int IMAGE_INCOMPATIBLE = 2;
  157   
  158       /**
  159        * Returns a static snapshot image of this object.  The
  160        * <code>BufferedImage</code> returned is only current with
  161        * the <code>VolatileImage</code> at the time of the request
  162        * and will not be updated with any future changes to the
  163        * <code>VolatileImage</code>.
  164        * @return a {@link BufferedImage} representation of this
  165        *          <code>VolatileImage</code>
  166        * @see BufferedImage
  167        */
  168       public abstract BufferedImage getSnapshot();
  169   
  170       /**
  171        * Returns the width of the <code>VolatileImage</code>.
  172        * @return the width of this <code>VolatileImage</code>.
  173        */
  174       public abstract int getWidth();
  175   
  176       /**
  177        * Returns the height of the <code>VolatileImage</code>.
  178        * @return the height of this <code>VolatileImage</code>.
  179        */
  180       public abstract int getHeight();
  181   
  182       // Image overrides
  183   
  184       /**
  185        * This returns an ImageProducer for this VolatileImage.
  186        * Note that the VolatileImage object is optimized for
  187        * rendering operations and blitting to the screen or other
  188        * VolatileImage objects, as opposed to reading back the
  189        * pixels of the image.  Therefore, operations such as
  190        * <code>getSource</code> may not perform as fast as
  191        * operations that do not rely on reading the pixels.
  192        * Note also that the pixel values read from the image are current
  193        * with those in the image only at the time that they are
  194        * retrieved. This method takes a snapshot
  195        * of the image at the time the request is made and the
  196        * ImageProducer object returned works with
  197        * that static snapshot image, not the original VolatileImage.
  198        * Calling getSource()
  199        * is equivalent to calling getSnapshot().getSource().
  200        * @return an {@link ImageProducer} that can be used to produce the
  201        * pixels for a <code>BufferedImage</code> representation of
  202        * this Image.
  203        * @see ImageProducer
  204        * @see #getSnapshot()
  205        */
  206       public ImageProducer getSource() {
  207           // REMIND: Make sure this functionality is in line with the
  208           // spec.  In particular, we are returning the Source for a
  209           // static image (the snapshot), not a changing image (the
  210           // VolatileImage).  So if the user expects the Source to be
  211           // up-to-date with the current contents of the VolatileImage,
  212           // they will be disappointed...
  213           // REMIND: This assumes that getSnapshot() returns something
  214           // valid and not the default null object returned by this class
  215           // (so it assumes that the actual VolatileImage object is
  216           // subclassed off something that does the right thing
  217           // (e.g., SunVolatileImage).
  218           return getSnapshot().getSource();
  219       }
  220   
  221       // REMIND: if we want any decent performance for getScaledInstance(),
  222       // we should override the Image implementation of it...
  223   
  224       /**
  225        * This method returns a {@link Graphics2D}, but is here
  226        * for backwards compatibility.  {@link #createGraphics() createGraphics} is more
  227        * convenient, since it is declared to return a
  228        * <code>Graphics2D</code>.
  229        * @return a <code>Graphics2D</code>, which can be used to draw into
  230        *          this image.
  231        */
  232       public Graphics getGraphics() {
  233           return createGraphics();
  234       }
  235   
  236       /**
  237        * Creates a <code>Graphics2D</code>, which can be used to draw into
  238        * this <code>VolatileImage</code>.
  239        * @return a <code>Graphics2D</code>, used for drawing into this
  240        *          image.
  241        */
  242       public abstract Graphics2D createGraphics();
  243   
  244   
  245       // Volatile management methods
  246   
  247       /**
  248        * Attempts to restore the drawing surface of the image if the surface
  249        * had been lost since the last <code>validate</code> call.  Also
  250        * validates this image against the given GraphicsConfiguration
  251        * parameter to see whether operations from this image to the
  252        * GraphicsConfiguration are compatible.  An example of an
  253        * incompatible combination might be a situation where a VolatileImage
  254        * object was created on one graphics device and then was used
  255        * to render to a different graphics device.  Since VolatileImage
  256        * objects tend to be very device-specific, this operation might
  257        * not work as intended, so the return code from this validate
  258        * call would note that incompatibility.  A null or incorrect
  259        * value for gc may cause incorrect values to be returned from
  260        * <code>validate</code> and may cause later problems with rendering.
  261        *
  262        * @param   gc   a <code>GraphicsConfiguration</code> object for this
  263        *          image to be validated against.  A null gc implies that the
  264        *          validate method should skip the compatibility test.
  265        * @return  <code>IMAGE_OK</code> if the image did not need validation<BR>
  266        *          <code>IMAGE_RESTORED</code> if the image needed restoration.
  267        *          Restoration implies that the contents of the image may have
  268        *          been affected and the image may need to be re-rendered.<BR>
  269        *          <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
  270        *          with the <code>GraphicsConfiguration</code> object passed
  271        *          into the <code>validate</code> method.  Incompatibility
  272        *          implies that the image may need to be recreated with a
  273        *          new <code>Component</code> or
  274        *          <code>GraphicsConfiguration</code> in order to get an image
  275        *          that can be used successfully with this
  276        *          <code>GraphicsConfiguration</code>.
  277        *          An incompatible image is not checked for whether restoration
  278        *          was necessary, so the state of the image is unchanged
  279        *          after a return value of <code>IMAGE_INCOMPATIBLE</code>
  280        *          and this return value implies nothing about whether the
  281        *          image needs to be restored.
  282        * @see java.awt.GraphicsConfiguration
  283        * @see java.awt.Component
  284        * @see #IMAGE_OK
  285        * @see #IMAGE_RESTORED
  286        * @see #IMAGE_INCOMPATIBLE
  287        */
  288       public abstract int validate(GraphicsConfiguration gc);
  289   
  290       /**
  291        * Returns <code>true</code> if rendering data was lost since last
  292        * <code>validate</code> call.  This method should be called by the
  293        * application at the end of any series of rendering operations to
  294        * or from the image to see whether
  295        * the image needs to be validated and the rendering redone.
  296        * @return <code>true</code> if the drawing surface needs to be restored;
  297        * <code>false</code> otherwise.
  298        */
  299       public abstract boolean contentsLost();
  300   
  301       /**
  302        * Returns an ImageCapabilities object which can be
  303        * inquired as to the specific capabilities of this
  304        * VolatileImage.  This would allow programmers to find
  305        * out more runtime information on the specific VolatileImage
  306        * object that they have created.  For example, the user
  307        * might create a VolatileImage but the system may have
  308        * no video memory left for creating an image of that
  309        * size, so although the object is a VolatileImage, it is
  310        * not as accelerated as other VolatileImage objects on
  311        * this platform might be.  The user might want that
  312        * information to find other solutions to their problem.
  313        * @return an <code>ImageCapabilities</code> object that contains
  314        *         the capabilities of this <code>VolatileImage</code>.
  315        * @since 1.4
  316        */
  317       public abstract ImageCapabilities getCapabilities();
  318   
  319       /**
  320        * The transparency value with which this image was created.
  321        * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
  322        *      int,int)
  323        * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
  324        *      int,ImageCapabilities,int)
  325        * @see Transparency
  326        * @since 1.5
  327        */
  328       protected int transparency = TRANSLUCENT;
  329   
  330       /**
  331        * Returns the transparency.  Returns either OPAQUE, BITMASK,
  332        * or TRANSLUCENT.
  333        * @return the transparency of this <code>VolatileImage</code>.
  334        * @see Transparency#OPAQUE
  335        * @see Transparency#BITMASK
  336        * @see Transparency#TRANSLUCENT
  337        * @since 1.5
  338        */
  339       public int getTransparency() {
  340           return transparency;
  341       }
  342   }

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