View Javadoc
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.util.*;
38  import java.awt.geom.*;
39  import java.awt.*;
40  import 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   */
61  public 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</code>.
129      * @return a <code>RenderingHints</code> object that represents
130      * the rendering hints of this <code>RenderContext</code>.
131      * @see #setRenderingHints(RenderingHints)
132      */
133     public RenderingHints getRenderingHints() {
134         return hints;
135     }
136 
137     /**
138      * Sets the rendering hints of this <code>RenderContext</code>.
139      * @param hints a <code>RenderingHints</code> object that represents
140      * the rendering hints to assign to this <code>RenderContext</code>.
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)</code>.
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)</code>.
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 }