001 /*
002 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt;
027
028 import java.awt.geom.AffineTransform;
029 import java.awt.geom.Point2D;
030 import java.awt.geom.Rectangle2D;
031 import java.awt.image.ColorModel;
032
033 /**
034 * The {@code RadialGradientPaint} class provides a way to fill a shape with
035 * a circular radial color gradient pattern. The user may specify 2 or more
036 * gradient colors, and this paint will provide an interpolation between
037 * each color.
038 * <p>
039 * The user must specify the circle controlling the gradient pattern,
040 * which is described by a center point and a radius. The user can also
041 * specify a separate focus point within that circle, which controls the
042 * location of the first color of the gradient. By default the focus is
043 * set to be the center of the circle.
044 * <p>
045 * This paint will map the first color of the gradient to the focus point,
046 * and the last color to the perimeter of the circle, interpolating
047 * smoothly for any in-between colors specified by the user. Any line drawn
048 * from the focus point to the circumference will thus span all the gradient
049 * colors.
050 * <p>
051 * Specifying a focus point outside of the circle's radius will result in the
052 * focus being set to the intersection point of the focus-center line and the
053 * perimeter of the circle.
054 * <p>
055 * The user must provide an array of floats specifying how to distribute the
056 * colors along the gradient. These values should range from 0.0 to 1.0 and
057 * act like keyframes along the gradient (they mark where the gradient should
058 * be exactly a particular color).
059 * <p>
060 * In the event that the user does not set the first keyframe value equal
061 * to 0 and/or the last keyframe value equal to 1, keyframes will be created
062 * at these positions and the first and last colors will be replicated there.
063 * So, if a user specifies the following arrays to construct a gradient:<br>
064 * <pre>
065 * {Color.BLUE, Color.RED}, {.3f, .7f}
066 * </pre>
067 * this will be converted to a gradient with the following keyframes:<br>
068 * <pre>
069 * {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f}
070 * </pre>
071 *
072 * <p>
073 * The user may also select what action the {@code RadialGradientPaint}
074 * should take when filling color outside the bounds of the circle's radius.
075 * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
076 * default, which means the the last keyframe color will be used to fill the
077 * remaining area.
078 * <p>
079 * The colorSpace parameter allows the user to specify in which colorspace
080 * the interpolation should be performed, default sRGB or linearized RGB.
081 *
082 * <p>
083 * The following code demonstrates typical usage of
084 * {@code RadialGradientPaint}, where the center and focus points are
085 * the same:
086 * <p>
087 * <pre>
088 * Point2D center = new Point2D.Float(50, 50);
089 * float radius = 25;
090 * float[] dist = {0.0f, 0.2f, 1.0f};
091 * Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
092 * RadialGradientPaint p =
093 * new RadialGradientPaint(center, radius, dist, colors);
094 * </pre>
095 *
096 * <p>
097 * This image demonstrates the example code above, with default
098 * (centered) focus for each of the three cycle methods:
099 * <p>
100 * <center>
101 * <img src = "doc-files/RadialGradientPaint-1.png">
102 * </center>
103 *
104 * <p>
105 * It is also possible to specify a non-centered focus point, as
106 * in the following code:
107 * <p>
108 * <pre>
109 * Point2D center = new Point2D.Float(50, 50);
110 * float radius = 25;
111 * Point2D focus = new Point2D.Float(40, 40);
112 * float[] dist = {0.0f, 0.2f, 1.0f};
113 * Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
114 * RadialGradientPaint p =
115 * new RadialGradientPaint(center, radius, focus,
116 * dist, colors,
117 * CycleMethod.NO_CYCLE);
118 * </pre>
119 *
120 * <p>
121 * This image demonstrates the previous example code, with non-centered
122 * focus for each of the three cycle methods:
123 * <p>
124 * <center>
125 * <img src = "doc-files/RadialGradientPaint-2.png">
126 * </center>
127 *
128 * @see java.awt.Paint
129 * @see java.awt.Graphics2D#setPaint
130 * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans
131 * @since 1.6
132 */
133 public final class RadialGradientPaint extends MultipleGradientPaint {
134
135 /** Focus point which defines the 0% gradient stop X coordinate. */
136 private final Point2D focus;
137
138 /** Center of the circle defining the 100% gradient stop X coordinate. */
139 private final Point2D center;
140
141 /** Radius of the outermost circle defining the 100% gradient stop. */
142 private final float radius;
143
144 /**
145 * Constructs a {@code RadialGradientPaint} with a default
146 * {@code NO_CYCLE} repeating method and {@code SRGB} color space,
147 * using the center as the focus point.
148 *
149 * @param cx the X coordinate in user space of the center point of the
150 * circle defining the gradient. The last color of the
151 * gradient is mapped to the perimeter of this circle.
152 * @param cy the Y coordinate in user space of the center point of the
153 * circle defining the gradient. The last color of the
154 * gradient is mapped to the perimeter of this circle.
155 * @param radius the radius of the circle defining the extents of the
156 * color gradient
157 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
158 * distribution of colors along the gradient
159 * @param colors array of colors to use in the gradient. The first color
160 * is used at the focus point, the last color around the
161 * perimeter of the circle.
162 *
163 * @throws NullPointerException
164 * if {@code fractions} array is null,
165 * or {@code colors} array is null
166 * @throws IllegalArgumentException
167 * if {@code radius} is non-positive,
168 * or {@code fractions.length != colors.length},
169 * or {@code colors} is less than 2 in size,
170 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
171 * or the {@code fractions} are not provided in strictly increasing order
172 */
173 public RadialGradientPaint(float cx, float cy, float radius,
174 float[] fractions, Color[] colors) {
175 this (cx, cy, radius, cx, cy, fractions, colors,
176 CycleMethod.NO_CYCLE);
177 }
178
179 /**
180 * Constructs a {@code RadialGradientPaint} with a default
181 * {@code NO_CYCLE} repeating method and {@code SRGB} color space,
182 * using the center as the focus point.
183 *
184 * @param center the center point, in user space, of the circle defining
185 * the gradient
186 * @param radius the radius of the circle defining the extents of the
187 * color gradient
188 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
189 * distribution of colors along the gradient
190 * @param colors array of colors to use in the gradient. The first color
191 * is used at the focus point, the last color around the
192 * perimeter of the circle.
193 *
194 * @throws NullPointerException
195 * if {@code center} point is null,
196 * or {@code fractions} array is null,
197 * or {@code colors} array is null
198 * @throws IllegalArgumentException
199 * if {@code radius} is non-positive,
200 * or {@code fractions.length != colors.length},
201 * or {@code colors} is less than 2 in size,
202 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
203 * or the {@code fractions} are not provided in strictly increasing order
204 */
205 public RadialGradientPaint(Point2D center, float radius,
206 float[] fractions, Color[] colors) {
207 this (center, radius, center, fractions, colors,
208 CycleMethod.NO_CYCLE);
209 }
210
211 /**
212 * Constructs a {@code RadialGradientPaint} with a default
213 * {@code SRGB} color space, using the center as the focus point.
214 *
215 * @param cx the X coordinate in user space of the center point of the
216 * circle defining the gradient. The last color of the
217 * gradient is mapped to the perimeter of this circle.
218 * @param cy the Y coordinate in user space of the center point of the
219 * circle defining the gradient. The last color of the
220 * gradient is mapped to the perimeter of this circle.
221 * @param radius the radius of the circle defining the extents of the
222 * color gradient
223 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
224 * distribution of colors along the gradient
225 * @param colors array of colors to use in the gradient. The first color
226 * is used at the focus point, the last color around the
227 * perimeter of the circle.
228 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
229 * or {@code REPEAT}
230 *
231 * @throws NullPointerException
232 * if {@code fractions} array is null,
233 * or {@code colors} array is null,
234 * or {@code cycleMethod} is null
235 * @throws IllegalArgumentException
236 * if {@code radius} is non-positive,
237 * or {@code fractions.length != colors.length},
238 * or {@code colors} is less than 2 in size,
239 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
240 * or the {@code fractions} are not provided in strictly increasing order
241 */
242 public RadialGradientPaint(float cx, float cy, float radius,
243 float[] fractions, Color[] colors, CycleMethod cycleMethod) {
244 this (cx, cy, radius, cx, cy, fractions, colors, cycleMethod);
245 }
246
247 /**
248 * Constructs a {@code RadialGradientPaint} with a default
249 * {@code SRGB} color space, using the center as the focus point.
250 *
251 * @param center the center point, in user space, of the circle defining
252 * the gradient
253 * @param radius the radius of the circle defining the extents of the
254 * color gradient
255 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
256 * distribution of colors along the gradient
257 * @param colors array of colors to use in the gradient. The first color
258 * is used at the focus point, the last color around the
259 * perimeter of the circle.
260 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
261 * or {@code REPEAT}
262 *
263 * @throws NullPointerException
264 * if {@code center} point is null,
265 * or {@code fractions} array is null,
266 * or {@code colors} array is null,
267 * or {@code cycleMethod} is null
268 * @throws IllegalArgumentException
269 * if {@code radius} is non-positive,
270 * or {@code fractions.length != colors.length},
271 * or {@code colors} is less than 2 in size,
272 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
273 * or the {@code fractions} are not provided in strictly increasing order
274 */
275 public RadialGradientPaint(Point2D center, float radius,
276 float[] fractions, Color[] colors, CycleMethod cycleMethod) {
277 this (center, radius, center, fractions, colors, cycleMethod);
278 }
279
280 /**
281 * Constructs a {@code RadialGradientPaint} with a default
282 * {@code SRGB} color space.
283 *
284 * @param cx the X coordinate in user space of the center point of the
285 * circle defining the gradient. The last color of the
286 * gradient is mapped to the perimeter of this circle.
287 * @param cy the Y coordinate in user space of the center point of the
288 * circle defining the gradient. The last color of the
289 * gradient is mapped to the perimeter of this circle.
290 * @param radius the radius of the circle defining the extents of the
291 * color gradient
292 * @param fx the X coordinate of the point in user space to which the
293 * first color is mapped
294 * @param fy the Y coordinate of the point in user space to which the
295 * first color is mapped
296 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
297 * distribution of colors along the gradient
298 * @param colors array of colors to use in the gradient. The first color
299 * is used at the focus point, the last color around the
300 * perimeter of the circle.
301 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
302 * or {@code REPEAT}
303 *
304 * @throws NullPointerException
305 * if {@code fractions} array is null,
306 * or {@code colors} array is null,
307 * or {@code cycleMethod} is null
308 * @throws IllegalArgumentException
309 * if {@code radius} is non-positive,
310 * or {@code fractions.length != colors.length},
311 * or {@code colors} is less than 2 in size,
312 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
313 * or the {@code fractions} are not provided in strictly increasing order
314 */
315 public RadialGradientPaint(float cx, float cy, float radius,
316 float fx, float fy, float[] fractions, Color[] colors,
317 CycleMethod cycleMethod) {
318 this (new Point2D.Float(cx, cy), radius, new Point2D.Float(fx,
319 fy), fractions, colors, cycleMethod);
320 }
321
322 /**
323 * Constructs a {@code RadialGradientPaint} with a default
324 * {@code SRGB} color space.
325 *
326 * @param center the center point, in user space, of the circle defining
327 * the gradient. The last color of the gradient is mapped
328 * to the perimeter of this circle.
329 * @param radius the radius of the circle defining the extents of the color
330 * gradient
331 * @param focus the point in user space to which the first color is mapped
332 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
333 * distribution of colors along the gradient
334 * @param colors array of colors to use in the gradient. The first color
335 * is used at the focus point, the last color around the
336 * perimeter of the circle.
337 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
338 * or {@code REPEAT}
339 *
340 * @throws NullPointerException
341 * if one of the points is null,
342 * or {@code fractions} array is null,
343 * or {@code colors} array is null,
344 * or {@code cycleMethod} is null
345 * @throws IllegalArgumentException
346 * if {@code radius} is non-positive,
347 * or {@code fractions.length != colors.length},
348 * or {@code colors} is less than 2 in size,
349 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
350 * or the {@code fractions} are not provided in strictly increasing order
351 */
352 public RadialGradientPaint(Point2D center, float radius,
353 Point2D focus, float[] fractions, Color[] colors,
354 CycleMethod cycleMethod) {
355 this (center, radius, focus, fractions, colors, cycleMethod,
356 ColorSpaceType.SRGB, new AffineTransform());
357 }
358
359 /**
360 * Constructs a {@code RadialGradientPaint}.
361 *
362 * @param center the center point in user space of the circle defining the
363 * gradient. The last color of the gradient is mapped to
364 * the perimeter of this circle.
365 * @param radius the radius of the circle defining the extents of the
366 * color gradient
367 * @param focus the point in user space to which the first color is mapped
368 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
369 * distribution of colors along the gradient
370 * @param colors array of colors to use in the gradient. The first color
371 * is used at the focus point, the last color around the
372 * perimeter of the circle.
373 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
374 * or {@code REPEAT}
375 * @param colorSpace which color space to use for interpolation,
376 * either {@code SRGB} or {@code LINEAR_RGB}
377 * @param gradientTransform transform to apply to the gradient
378 *
379 * @throws NullPointerException
380 * if one of the points is null,
381 * or {@code fractions} array is null,
382 * or {@code colors} array is null,
383 * or {@code cycleMethod} is null,
384 * or {@code colorSpace} is null,
385 * or {@code gradientTransform} is null
386 * @throws IllegalArgumentException
387 * if {@code radius} is non-positive,
388 * or {@code fractions.length != colors.length},
389 * or {@code colors} is less than 2 in size,
390 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
391 * or the {@code fractions} are not provided in strictly increasing order
392 */
393 public RadialGradientPaint(Point2D center, float radius,
394 Point2D focus, float[] fractions, Color[] colors,
395 CycleMethod cycleMethod, ColorSpaceType colorSpace,
396 AffineTransform gradientTransform) {
397 super (fractions, colors, cycleMethod, colorSpace,
398 gradientTransform);
399
400 // check input arguments
401 if (center == null) {
402 throw new NullPointerException(
403 "Center point must be non-null");
404 }
405
406 if (focus == null) {
407 throw new NullPointerException(
408 "Focus point must be non-null");
409 }
410
411 if (radius <= 0) {
412 throw new IllegalArgumentException(
413 "Radius must be greater " + "than zero");
414 }
415
416 // copy parameters
417 this .center = new Point2D.Double(center.getX(), center.getY());
418 this .focus = new Point2D.Double(focus.getX(), focus.getY());
419 this .radius = radius;
420 }
421
422 /**
423 * Constructs a {@code RadialGradientPaint} with a default
424 * {@code SRGB} color space.
425 * The gradient circle of the {@code RadialGradientPaint} is defined
426 * by the given bounding box.
427 * <p>
428 * This constructor is a more convenient way to express the
429 * following (equivalent) code:<br>
430 *
431 * <pre>
432 * double gw = gradientBounds.getWidth();
433 * double gh = gradientBounds.getHeight();
434 * double cx = gradientBounds.getCenterX();
435 * double cy = gradientBounds.getCenterY();
436 * Point2D center = new Point2D.Double(cx, cy);
437 *
438 * AffineTransform gradientTransform = new AffineTransform();
439 * gradientTransform.translate(cx, cy);
440 * gradientTransform.scale(gw / 2, gh / 2);
441 * gradientTransform.translate(-cx, -cy);
442 *
443 * RadialGradientPaint gp =
444 * new RadialGradientPaint(center, 1.0f, center,
445 * fractions, colors,
446 * cycleMethod,
447 * ColorSpaceType.SRGB,
448 * gradientTransform);
449 * </pre>
450 *
451 * @param gradientBounds the bounding box, in user space, of the circle
452 * defining the outermost extent of the gradient
453 * @param fractions numbers ranging from 0.0 to 1.0 specifying the
454 * distribution of colors along the gradient
455 * @param colors array of colors to use in the gradient. The first color
456 * is used at the focus point, the last color around the
457 * perimeter of the circle.
458 * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
459 * or {@code REPEAT}
460 *
461 * @throws NullPointerException
462 * if {@code gradientBounds} is null,
463 * or {@code fractions} array is null,
464 * or {@code colors} array is null,
465 * or {@code cycleMethod} is null
466 * @throws IllegalArgumentException
467 * if {@code gradientBounds} is empty,
468 * or {@code fractions.length != colors.length},
469 * or {@code colors} is less than 2 in size,
470 * or a {@code fractions} value is less than 0.0 or greater than 1.0,
471 * or the {@code fractions} are not provided in strictly increasing order
472 */
473 public RadialGradientPaint(Rectangle2D gradientBounds,
474 float[] fractions, Color[] colors, CycleMethod cycleMethod) {
475 // gradient center/focal point is the center of the bounding box,
476 // radius is set to 1.0, and then we set a scale transform
477 // to achieve an elliptical gradient defined by the bounding box
478 this (new Point2D.Double(gradientBounds.getCenterX(),
479 gradientBounds.getCenterY()), 1.0f, new Point2D.Double(
480 gradientBounds.getCenterX(), gradientBounds
481 .getCenterY()), fractions, colors, cycleMethod,
482 ColorSpaceType.SRGB,
483 createGradientTransform(gradientBounds));
484
485 if (gradientBounds.isEmpty()) {
486 throw new IllegalArgumentException(
487 "Gradient bounds must be " + "non-empty");
488 }
489 }
490
491 private static AffineTransform createGradientTransform(Rectangle2D r) {
492 double cx = r.getCenterX();
493 double cy = r.getCenterY();
494 AffineTransform xform = AffineTransform.getTranslateInstance(
495 cx, cy);
496 xform.scale(r.getWidth() / 2, r.getHeight() / 2);
497 xform.translate(-cx, -cy);
498 return xform;
499 }
500
501 /**
502 * {@inheritDoc}
503 */
504 public PaintContext createContext(ColorModel cm,
505 Rectangle deviceBounds, Rectangle2D userBounds,
506 AffineTransform transform, RenderingHints hints) {
507 // avoid modifying the user's transform...
508 transform = new AffineTransform(transform);
509 // incorporate the gradient transform
510 transform.concatenate(gradientTransform);
511
512 return new RadialGradientPaintContext(this , cm, deviceBounds,
513 userBounds, transform, hints, (float) center.getX(),
514 (float) center.getY(), radius, (float) focus.getX(),
515 (float) focus.getY(), fractions, colors, cycleMethod,
516 colorSpace);
517 }
518
519 /**
520 * Returns a copy of the center point of the radial gradient.
521 *
522 * @return a {@code Point2D} object that is a copy of the center point
523 */
524 public Point2D getCenterPoint() {
525 return new Point2D.Double(center.getX(), center.getY());
526 }
527
528 /**
529 * Returns a copy of the end point of the gradient axis.
530 *
531 * @return a {@code Point2D} object that is a copy of the focus point
532 */
533 public Point2D getFocusPoint() {
534 return new Point2D.Double(focus.getX(), focus.getY());
535 }
536
537 /**
538 * Returns the radius of the circle defining the radial gradient.
539 *
540 * @return the radius of the circle defining the radial gradient
541 */
542 public float getRadius() {
543 return radius;
544 }
545 }
|