1 /*
   2  * Copyright (c) 1997, 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 package java.awt;
  27 
  28 import java.awt.image.ColorModel;
  29 import java.awt.geom.AffineTransform;
  30 import java.awt.geom.Rectangle2D;
  31 
  32 /**
  33  * This {@code Paint} interface defines how color patterns
  34  * can be generated for {@link Graphics2D} operations.  A class
  35  * implementing the {@code Paint} interface is added to the
  36  * {@code Graphics2D} context in order to define the color
  37  * pattern used by the {@code draw} and {@code fill} methods.
  38  * <p>
  39  * Instances of classes implementing {@code Paint} must be
  40  * read-only because the {@code Graphics2D} does not clone
  41  * these objects when they are set as an attribute with the
  42  * {@code setPaint} method or when the {@code Graphics2D}
  43  * object is itself cloned.
  44  * @see PaintContext
  45  * @see Color
  46  * @see GradientPaint
  47  * @see TexturePaint
  48  * @see Graphics2D#setPaint
  49  * @version 1.36, 06/05/07
  50  */
  51 
  52 public interface Paint extends Transparency {
  53     /**
  54      * Creates and returns a {@link PaintContext} used to
  55      * generate the color pattern.
  56      * The arguments to this method convey additional information
  57      * about the rendering operation that may be
  58      * used or ignored on various implementations of the {@code Paint} interface.
  59      * A caller must pass non-{@code null} values for all of the arguments
  60      * except for the {@code ColorModel} argument which may be {@code null} to
  61      * indicate that no specific {@code ColorModel} type is preferred.
  62      * Implementations of the {@code Paint} interface are allowed to use or ignore
  63      * any of the arguments as makes sense for their function, and are
  64      * not constrained to use the specified {@code ColorModel} for the returned
  65      * {@code PaintContext}, even if it is not {@code null}.
  66      * Implementations are allowed to throw {@code NullPointerException} for
  67      * any {@code null} argument other than the {@code ColorModel} argument,
  68      * but are not required to do so.
  69      *
  70      * @param cm the preferred {@link ColorModel} which represents the most convenient
  71      *           format for the caller to receive the pixel data, or {@code null}
  72      *           if there is no preference.
  73      * @param deviceBounds the device space bounding box
  74      *                     of the graphics primitive being rendered.
  75      *                     Implementations of the {@code Paint} interface
  76      *                     are allowed to throw {@code NullPointerException}
  77      *                     for a {@code null deviceBounds}.
  78      * @param userBounds the user space bounding box
  79      *                   of the graphics primitive being rendered.
  80      *                     Implementations of the {@code Paint} interface
  81      *                     are allowed to throw {@code NullPointerException}
  82      *                     for a {@code null userBounds}.
  83      * @param xform the {@link AffineTransform} from user
  84      *              space into device space.
  85      *                     Implementations of the {@code Paint} interface
  86      *                     are allowed to throw {@code NullPointerException}
  87      *                     for a {@code null xform}.
  88      * @param hints the set of hints that the context object can use to
  89      *              choose between rendering alternatives.
  90      *                     Implementations of the {@code Paint} interface
  91      *                     are allowed to throw {@code NullPointerException}
  92      *                     for a {@code null hints}.
  93      * @return the {@code PaintContext} for
  94      *         generating color patterns.
  95      * @see PaintContext
  96      * @see ColorModel
  97      * @see Rectangle
  98      * @see Rectangle2D
  99      * @see AffineTransform
 100      * @see RenderingHints
 101      */
 102     public PaintContext createContext(ColorModel cm,
 103                                       Rectangle deviceBounds,
 104                                       Rectangle2D userBounds,
 105                                       AffineTransform xform,
 106                                       RenderingHints hints);
 107 
 108 }