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
36package java.awt.image.renderable;
37import java.util.*;
38import java.awt.geom.*;
39import java.awt.*;
40import java.awt.image.*;
41
42/**
43 * A RenderContext encapsulates the information needed to produce a
44 * specific rendering from a RenderableImage.  It contains the area to
45 * be rendered specified in rendering-independent terms, the
46 * resolution at which the rendering is to be performed, and hints
47 * used to control the rendering process.
48 *
49 * <p> Users create RenderContexts and pass them to the
50 * RenderableImage via the createRendering method.  Most of the methods of
51 * RenderContexts are not meant to be used directly by applications,
52 * but by the RenderableImage and operator classes to which it is
53 * passed.
54 *
55 * <p> The AffineTransform parameter passed into and out of this class
56 * are cloned.  The RenderingHints and Shape parameters are not
57 * necessarily cloneable and are therefore only reference copied.
58 * Altering RenderingHints or Shape instances that are in use by
59 * instances of RenderContext may have undesired side effects.
60 */
61public class RenderContext implements Cloneable {
62
63    /** Table of hints. May be null. */
64    RenderingHints hints;
65
66    /** Transform to convert user coordinates to device coordinates.  */
67    AffineTransform usr2dev;
68
69    /** The area of interest.  May be null. */
70    Shape aoi;
71
72    // Various constructors that allow different levels of
73    // specificity. If the Shape is missing the whole renderable area
74    // is assumed. If hints is missing no hints are assumed.
75
76    /**
77     * Constructs a RenderContext with a given transform.
78     * The area of interest is supplied as a Shape,
79     * and the rendering hints are supplied as a RenderingHints object.
80     *
81     * @param usr2dev an AffineTransform.
82     * @param aoi a Shape representing the area of interest.
83     * @param hints a RenderingHints object containing rendering hints.
84     */
85    public RenderContext(AffineTransform usr2dev,
86                         Shape aoi,
87                         RenderingHints hints) {
88        this.hints = hints;
89        this.aoi = aoi;
90        this.usr2dev = (AffineTransform)usr2dev.clone();
91    }
92
93    /**
94     * Constructs a RenderContext with a given transform.
95     * The area of interest is taken to be the entire renderable area.
96     * No rendering hints are used.
97     *
98     * @param usr2dev an AffineTransform.
99     */
100    public RenderContext(AffineTransform usr2dev) {
101        this(usr2dev, null, null);
102    }
103
104    /**
105     * Constructs a RenderContext with a given transform and rendering hints.
106     * The area of interest is taken to be the entire renderable area.
107     *
108     * @param usr2dev an AffineTransform.
109     * @param hints a RenderingHints object containing rendering hints.
110     */
111    public RenderContext(AffineTransform usr2dev, RenderingHints hints) {
112        this(usr2dev, null, hints);
113    }
114
115    /**
116     * Constructs a RenderContext with a given transform and area of interest.
117     * The area of interest is supplied as a Shape.
118     * No rendering hints are used.
119     *
120     * @param usr2dev an AffineTransform.
121     * @param aoi a Shape representing the area of interest.
122     */
123    public RenderContext(AffineTransform usr2dev, Shape aoi) {
124        this(usr2dev, aoi, null);
125    }
126
127    /**
128     * Gets the rendering hints of this {@code RenderContext}.
129     * @return a {@code RenderingHints} object that represents
130     * the rendering hints of this {@code RenderContext}.
131     * @see #setRenderingHints(RenderingHints)
132     */
133    public RenderingHints getRenderingHints() {
134        return hints;
135    }
136
137    /**
138     * Sets the rendering hints of this {@code RenderContext}.
139     * @param hints a {@code RenderingHints} object that represents
140     * the rendering hints to assign to this {@code RenderContext}.
141     * @see #getRenderingHints
142     */
143    public void setRenderingHints(RenderingHints hints) {
144        this.hints = hints;
145    }
146
147    /**
148     * Sets the current user-to-device AffineTransform contained
149     * in the RenderContext to a given transform.
150     *
151     * @param newTransform the new AffineTransform.
152     * @see #getTransform
153     */
154    public void setTransform(AffineTransform newTransform) {
155        usr2dev = (AffineTransform)newTransform.clone();
156    }
157
158    /**
159     * Modifies the current user-to-device transform by prepending another
160     * transform.  In matrix notation the operation is:
161     * <pre>
162     * [this] = [modTransform] x [this]
163     * </pre>
164     *
165     * @param modTransform the AffineTransform to prepend to the
166     *        current usr2dev transform.
167     * @since 1.3
168     */
169    public void preConcatenateTransform(AffineTransform modTransform) {
170        this.preConcetenateTransform(modTransform);
171    }
172
173    /**
174     * Modifies the current user-to-device transform by prepending another
175     * transform.  In matrix notation the operation is:
176     * <pre>
177     * [this] = [modTransform] x [this]
178     * </pre>
179     * This method does the same thing as the preConcatenateTransform
180     * method.  It is here for backward compatibility with previous releases
181     * which misspelled the method name.
182     *
183     * @param modTransform the AffineTransform to prepend to the
184     *        current usr2dev transform.
185     * @deprecated     replaced by
186     *                 {@code preConcatenateTransform(AffineTransform)}.
187     */
188    @Deprecated
189    public void preConcetenateTransform(AffineTransform modTransform) {
190        usr2dev.preConcatenate(modTransform);
191    }
192
193    /**
194     * Modifies the current user-to-device transform by appending another
195     * transform.  In matrix notation the operation is:
196     * <pre>
197     * [this] = [this] x [modTransform]
198     * </pre>
199     *
200     * @param modTransform the AffineTransform to append to the
201     *        current usr2dev transform.
202     * @since 1.3
203     */
204    public void concatenateTransform(AffineTransform modTransform) {
205        this.concetenateTransform(modTransform);
206    }
207
208    /**
209     * Modifies the current user-to-device transform by appending another
210     * transform.  In matrix notation the operation is:
211     * <pre>
212     * [this] = [this] x [modTransform]
213     * </pre>
214     * This method does the same thing as the concatenateTransform
215     * method.  It is here for backward compatibility with previous releases
216     * which misspelled the method name.
217     *
218     * @param modTransform the AffineTransform to append to the
219     *        current usr2dev transform.
220     * @deprecated     replaced by
221     *                 {@code concatenateTransform(AffineTransform)}.
222     */
223    @Deprecated
224    public void concetenateTransform(AffineTransform modTransform) {
225        usr2dev.concatenate(modTransform);
226    }
227
228    /**
229     * Gets the current user-to-device AffineTransform.
230     *
231     * @return a reference to the current AffineTransform.
232     * @see #setTransform(AffineTransform)
233     */
234    public AffineTransform getTransform() {
235        return (AffineTransform)usr2dev.clone();
236    }
237
238    /**
239     * Sets the current area of interest.  The old area is discarded.
240     *
241     * @param newAoi The new area of interest.
242     * @see #getAreaOfInterest
243     */
244    public void setAreaOfInterest(Shape newAoi) {
245        aoi = newAoi;
246    }
247
248    /**
249     * Gets the ares of interest currently contained in the
250     * RenderContext.
251     *
252     * @return a reference to the area of interest of the RenderContext,
253     *         or null if none is specified.
254     * @see #setAreaOfInterest(Shape)
255     */
256    public Shape getAreaOfInterest() {
257        return aoi;
258    }
259
260    /**
261     * Makes a copy of a RenderContext. The area of interest is copied
262     * by reference.  The usr2dev AffineTransform and hints are cloned,
263     * while the area of interest is copied by reference.
264     *
265     * @return the new cloned RenderContext.
266     */
267    public Object clone() {
268        RenderContext newRenderContext = new RenderContext(usr2dev,
269                                                           aoi, hints);
270        return newRenderContext;
271    }
272}
273