/*

 * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

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

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt;

import java.awt.geom.AffineTransform;

import java.awt.geom.Point2D;

import java.awt.geom.Rectangle2D;

import java.awt.image.ColorModel;

import java.beans.ConstructorProperties;

/**

 * The {@code LinearGradientPaint} class provides a way to fill

 * a {@link java.awt.Shape} with a linear color gradient pattern.  The user

 * may specify two or more gradient colors, and this paint will provide an

 * interpolation between each color.  The user also specifies start and end

 * points which define where in user space the color gradient should begin

 * and end.

 * <p>

 * The user must provide an array of floats specifying how to distribute the

 * colors along the gradient.  These values should range from 0.0 to 1.0 and

 * act like keyframes along the gradient (they mark where the gradient should

 * be exactly a particular color).

 * <p>

 * In the event that the user does not set the first keyframe value equal

 * to 0 and/or the last keyframe value equal to 1, keyframes will be created

 * at these positions and the first and last colors will be replicated there.

 * So, if a user specifies the following arrays to construct a gradient:<br>

 * <pre>

 *     {Color.BLUE, Color.RED}, {.3f, .7f}

 * </pre>

 * this will be converted to a gradient with the following keyframes:<br>

 * <pre>

 *     {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f}

 * </pre>

 *

 * <p>

 * The user may also select what action the {@code LinearGradientPaint} object

 * takes when it is filling the space outside the start and end points by

 * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}.

 * The distances between any two colors in any of the reflected or repeated

 * copies of the gradient are the same as the distance between those same two

 * colors between the start and end points.

 * Note that some minor variations in distances may occur due to sampling at

 * the granularity of a pixel.

 * If no cycle method is specified, {@code NO_CYCLE} will be chosen by

 * default, which means the endpoint colors will be used to fill the

 * remaining area.

 * <p>

 * The colorSpace parameter allows the user to specify in which colorspace

 * the interpolation should be performed, default sRGB or linearized RGB.

 *

 * <p>

 * The following code demonstrates typical usage of

 * {@code LinearGradientPaint}:

 * <pre>

 *     Point2D start = new Point2D.Float(0, 0);

 *     Point2D end = new Point2D.Float(50, 50);

 *     float[] dist = {0.0f, 0.2f, 1.0f};

 *     Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};

 *     LinearGradientPaint p =

 *         new LinearGradientPaint(start, end, dist, colors);

 * </pre>

 * <p>

 * This code will create a {@code LinearGradientPaint} which interpolates

 * between red and white for the first 20% of the gradient and between white

 * and blue for the remaining 80%.

 *

 * <p>

 * This image demonstrates the example code above for each

 * of the three cycle methods:

 * <center>

 * <img src = "doc-files/LinearGradientPaint.png"

 * alt="image showing the output of the example code">

 * </center>

 *

 * @see java.awt.Paint

 * @see java.awt.Graphics2D#setPaint

 * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans

 * @since 1.6

 */

public final class LinearGradientPaint extends MultipleGradientPaint {

    /** Gradient start and end points. */

    private final Point2D start, end;

    /**

     * Constructs a {@code LinearGradientPaint} with a default

     * {@code NO_CYCLE} repeating method and {@code SRGB} color space.

     *

     * @param startX the X coordinate of the gradient axis start point

     *               in user space

     * @param startY the Y coordinate of the gradient axis start point

     *               in user space

     * @param endX   the X coordinate of the gradient axis end point

     *               in user space

     * @param endY   the Y coordinate of the gradient axis end point

     *               in user space

     * @param fractions numbers ranging from 0.0 to 1.0 specifying the

     *                  distribution of colors along the gradient

     * @param colors array of colors corresponding to each fractional value

     *

     * @throws NullPointerException

     * if {@code fractions} array is null,

     * or {@code colors} array is null,

     * @throws IllegalArgumentException

     * if start and end points are the same points,

     * or {@code fractions.length != colors.length},

     * or {@code colors} is less than 2 in size,

     * or a {@code fractions} value is less than 0.0 or greater than 1.0,

     * or the {@code fractions} are not provided in strictly increasing order

     */

    public LinearGradientPaint(float startX, float startY,

                               float endX, float endY,

                               float[] fractions, Color[] colors)

    {

        this(new Point2D.Float(startX, startY),

             new Point2D.Float(endX, endY),

             fractions,

             colors,

             CycleMethod.NO_CYCLE);

    }

    /**

     * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}

     * color space.

     *

     * @param startX the X coordinate of the gradient axis start point

     *               in user space

     * @param startY the Y coordinate of the gradient axis start point

     *               in user space

     * @param endX   the X coordinate of the gradient axis end point

     *               in user space

     * @param endY   the Y coordinate of the gradient axis end point

     *               in user space

     * @param fractions numbers ranging from 0.0 to 1.0 specifying the

     *                  distribution of colors along the gradient

     * @param colors array of colors corresponding to each fractional value

     * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},

     *                    or {@code REPEAT}

     *

     * @throws NullPointerException

     * if {@code fractions} array is null,

     * or {@code colors} array is null,

     * or {@code cycleMethod} is null

     * @throws IllegalArgumentException

     * if start and end points are the same points,

     * or {@code fractions.length != colors.length},

     * or {@code colors} is less than 2 in size,

     * or a {@code fractions} value is less than 0.0 or greater than 1.0,

     * or the {@code fractions} are not provided in strictly increasing order

     */

    public LinearGradientPaint(float startX, float startY,

                               float endX, float endY,

                               float[] fractions, Color[] colors,

                               CycleMethod cycleMethod)

    {

        this(new Point2D.Float(startX, startY),

             new Point2D.Float(endX, endY),

             fractions,

             colors,

             cycleMethod);

    }

    /**

     * Constructs a {@code LinearGradientPaint} with a default

     * {@code NO_CYCLE} repeating method and {@code SRGB} color space.

     *

     * @param start the gradient axis start {@code Point2D} in user space

     * @param end the gradient axis end {@code Point2D} in user space

     * @param fractions numbers ranging from 0.0 to 1.0 specifying the

     *                  distribution of colors along the gradient

     * @param colors array of colors corresponding to each fractional value

     *

     * @throws NullPointerException

     * if one of the points is null,

     * or {@code fractions} array is null,

     * or {@code colors} array is null

     * @throws IllegalArgumentException

     * if start and end points are the same points,

     * or {@code fractions.length != colors.length},

     * or {@code colors} is less than 2 in size,

     * or a {@code fractions} value is less than 0.0 or greater than 1.0,

     * or the {@code fractions} are not provided in strictly increasing order

     */

    public LinearGradientPaint(Point2D start, Point2D end,

                               float[] fractions, Color[] colors)

    {

        this(start, end,

             fractions, colors,

             CycleMethod.NO_CYCLE);

    }

    /**

     * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}

     * color space.

     *

     * @param start the gradient axis start {@code Point2D} in user space

     * @param end the gradient axis end {@code Point2D} in user space

     * @param fractions numbers ranging from 0.0 to 1.0 specifying the

     *                  distribution of colors along the gradient

     * @param colors array of colors corresponding to each fractional value

     * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},

     *                    or {@code REPEAT}

     *

     * @throws NullPointerException

     * if one of the points is null,

     * or {@code fractions} array is null,

     * or {@code colors} array is null,

     * or {@code cycleMethod} is null

     * @throws IllegalArgumentException

     * if start and end points are the same points,

     * or {@code fractions.length != colors.length},

     * or {@code colors} is less than 2 in size,

     * or a {@code fractions} value is less than 0.0 or greater than 1.0,

     * or the {@code fractions} are not provided in strictly increasing order

     */

    public LinearGradientPaint(Point2D start, Point2D end,

                               float[] fractions, Color[] colors,

                               CycleMethod cycleMethod)

    {

        this(start, end,

             fractions, colors,

             cycleMethod,

             ColorSpaceType.SRGB,

             new AffineTransform());

    }

    /**

     * Constructs a {@code LinearGradientPaint}.

     *

     * @param start the gradient axis start {@code Point2D} in user space

     * @param end the gradient axis end {@code Point2D} in user space

     * @param fractions numbers ranging from 0.0 to 1.0 specifying the

     *                  distribution of colors along the gradient

     * @param colors array of colors corresponding to each fractional value

     * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},

     *                    or {@code REPEAT}

     * @param colorSpace which color space to use for interpolation,

     *                   either {@code SRGB} or {@code LINEAR_RGB}

     * @param gradientTransform transform to apply to the gradient

     *

     * @throws NullPointerException

     * if one of the points is null,

     * or {@code fractions} array is null,

     * or {@code colors} array is null,

     * or {@code cycleMethod} is null,

     * or {@code colorSpace} is null,

     * or {@code gradientTransform} is null

     * @throws IllegalArgumentException

     * if start and end points are the same points,

     * or {@code fractions.length != colors.length},

     * or {@code colors} is less than 2 in size,

     * or a {@code fractions} value is less than 0.0 or greater than 1.0,

     * or the {@code fractions} are not provided in strictly increasing order

     */

    @ConstructorProperties({ "startPoint", "endPoint", "fractions", "colors", "cycleMethod", "colorSpace", "transform" })

    public LinearGradientPaint(Point2D start, Point2D end,

                               float[] fractions, Color[] colors,

                               CycleMethod cycleMethod,

                               ColorSpaceType colorSpace,

                               AffineTransform gradientTransform)

    {

        super(fractions, colors, cycleMethod, colorSpace, gradientTransform);

        // check input parameters

        if (start == null || end == null) {

            throw new NullPointerException("Start and end points must be" +

                                           "non-null");

        }

        if (start.equals(end)) {

            throw new IllegalArgumentException("Start point cannot equal" +

                                               "endpoint");

        }

        // copy the points...

        this.start = new Point2D.Double(start.getX(), start.getY());

        this.end = new Point2D.Double(end.getX(), end.getY());

    }

    /**

     * Creates and returns a {@link PaintContext} used to

     * generate a linear color gradient pattern.

     * See the {@link Paint#createContext specification} of the

     * method in the {@link Paint} interface for information

     * on null parameter handling.

     *

     * @param cm the preferred {@link ColorModel} which represents the most convenient

     *           format for the caller to receive the pixel data, or {@code null}

     *           if there is no preference.

     * @param deviceBounds the device space bounding box

     *                     of the graphics primitive being rendered.

     * @param userBounds the user space bounding box

     *                   of the graphics primitive being rendered.

     * @param transform the {@link AffineTransform} from user

     *              space into device space.

     * @param hints the set of hints that the context object can use to

     *              choose between rendering alternatives.

     * @return the {@code PaintContext} for

     *         generating color patterns.

     * @see Paint

     * @see PaintContext

     * @see ColorModel

     * @see Rectangle

     * @see Rectangle2D

     * @see AffineTransform

     * @see RenderingHints

     */

    public PaintContext createContext(ColorModel cm,

                                      Rectangle deviceBounds,

                                      Rectangle2D userBounds,

                                      AffineTransform transform,

                                      RenderingHints hints)

    {

        // avoid modifying the user's transform...

        transform = new AffineTransform(transform);

        // incorporate the gradient transform

        transform.concatenate(gradientTransform);

        if ((fractions.length == 2) &&

            (cycleMethod != CycleMethod.REPEAT) &&

            (colorSpace == ColorSpaceType.SRGB))

        {

            // faster to use the basic GradientPaintContext for this

            // common case

            boolean cyclic = (cycleMethod != CycleMethod.NO_CYCLE);

            return new GradientPaintContext(cm, start, end,

                                            transform,

                                            colors[0], colors[1],

                                            cyclic);

        } else {

            return new LinearGradientPaintContext(this, cm,

                                                  deviceBounds, userBounds,

                                                  transform, hints,

                                                  start, end,

                                                  fractions, colors,

                                                  cycleMethod, colorSpace);

        }

    }

    /**

     * Returns a copy of the start point of the gradient axis.

     *

     * @return a {@code Point2D} object that is a copy of the point

     * that anchors the first color of this {@code LinearGradientPaint}

     */

    public Point2D getStartPoint() {

        return new Point2D.Double(start.getX(), start.getY());

    }

    /**

     * Returns a copy of the end point of the gradient axis.

     *

     * @return a {@code Point2D} object that is a copy of the point

     * that anchors the last color of this {@code LinearGradientPaint}

     */

    public Point2D getEndPoint() {

        return new Point2D.Double(end.getX(), end.getY());

    }

}