jdk/src/share/classes/java/awt/image/renderable/ContextualRenderedImageFactory.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/awt/image/renderable/ContextualRenderedImageFactory.java Thu Apr 10 16:28:45 2008 -0700
@@ -0,0 +1,143 @@
+/*
+ * Portions Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+/* ********************************************************************
+ **********************************************************************
+ **********************************************************************
+ *** COPYRIGHT (c) Eastman Kodak Company, 1997 ***
+ *** As an unpublished work pursuant to Title 17 of the United ***
+ *** States Code. All rights reserved. ***
+ **********************************************************************
+ **********************************************************************
+ **********************************************************************/
+
+package java.awt.image.renderable;
+import java.awt.geom.Rectangle2D;
+import java.awt.image.RenderedImage;
+
+/**
+ * ContextualRenderedImageFactory provides an interface for the
+ * functionality that may differ between instances of
+ * RenderableImageOp. Thus different operations on RenderableImages
+ * may be performed by a single class such as RenderedImageOp through
+ * the use of multiple instances of ContextualRenderedImageFactory.
+ * The name ContextualRenderedImageFactory is commonly shortened to
+ * "CRIF."
+ *
+ * <p> All operations that are to be used in a rendering-independent
+ * chain must implement ContextualRenderedImageFactory.
+ *
+ * <p> Classes that implement this interface must provide a
+ * constructor with no arguments.
+ */
+public interface ContextualRenderedImageFactory extends RenderedImageFactory {
+
+ /**
+ * Maps the operation's output RenderContext into a RenderContext
+ * for each of the operation's sources. This is useful for
+ * operations that can be expressed in whole or in part simply as
+ * alterations in the RenderContext, such as an affine mapping, or
+ * operations that wish to obtain lower quality renderings of
+ * their sources in order to save processing effort or
+ * transmission bandwith. Some operations, such as blur, can also
+ * use this mechanism to avoid obtaining sources of higher quality
+ * than necessary.
+ *
+ * @param i the index of the source image.
+ * @param renderContext the RenderContext being applied to the operation.
+ * @param paramBlock a ParameterBlock containing the operation's
+ * sources and parameters.
+ * @param image the RenderableImage being rendered.
+ * @return a <code>RenderContext</code> for
+ * the source at the specified index of the parameters
+ * Vector contained in the specified ParameterBlock.
+ */
+ RenderContext mapRenderContext(int i,
+ RenderContext renderContext,
+ ParameterBlock paramBlock,
+ RenderableImage image);
+
+ /**
+ * Creates a rendering, given a RenderContext and a ParameterBlock
+ * containing the operation's sources and parameters. The output
+ * is a RenderedImage that takes the RenderContext into account to
+ * determine its dimensions and placement on the image plane.
+ * This method houses the "intelligence" that allows a
+ * rendering-independent operation to adapt to a specific
+ * RenderContext.
+ *
+ * @param renderContext The RenderContext specifying the rendering
+ * @param paramBlock a ParameterBlock containing the operation's
+ * sources and parameters
+ * @return a <code>RenderedImage</code> from the sources and parameters
+ * in the specified ParameterBlock and according to the
+ * rendering instructions in the specified RenderContext.
+ */
+ RenderedImage create(RenderContext renderContext,
+ ParameterBlock paramBlock);
+
+ /**
+ * Returns the bounding box for the output of the operation,
+ * performed on a given set of sources, in rendering-independent
+ * space. The bounds are returned as a Rectangle2D, that is, an
+ * axis-aligned rectangle with floating-point corner coordinates.
+ *
+ * @param paramBlock a ParameterBlock containing the operation's
+ * sources and parameters.
+ * @return a Rectangle2D specifying the rendering-independent
+ * bounding box of the output.
+ */
+ Rectangle2D getBounds2D(ParameterBlock paramBlock);
+
+ /**
+ * Gets the appropriate instance of the property specified by the name
+ * parameter. This method must determine which instance of a property to
+ * return when there are multiple sources that each specify the property.
+ *
+ * @param paramBlock a ParameterBlock containing the operation's
+ * sources and parameters.
+ * @param name a String naming the desired property.
+ * @return an object reference to the value of the property requested.
+ */
+ Object getProperty(ParameterBlock paramBlock, String name);
+
+ /**
+ * Returns a list of names recognized by getProperty.
+ * @return the list of property names.
+ */
+ String[] getPropertyNames();
+
+ /**
+ * Returns true if successive renderings (that is, calls to
+ * create(RenderContext, ParameterBlock)) with the same arguments
+ * may produce different results. This method may be used to
+ * determine whether an existing rendering may be cached and
+ * reused. It is always safe to return true.
+ * @return <code>true</code> if successive renderings with the
+ * same arguments might produce different results;
+ * <code>false</code> otherwise.
+ */
+ boolean isDynamic();
+}