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
26package java.awt;
27
28import java.awt.image.ColorModel;
29import java.awt.geom.AffineTransform;
30import 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
52public 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}
109