Paint.java revision 2362
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * This code is free software; you can redistribute it and/or modify it
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * under the terms of the GNU General Public License version 2 only, as
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * published by the Free Software Foundation. Oracle designates this
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * particular file as subject to the "Classpath" exception as provided
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * by Oracle in the LICENSE file that accompanied this code.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * This code is distributed in the hope that it will be useful, but WITHOUT
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * version 2 for more details (a copy is included in the LICENSE file that
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * accompanied this code).
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * You should have received a copy of the GNU General Public License version
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * 2 along with this work; if not, write to the Free Software Foundation,
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
40764c95159232b912f6f16cb1fb1a41897fb0a7Victor Li * or visit www.oracle.com if you need additional information or have any
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * questions.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * This <code>Paint</code> interface defines how color patterns
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * can be generated for {@link Graphics2D} operations. A class
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * implementing the <code>Paint</code> interface is added to the
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * <code>Graphics2D</code> context in order to define the color
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * pattern used by the <code>draw</code> and <code>fill</code> methods.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Instances of classes implementing <code>Paint</code> must be
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * read-only because the <code>Graphics2D</code> does not clone
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * these objects when they are set as an attribute with the
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * <code>setPaint</code> method or when the <code>Graphics2D</code>
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * object is itself cloned.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see PaintContext
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see Color
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see GradientPaint
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see TexturePaint
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see Graphics2D#setPaint
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @version 1.36, 06/05/07
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Creates and returns a {@link PaintContext} used to
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * generate the color pattern.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * The arguments to this method convey additional information
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * about the rendering operation that may be
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * used or ignored on various implementations of the {@code Paint} interface.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * A caller must pass non-{@code null} values for all of the arguments
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * except for the {@code ColorModel} argument which may be {@code null} to
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * indicate that no specific {@code ColorModel} type is preferred.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations of the {@code Paint} interface are allowed to use or ignore
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * any of the arguments as makes sense for their function, and are
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * not constrained to use the specified {@code ColorModel} for the returned
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * {@code PaintContext}, even if it is not {@code null}.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations are allowed to throw {@code NullPointerException} for
7bc7346c0c75ced7da727f63c2772fd53809244dcm * any {@code null} argument other than the {@code ColorModel} argument,
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * but are not required to do so.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @param cm the preferred {@link ColorModel} which represents the most convenient
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * format for the caller to receive the pixel data, or {@code null}
193974072f41a843678abf5f61979c748687e66bSherry Moore * if there is no preference.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @param deviceBounds the device space bounding box
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * of the graphics primitive being rendered.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations of the {@code Paint} interface
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * are allowed to throw {@code NullPointerException}
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * for a {@code null} {@code deviceBounds}.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @param userBounds the user space bounding box
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * of the graphics primitive being rendered.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations of the {@code Paint} interface
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * are allowed to throw {@code NullPointerException}
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * for a {@code null} {@code userBounds}.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @param xform the {@link AffineTransform} from user
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * space into device space.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations of the {@code Paint} interface
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * are allowed to throw {@code NullPointerException}
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * for a {@code null} {@code xform}.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @param hints the set of hints that the context object can use to
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * choose between rendering alternatives.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * Implementations of the {@code Paint} interface
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * are allowed to throw {@code NullPointerException}
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * for a {@code null} {@code hints}.
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @return the {@code PaintContext} for
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * generating color patterns.
53a7b6b6763f5865522a76e5e887390a8f4777d7Chris Horne * @see PaintContext
53a7b6b6763f5865522a76e5e887390a8f4777d7Chris Horne * @see ColorModel
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see Rectangle
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see Rectangle2D
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see AffineTransform
1e1ddd6cc98ab5af8293f7ebd132be62900730fdcth * @see RenderingHints