/*
* 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 RadialGradientPaint} class provides a way to fill a shape with
* a circular radial color gradient pattern. The user may specify 2 or more
* gradient colors, and this paint will provide an interpolation between
* each color.
* <p>
* The user must specify the circle controlling the gradient pattern,
* which is described by a center point and a radius. The user can also
* specify a separate focus point within that circle, which controls the
* location of the first color of the gradient. By default the focus is
* set to be the center of the circle.
* <p>
* This paint will map the first color of the gradient to the focus point,
* and the last color to the perimeter of the circle, interpolating
* smoothly for any in-between colors specified by the user. Any line drawn
* from the focus point to the circumference will thus span all the gradient
* colors.
* <p>
* Specifying a focus point outside of the radius of the circle will cause
* the rings of the gradient pattern to be centered on the point just inside
* the edge of the circle in the direction of the focus point.
* The rendering will internally use this modified location as if it were
* the specified focus point.
* <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 RadialGradientPaint} object
* takes when it is filling the space outside the circle's radius by
* setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}.
* The gradient color proportions are equal for any particular line drawn
* from the focus point. The following figure shows that the distance AB
* is equal to the distance BC, and the distance AD is equal to the distance DE.
* <center>
* <img src = "doc-files/RadialGradientPaint-3.png" alt="image showing the
* distance AB=BC, and AD=DE">
* </center>
* If the gradient and graphics rendering transforms are uniformly scaled and
* the user sets the focus so that it coincides with the center of the circle,
* the gradient color proportions are equal for any line drawn from the center.
* The following figure shows the distances AB, BC, AD, and DE. They are all equal.
* <center>
* <img src = "doc-files/RadialGradientPaint-4.png" alt="image showing the
* distance of AB, BC, AD, and DE are all equal">
* </center>
* 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 last keyframe color 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 RadialGradientPaint}, where the center and focus points are
* the same:
* <pre>
* Point2D center = new Point2D.Float(50, 50);
* float radius = 25;
* float[] dist = {0.0f, 0.2f, 1.0f};
* Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
* RadialGradientPaint p =
* new RadialGradientPaint(center, radius, dist, colors);
* </pre>
*
* <p>
* This image demonstrates the example code above, with default
* (centered) focus for each of the three cycle methods:
* <center>
* <img src = "doc-files/RadialGradientPaint-1.png" alt="image showing the
* output of the sameple code">
* </center>
*
* <p>
* It is also possible to specify a non-centered focus point, as
* in the following code:
* <pre>
* Point2D center = new Point2D.Float(50, 50);
* float radius = 25;
* Point2D focus = new Point2D.Float(40, 40);
* float[] dist = {0.0f, 0.2f, 1.0f};
* Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
* RadialGradientPaint p =
* new RadialGradientPaint(center, radius, focus,
* dist, colors,
* CycleMethod.NO_CYCLE);
* </pre>
*
* <p>
* This image demonstrates the previous example code, with non-centered
* focus for each of the three cycle methods:
* <center>
* <img src = "doc-files/RadialGradientPaint-2.png" alt="image showing the
* output of the sample 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 RadialGradientPaint extends MultipleGradientPaint {
/** Focus point which defines the 0% gradient stop X coordinate. */
private final Point2D focus;
/** Center of the circle defining the 100% gradient stop X coordinate. */
private final Point2D center;
/** Radius of the outermost circle defining the 100% gradient stop. */
private final float radius;
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code NO_CYCLE} repeating method and {@code SRGB} color space,
* using the center as the focus point.
*
* @param cx the X coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param cy the Y coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
*
* @throws NullPointerException
* if {@code fractions} array is null,
* or {@code colors} array is null
* @throws IllegalArgumentException
* if {@code radius} is non-positive,
* 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 RadialGradientPaint(float cx, float cy, float radius,
float[] fractions, Color[] colors)
{
this(cx, cy,
radius,
cx, cy,
fractions,
colors,
CycleMethod.NO_CYCLE);
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code NO_CYCLE} repeating method and {@code SRGB} color space,
* using the center as the focus point.
*
* @param center the center point, in user space, of the circle defining
* the gradient
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
*
* @throws NullPointerException
* if {@code center} point is null,
* or {@code fractions} array is null,
* or {@code colors} array is null
* @throws IllegalArgumentException
* if {@code radius} is non-positive,
* 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 RadialGradientPaint(Point2D center, float radius,
float[] fractions, Color[] colors)
{
this(center,
radius,
center,
fractions,
colors,
CycleMethod.NO_CYCLE);
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code SRGB} color space, using the center as the focus point.
*
* @param cx the X coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param cy the Y coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @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 {@code radius} is non-positive,
* 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 RadialGradientPaint(float cx, float cy, float radius,
float[] fractions, Color[] colors,
CycleMethod cycleMethod)
{
this(cx, cy,
radius,
cx, cy,
fractions,
colors,
cycleMethod);
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code SRGB} color space, using the center as the focus point.
*
* @param center the center point, in user space, of the circle defining
* the gradient
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
* or {@code REPEAT}
*
* @throws NullPointerException
* if {@code center} point is null,
* or {@code fractions} array is null,
* or {@code colors} array is null,
* or {@code cycleMethod} is null
* @throws IllegalArgumentException
* if {@code radius} is non-positive,
* 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 RadialGradientPaint(Point2D center, float radius,
float[] fractions, Color[] colors,
CycleMethod cycleMethod)
{
this(center,
radius,
center,
fractions,
colors,
cycleMethod);
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code SRGB} color space.
*
* @param cx the X coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param cy the Y coordinate in user space of the center point of the
* circle defining the gradient. The last color of the
* gradient is mapped to the perimeter of this circle.
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param fx the X coordinate of the point in user space to which the
* first color is mapped
* @param fy the Y coordinate of the point in user space to which the
* first color is mapped
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @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 {@code radius} is non-positive,
* 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 RadialGradientPaint(float cx, float cy, float radius,
float fx, float fy,
float[] fractions, Color[] colors,
CycleMethod cycleMethod)
{
this(new Point2D.Float(cx, cy),
radius,
new Point2D.Float(fx, fy),
fractions,
colors,
cycleMethod);
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code SRGB} color space.
*
* @param center the center point, in user space, of the circle defining
* the gradient. The last color of the gradient is mapped
* to the perimeter of this circle.
* @param radius the radius of the circle defining the extents of the color
* gradient
* @param focus the point in user space to which the first color is mapped
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @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 {@code radius} is non-positive,
* 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 RadialGradientPaint(Point2D center, float radius,
Point2D focus,
float[] fractions, Color[] colors,
CycleMethod cycleMethod)
{
this(center,
radius,
focus,
fractions,
colors,
cycleMethod,
ColorSpaceType.SRGB,
new AffineTransform());
}
/**
* Constructs a {@code RadialGradientPaint}.
*
* @param center the center point in user space of the circle defining the
* gradient. The last color of the gradient is mapped to
* the perimeter of this circle.
* @param radius the radius of the circle defining the extents of the
* color gradient
* @param focus the point in user space to which the first color is mapped
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @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 {@code radius} is non-positive,
* 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({ "centerPoint", "radius", "focusPoint", "fractions", "colors", "cycleMethod", "colorSpace", "transform" })
public RadialGradientPaint(Point2D center,
float radius,
Point2D focus,
float[] fractions, Color[] colors,
CycleMethod cycleMethod,
ColorSpaceType colorSpace,
AffineTransform gradientTransform)
{
super(fractions, colors, cycleMethod, colorSpace, gradientTransform);
// check input arguments
if (center == null) {
throw new NullPointerException("Center point must be non-null");
}
if (focus == null) {
throw new NullPointerException("Focus point must be non-null");
}
if (radius <= 0) {
throw new IllegalArgumentException("Radius must be greater " +
"than zero");
}
// copy parameters
this.center = new Point2D.Double(center.getX(), center.getY());
this.focus = new Point2D.Double(focus.getX(), focus.getY());
this.radius = radius;
}
/**
* Constructs a {@code RadialGradientPaint} with a default
* {@code SRGB} color space.
* The gradient circle of the {@code RadialGradientPaint} is defined
* by the given bounding box.
* <p>
* This constructor is a more convenient way to express the
* following (equivalent) code:<br>
*
* <pre>
* double gw = gradientBounds.getWidth();
* double gh = gradientBounds.getHeight();
* double cx = gradientBounds.getCenterX();
* double cy = gradientBounds.getCenterY();
* Point2D center = new Point2D.Double(cx, cy);
*
* AffineTransform gradientTransform = new AffineTransform();
* gradientTransform.translate(cx, cy);
* gradientTransform.scale(gw / 2, gh / 2);
* gradientTransform.translate(-cx, -cy);
*
* RadialGradientPaint gp =
* new RadialGradientPaint(center, 1.0f, center,
* fractions, colors,
* cycleMethod,
* ColorSpaceType.SRGB,
* gradientTransform);
* </pre>
*
* @param gradientBounds the bounding box, in user space, of the circle
* defining the outermost extent of the gradient
* @param fractions numbers ranging from 0.0 to 1.0 specifying the
* distribution of colors along the gradient
* @param colors array of colors to use in the gradient. The first color
* is used at the focus point, the last color around the
* perimeter of the circle.
* @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
* or {@code REPEAT}
*
* @throws NullPointerException
* if {@code gradientBounds} is null,
* or {@code fractions} array is null,
* or {@code colors} array is null,
* or {@code cycleMethod} is null
* @throws IllegalArgumentException
* if {@code gradientBounds} is empty,
* 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 RadialGradientPaint(Rectangle2D gradientBounds,
float[] fractions, Color[] colors,
CycleMethod cycleMethod)
{
// gradient center/focal point is the center of the bounding box,
// radius is set to 1.0, and then we set a scale transform
// to achieve an elliptical gradient defined by the bounding box
this(new Point2D.Double(gradientBounds.getCenterX(),
gradientBounds.getCenterY()),
1.0f,
new Point2D.Double(gradientBounds.getCenterX(),
gradientBounds.getCenterY()),
fractions,
colors,
cycleMethod,
ColorSpaceType.SRGB,
createGradientTransform(gradientBounds));
if (gradientBounds.isEmpty()) {
throw new IllegalArgumentException("Gradient bounds must be " +
"non-empty");
}
}
private static AffineTransform createGradientTransform(Rectangle2D r) {
double cx = r.getCenterX();
double cy = r.getCenterY();
AffineTransform xform = AffineTransform.getTranslateInstance(cx, cy);
xform.scale(r.getWidth()/2, r.getHeight()/2);
xform.translate(-cx, -cy);
return xform;
}
/**
* Creates and returns a {@link PaintContext} used to
* generate a circular radial color gradient pattern.
* See the description of the {@link Paint#createContext createContext} method
* 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);
return new RadialGradientPaintContext(this, cm,
deviceBounds, userBounds,
transform, hints,
(float)center.getX(),
(float)center.getY(),
radius,
(float)focus.getX(),
(float)focus.getY(),
fractions, colors,
cycleMethod, colorSpace);
}
/**
* Returns a copy of the center point of the radial gradient.
*
* @return a {@code Point2D} object that is a copy of the center point
*/
public Point2D getCenterPoint() {
return new Point2D.Double(center.getX(), center.getY());
}
/**
* Returns a copy of the focus point of the radial gradient.
* Note that if the focus point specified when the radial gradient
* was constructed lies outside of the radius of the circle, this
* method will still return the original focus point even though
* the rendering may center the rings of color on a different
* point that lies inside the radius.
*
* @return a {@code Point2D} object that is a copy of the focus point
*/
public Point2D getFocusPoint() {
return new Point2D.Double(focus.getX(), focus.getY());
}
/**
* Returns the radius of the circle defining the radial gradient.
*
* @return the radius of the circle defining the radial gradient
*/
public float getRadius() {
return radius;
}
}