1 /*

     2  * Portions Copyright 1998-2000 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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 }