LinearGradientPaint.java revision 3909
2830N/A * Copyright (c) 2006, 2011, Oracle and/or its affiliates. All rights reserved. 2830N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 2830N/A * This code is free software; you can redistribute it and/or modify it 2830N/A * under the terms of the GNU General Public License version 2 only, as 2830N/A * published by the Free Software Foundation. Oracle designates this 2830N/A * particular file as subject to the "Classpath" exception as provided 2830N/A * by Oracle in the LICENSE file that accompanied this code. 2830N/A * This code is distributed in the hope that it will be useful, but WITHOUT 2830N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 2830N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 2830N/A * version 2 for more details (a copy is included in the LICENSE file that 2830N/A * You should have received a copy of the GNU General Public License version 2830N/A * 2 along with this work; if not, write to the Free Software Foundation, 2830N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2830N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2830N/A * or visit www.oracle.com if you need additional information or have any 2830N/A * The {@code LinearGradientPaint} class provides a way to fill 3478N/A * a {@link java.awt.Shape} with a linear color gradient pattern. The user 2830N/A * may specify two or more gradient colors, and this paint will provide an 2830N/A * interpolation between each color. The user also specifies start and end 2830N/A * points which define where in user space the color gradient should begin 2830N/A * The user must provide an array of floats specifying how to distribute the 2830N/A * colors along the gradient. These values should range from 0.0 to 1.0 and 2830N/A * act like keyframes along the gradient (they mark where the gradient should 2830N/A * be exactly a particular color). 2830N/A * In the event that the user does not set the first keyframe value equal 3216N/A * to 0 and/or the last keyframe value equal to 1, keyframes will be created 2830N/A * at these positions and the first and last colors will be replicated there. 2830N/A * So, if a user specifies the following arrays to construct a gradient:<br> 2830N/A * {Color.BLUE, Color.RED}, {.3f, .7f} 2830N/A * this will be converted to a gradient with the following keyframes:<br> 2830N/A * {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f} 2830N/A * The user may also select what action the {@code LinearGradientPaint} object 2830N/A * takes when it is filling the space outside the start and end points by 2830N/A * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}. 2830N/A * The distances between any two colors in any of the reflected or repeated 2830N/A * copies of the gradient are the same as the distance between those same two 2830N/A * colors between the start and end points. 2830N/A * Note that some minor variations in distances may occur due to sampling at 2830N/A * the granularity of a pixel. 2830N/A * If no cycle method is specified, {@code NO_CYCLE} will be chosen by 2830N/A * default, which means the endpoint colors will be used to fill the 2830N/A * The colorSpace parameter allows the user to specify in which colorspace 3060N/A * the interpolation should be performed, default sRGB or linearized RGB. 3060N/A * The following code demonstrates typical usage of 2830N/A * {@code LinearGradientPaint}: 3060N/A * Point2D start = new Point2D.Float(0, 0); 3060N/A * Point2D end = new Point2D.Float(50, 50); 2830N/A * float[] dist = {0.0f, 0.2f, 1.0f}; 2830N/A * Color[] colors = {Color.RED, Color.WHITE, Color.BLUE}; 2830N/A * new LinearGradientPaint(start, end, dist, colors); 2830N/A * This code will create a {@code LinearGradientPaint} which interpolates 2830N/A * between red and white for the first 20% of the gradient and between white 2830N/A * and blue for the remaining 80%. 2830N/A * This image demonstrates the example code above for each 2830N/A * of the three cycle methods: 2830N/A * @see java.awt.Graphics2D#setPaint 2830N/A * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans 2830N/A /** Gradient start and end points. */ 2830N/A * Constructs a {@code LinearGradientPaint} with a default 2830N/A * {@code NO_CYCLE} repeating method and {@code SRGB} color space. 2830N/A * @param startX the X coordinate of the gradient axis start point 2830N/A * @param startY the Y coordinate of the gradient axis start point 2830N/A * @param endX the X coordinate of the gradient axis end point 2830N/A * @param endY the Y coordinate of the gradient axis end point 2830N/A * @param fractions numbers ranging from 0.0 to 1.0 specifying the 2830N/A * distribution of colors along the gradient 2830N/A * @param colors array of colors corresponding to each fractional value 2830N/A * @throws NullPointerException 2830N/A * if {@code fractions} array is null, 2830N/A * or {@code colors} array is null, 2830N/A * @throws IllegalArgumentException 2830N/A * if start and end points are the same points, 2830N/A * or {@code fractions.length != colors.length}, 2830N/A * or {@code colors} is less than 2 in size, 2830N/A * or a {@code fractions} value is less than 0.0 or greater than 1.0, 2830N/A * or the {@code fractions} are not provided in strictly increasing order 3478N/A * Constructs a {@code LinearGradientPaint} with a default {@code SRGB} 3478N/A * @param startX the X coordinate of the gradient axis start point 3060N/A * @param startY the Y coordinate of the gradient axis start point 2830N/A * @param endX the X coordinate of the gradient axis end point 3478N/A * @param endY the Y coordinate of the gradient axis end point 2830N/A * @param fractions numbers ranging from 0.0 to 1.0 specifying the 2830N/A * distribution of colors along the gradient 2830N/A * @param colors array of colors corresponding to each fractional value 2830N/A * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, 2830N/A * @throws NullPointerException 2830N/A * if {@code fractions} array is null, 2830N/A * or {@code colors} array is null, 3478N/A * or {@code cycleMethod} is null 2830N/A * @throws IllegalArgumentException 2830N/A * if start and end points are the same points, 2830N/A * or {@code fractions.length != colors.length}, 2830N/A * or {@code colors} is less than 2 in size, 3478N/A * or a {@code fractions} value is less than 0.0 or greater than 1.0, 2830N/A * or the {@code fractions} are not provided in strictly increasing order 2830N/A * Constructs a {@code LinearGradientPaint} with a default 3060N/A * {@code NO_CYCLE} repeating method and {@code SRGB} color space. 3060N/A * @param start the gradient axis start {@code Point2D} in user space 3478N/A * @param end the gradient axis end {@code Point2D} in user space 3060N/A * @param fractions numbers ranging from 0.0 to 1.0 specifying the 3060N/A * distribution of colors along the gradient 3060N/A * @param colors array of colors corresponding to each fractional value 3478N/A * @throws NullPointerException 3060N/A * if one of the points is null, 2830N/A * or {@code fractions} array is null, 3503N/A * or {@code colors} array is null 3478N/A * @throws IllegalArgumentException 3478N/A * if start and end points are the same points, 2830N/A * or {@code fractions.length != colors.length}, 2830N/A * or {@code colors} is less than 2 in size, 3503N/A * or a {@code fractions} value is less than 0.0 or greater than 1.0, 3478N/A * or the {@code fractions} are not provided in strictly increasing order 2830N/A * Constructs a {@code LinearGradientPaint} with a default {@code SRGB} 2830N/A * @param start the gradient axis start {@code Point2D} in user space 2830N/A * @param end the gradient axis end {@code Point2D} in user space 3478N/A * @param fractions numbers ranging from 0.0 to 1.0 specifying the 3478N/A * distribution of colors along the gradient 2830N/A * @param colors array of colors corresponding to each fractional value 3478N/A * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, 3060N/A * @throws NullPointerException 3060N/A * if one of the points is null, 3060N/A * or {@code fractions} array is null, 3060N/A * or {@code colors} array is null, 3060N/A * or {@code cycleMethod} is null 3478N/A * @throws IllegalArgumentException 3478N/A * if start and end points are the same points, 3060N/A * or {@code fractions.length != colors.length}, 3478N/A * or {@code colors} is less than 2 in size, 3060N/A * or a {@code fractions} value is less than 0.0 or greater than 1.0, 3060N/A * or the {@code fractions} are not provided in strictly increasing order 3478N/A * Constructs a {@code LinearGradientPaint}. 2830N/A * @param start the gradient axis start {@code Point2D} in user space 3478N/A * @param end the gradient axis end {@code Point2D} in user space 2830N/A * @param fractions numbers ranging from 0.0 to 1.0 specifying the 3478N/A * distribution of colors along the gradient 2830N/A * @param colors array of colors corresponding to each fractional value 3478N/A * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, 2830N/A * @param colorSpace which color space to use for interpolation, 2830N/A * either {@code SRGB} or {@code LINEAR_RGB} 2830N/A * @param gradientTransform transform to apply to the gradient 2830N/A * @throws NullPointerException 2830N/A * if one of the points is null, 2830N/A * or {@code fractions} array is null, 2830N/A * or {@code colors} array is null, 2830N/A * or {@code cycleMethod} is null, 2830N/A * or {@code colorSpace} is null, 2830N/A * or {@code gradientTransform} is null 2830N/A * @throws IllegalArgumentException 2830N/A * if start and end points are the same points, 2830N/A * or {@code fractions.length != colors.length}, 2830N/A * or {@code colors} is less than 2 in size, 2830N/A * or a {@code fractions} value is less than 0.0 or greater than 1.0, 2830N/A * or the {@code fractions} are not provided in strictly increasing order 2830N/A * Creates and returns a {@link PaintContext} used to 2830N/A * generate a linear color gradient pattern. 3478N/A * See the {@link Paint#createContext specification} of the 3478N/A * method in the {@link Paint} interface for information 3478N/A * on null parameter handling. 3478N/A * @param cm the preferred {@link ColorModel} which represents the most convenient 2830N/A * format for the caller to receive the pixel data, or {@code null} 2830N/A * if there is no preference. 3478N/A * @param deviceBounds the device space bounding box 2830N/A * of the graphics primitive being rendered. 2830N/A * @param userBounds the user space bounding box 2830N/A * of the graphics primitive being rendered. 2830N/A * @param transform the {@link AffineTransform} from user 2830N/A * @param hints the set of hints that the context object can use to 2830N/A * choose between rendering alternatives. 3060N/A * @return the {@code PaintContext} for 2830N/A * generating color patterns. 3060N/A // avoid modifying the user's transform... 3060N/A // incorporate the gradient transform 2830N/A // faster to use the basic GradientPaintContext for this 2830N/A * Returns a copy of the start point of the gradient axis. 4123N/A * @return a {@code Point2D} object that is a copy of the point 4123N/A * that anchors the first color of this {@code LinearGradientPaint} 2830N/A * Returns a copy of the end point of the gradient axis. 2830N/A * @return a {@code Point2D} object that is a copy of the point 2830N/A * that anchors the last color of this {@code LinearGradientPaint}
