1 /*
   2  * Copyright (c) 1998, 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 
  26 /* ********************************************************************
  27  **********************************************************************
  28  **********************************************************************
  29  *** COPYRIGHT (c) Eastman Kodak Company, 1997                      ***
  30  *** As  an unpublished  work pursuant to Title 17 of the United    ***
  31  *** States Code.  All rights reserved.                             ***
  32  **********************************************************************
  33  **********************************************************************
  34  **********************************************************************/
  35 
  36 package java.awt.image.renderable;
  37 import java.util.Vector;
  38 import java.awt.RenderingHints;
  39 import java.awt.image.*;
  40 
  41 /**
  42  * A RenderableImage is a common interface for rendering-independent
  43  * images (a notion which subsumes resolution independence).  That is,
  44  * images which are described and have operations applied to them
  45  * independent of any specific rendering of the image.  For example, a
  46  * RenderableImage can be rotated and cropped in
  47  * resolution-independent terms.  Then, it can be rendered for various
  48  * specific contexts, such as a draft preview, a high-quality screen
  49  * display, or a printer, each in an optimal fashion.
  50  *
  51  * <p> A RenderedImage is returned from a RenderableImage via the
  52  * createRendering() method, which takes a RenderContext.  The
  53  * RenderContext specifies how the RenderedImage should be
  54  * constructed.  Note that it is not possible to extract pixels
  55  * directly from a RenderableImage.
  56  *
  57  * <p> The createDefaultRendering() and createScaledRendering() methods are
  58  * convenience methods that construct an appropriate RenderContext
  59  * internally.  All of the rendering methods may return a reference to a
  60  * previously produced rendering.
  61  */
  62 public interface RenderableImage {
  63 
  64     /**
  65      * String constant that can be used to identify a property on
  66      * a RenderedImage obtained via the createRendering or
  67      * createScaledRendering methods.  If such a property exists,
  68      * the value of the property will be a RenderingHints object
  69      * specifying which hints were observed in creating the rendering.
  70      */
  71      static final String HINTS_OBSERVED = "HINTS_OBSERVED";
  72 
  73     /**
  74      * Returns a vector of RenderableImages that are the sources of
  75      * image data for this RenderableImage. Note that this method may
  76      * return an empty vector, to indicate that the image has no sources,
  77      * or null, to indicate that no information is available.
  78      *
  79      * @return a (possibly empty) Vector of RenderableImages, or null.
  80      */
  81     Vector<RenderableImage> getSources();
  82 
  83     /**
  84      * Gets a property from the property set of this image.
  85      * If the property name is not recognized, java.awt.Image.UndefinedProperty
  86      * will be returned.
  87      *
  88      * @param name the name of the property to get, as a String.
  89      * @return a reference to the property Object, or the value
  90      *         java.awt.Image.UndefinedProperty.
  91      */
  92     Object getProperty(String name);
  93 
  94     /**
  95      * Returns a list of names recognized by getProperty.
  96      * @return a list of property names.
  97      */
  98     String[] getPropertyNames();
  99 
 100     /**
 101      * Returns true if successive renderings (that is, calls to
 102      * createRendering() or createScaledRendering()) with the same arguments
 103      * may produce different results.  This method may be used to
 104      * determine whether an existing rendering may be cached and
 105      * reused.  It is always safe to return true.
 106      * @return <code>true</code> if successive renderings with the
 107      *         same arguments might produce different results;
 108      *         <code>false</code> otherwise.
 109      */
 110     boolean isDynamic();
 111 
 112     /**
 113      * Gets the width in user coordinate space.  By convention, the
 114      * usual width of a RenderableImage is equal to the image's aspect
 115      * ratio (width divided by height).
 116      *
 117      * @return the width of the image in user coordinates.
 118      */
 119     float getWidth();
 120 
 121     /**
 122      * Gets the height in user coordinate space.  By convention, the
 123      * usual height of a RenderedImage is equal to 1.0F.
 124      *
 125      * @return the height of the image in user coordinates.
 126      */
 127     float getHeight();
 128 
 129     /**
 130      * Gets the minimum X coordinate of the rendering-independent image data.
 131      * @return the minimum X coordinate of the rendering-independent image
 132      * data.
 133      */
 134     float getMinX();
 135 
 136     /**
 137      * Gets the minimum Y coordinate of the rendering-independent image data.
 138      * @return the minimum Y coordinate of the rendering-independent image
 139      * data.
 140      */
 141     float getMinY();
 142 
 143     /**
 144      * Creates a RenderedImage instance of this image with width w, and
 145      * height h in pixels.  The RenderContext is built automatically
 146      * with an appropriate usr2dev transform and an area of interest
 147      * of the full image.  All the rendering hints come from hints
 148      * passed in.
 149      *
 150      * <p> If w == 0, it will be taken to equal
 151      * Math.round(h*(getWidth()/getHeight())).
 152      * Similarly, if h == 0, it will be taken to equal
 153      * Math.round(w*(getHeight()/getWidth())).  One of
 154      * w or h must be non-zero or else an IllegalArgumentException
 155      * will be thrown.
 156      *
 157      * <p> The created RenderedImage may have a property identified
 158      * by the String HINTS_OBSERVED to indicate which RenderingHints
 159      * were used to create the image.  In addition any RenderedImages
 160      * that are obtained via the getSources() method on the created
 161      * RenderedImage may have such a property.
 162      *
 163      * @param w the width of rendered image in pixels, or 0.
 164      * @param h the height of rendered image in pixels, or 0.
 165      * @param hints a RenderingHints object containing hints.
 166      * @return a RenderedImage containing the rendered data.
 167      */
 168     RenderedImage createScaledRendering(int w, int h, RenderingHints hints);
 169 
 170     /**
 171      * Returnd a RenderedImage instance of this image with a default
 172      * width and height in pixels.  The RenderContext is built
 173      * automatically with an appropriate usr2dev transform and an area
 174      * of interest of the full image.  The rendering hints are
 175      * empty.  createDefaultRendering may make use of a stored
 176      * rendering for speed.
 177      *
 178      * @return a RenderedImage containing the rendered data.
 179      */
 180     RenderedImage createDefaultRendering();
 181 
 182     /**
 183      * Creates a RenderedImage that represented a rendering of this image
 184      * using a given RenderContext.  This is the most general way to obtain a
 185      * rendering of a RenderableImage.
 186      *
 187      * <p> The created RenderedImage may have a property identified
 188      * by the String HINTS_OBSERVED to indicate which RenderingHints
 189      * (from the RenderContext) were used to create the image.
 190      * In addition any RenderedImages
 191      * that are obtained via the getSources() method on the created
 192      * RenderedImage may have such a property.
 193      *
 194      * @param renderContext the RenderContext to use to produce the rendering.
 195      * @return a RenderedImage containing the rendered data.
 196      */
 197     RenderedImage createRendering(RenderContext renderContext);
 198 }