1 /*
2 * Copyright (c) 1998, 2008, 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.awt.geom.Rectangle2D;
38 import java.awt.image.RenderedImage;
39
40 /**
41 * ContextualRenderedImageFactory provides an interface for the
42 * functionality that may differ between instances of
43 * RenderableImageOp. Thus different operations on RenderableImages
44 * may be performed by a single class such as RenderedImageOp through
45 * the use of multiple instances of ContextualRenderedImageFactory.
46 * The name ContextualRenderedImageFactory is commonly shortened to
47 * "CRIF."
48 *
49 * <p> All operations that are to be used in a rendering-independent
50 * chain must implement ContextualRenderedImageFactory.
51 *
52 * <p> Classes that implement this interface must provide a
53 * constructor with no arguments.
54 */
55 public interface ContextualRenderedImageFactory extends RenderedImageFactory {
56
57 /**
58 * Maps the operation's output RenderContext into a RenderContext
59 * for each of the operation's sources. This is useful for
60 * operations that can be expressed in whole or in part simply as
61 * alterations in the RenderContext, such as an affine mapping, or
62 * operations that wish to obtain lower quality renderings of
63 * their sources in order to save processing effort or
64 * transmission bandwith. Some operations, such as blur, can also
65 * use this mechanism to avoid obtaining sources of higher quality
66 * than necessary.
67 *
68 * @param i the index of the source image.
69 * @param renderContext the RenderContext being applied to the operation.
70 * @param paramBlock a ParameterBlock containing the operation's
71 * sources and parameters.
72 * @param image the RenderableImage being rendered.
73 * @return a <code>RenderContext</code> for
74 * the source at the specified index of the parameters
75 * Vector contained in the specified ParameterBlock.
76 */
77 RenderContext mapRenderContext(int i,
78 RenderContext renderContext,
79 ParameterBlock paramBlock,
80 RenderableImage image);
81
82 /**
83 * Creates a rendering, given a RenderContext and a ParameterBlock
84 * containing the operation's sources and parameters. The output
85 * is a RenderedImage that takes the RenderContext into account to
86 * determine its dimensions and placement on the image plane.
87 * This method houses the "intelligence" that allows a
88 * rendering-independent operation to adapt to a specific
89 * RenderContext.
90 *
91 * @param renderContext The RenderContext specifying the rendering
92 * @param paramBlock a ParameterBlock containing the operation's
93 * sources and parameters
94 * @return a <code>RenderedImage</code> from the sources and parameters
95 * in the specified ParameterBlock and according to the
96 * rendering instructions in the specified RenderContext.
97 */
98 RenderedImage create(RenderContext renderContext,
99 ParameterBlock paramBlock);
100
101 /**
102 * Returns the bounding box for the output of the operation,
103 * performed on a given set of sources, in rendering-independent
104 * space. The bounds are returned as a Rectangle2D, that is, an
105 * axis-aligned rectangle with floating-point corner coordinates.
106 *
107 * @param paramBlock a ParameterBlock containing the operation's
108 * sources and parameters.
109 * @return a Rectangle2D specifying the rendering-independent
110 * bounding box of the output.
111 */
112 Rectangle2D getBounds2D(ParameterBlock paramBlock);
113
114 /**
115 * Gets the appropriate instance of the property specified by the name
116 * parameter. This method must determine which instance of a property to
117 * return when there are multiple sources that each specify the property.
118 *
119 * @param paramBlock a ParameterBlock containing the operation's
120 * sources and parameters.
121 * @param name a String naming the desired property.
122 * @return an object reference to the value of the property requested.
123 */
124 Object getProperty(ParameterBlock paramBlock, String name);
125
126 /**
127 * Returns a list of names recognized by getProperty.
128 * @return the list of property names.
129 */
130 String[] getPropertyNames();
131
132 /**
133 * Returns true if successive renderings (that is, calls to
134 * create(RenderContext, ParameterBlock)) with the same arguments
135 * may produce different results. This method may be used to
136 * determine whether an existing rendering may be cached and
137 * reused. It is always safe to return true.
138 * @return <code>true</code> if successive renderings with the
139 * same arguments might produce different results;
140 * <code>false</code> otherwise.
141 */
142 boolean isDynamic();
143 }