RadialGradientPaint


1   /*
2    * @(#)RadialGradientPaint.java 1.2 06/04/24
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt;
9   
10  import java.awt.geom.AffineTransform  ;
11  import java.awt.geom.Point2D  ;
12  import java.awt.geom.Rectangle2D  ;
13  import java.awt.image.ColorModel  ;
14  
15  /**
16   * The {@code RadialGradientPaint} class provides a way to fill a shape with
17   * a circular radial color gradient pattern. The user may specify 2 or more
18   * gradient colors, and this paint will provide an interpolation between
19   * each color.
20   * <p>
21   * The user must specify the circle controlling the gradient pattern,
22   * which is described by a center point and a radius.  The user can also
23   * specify a separate focus point within that circle, which controls the
24   * location of the first color of the gradient.  By default the focus is
25   * set to be the center of the circle.
26   * <p>
27   * This paint will map the first color of the gradient to the focus point,
28   * and the last color to the perimeter of the circle, interpolating
29   * smoothly for any in-between colors specified by the user.  Any line drawn 
30   * from the focus point to the circumference will thus span all the gradient 
31   * colors.
32   * <p>
33   * Specifying a focus point outside of the circle's radius will result in the 
34   * focus being set to the intersection point of the focus-center line and the 
35   * perimeter of the circle.
36   * <p>
37   * The user must provide an array of floats specifying how to distribute the 
38   * colors along the gradient.  These values should range from 0.0 to 1.0 and 
39   * act like keyframes along the gradient (they mark where the gradient should 
40   * be exactly a particular color).
41   * <p>
42   * In the event that the user does not set the first keyframe value equal
43   * to 0 and/or the last keyframe value equal to 1, keyframes will be created
44   * at these positions and the first and last colors will be replicated there.
45   * So, if a user specifies the following arrays to construct a gradient:<br>
46   * <pre>
47   *     {Color.BLUE, Color.RED}, {.3f, .7f}
48   * </pre>
49   * this will be converted to a gradient with the following keyframes:<br>
50   * <pre>
51   *     {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f}
52   * </pre>
53   *
54   * <p>
55   * The user may also select what action the {@code RadialGradientPaint}
56   * should take when filling color outside the bounds of the circle's radius.
57   * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
58   * default, which means the the last keyframe color will be used to fill the
59   * remaining area.
60   * <p>
61   * The colorSpace parameter allows the user to specify in which colorspace
62   * the interpolation should be performed, default sRGB or linearized RGB.
63   *
64   * <p>
65   * The following code demonstrates typical usage of
66   * {@code RadialGradientPaint}, where the center and focus points are
67   * the same:
68   * <p>
69   * <pre>
70   *     Point2D center = new Point2D.Float(50, 50);
71   *     float radius = 25;
72   *     float[] dist = {0.0f, 0.2f, 1.0f};
73   *     Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
74   *     RadialGradientPaint p =
75   *         new RadialGradientPaint(center, radius, dist, colors);
76   * </pre>
77   *
78   * <p>
79   * This image demonstrates the example code above, with default
80   * (centered) focus for each of the three cycle methods:
81   * <p>
82   * <center>
83   * <img src = "doc-files/RadialGradientPaint-1.png">
84   * </center>
85   *
86   * <p>
87   * It is also possible to specify a non-centered focus point, as
88   * in the following code:
89   * <p>
90   * <pre>
91   *     Point2D center = new Point2D.Float(50, 50);
92   *     float radius = 25;
93   *     Point2D focus = new Point2D.Float(40, 40);
94   *     float[] dist = {0.0f, 0.2f, 1.0f};
95   *     Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
96   *     RadialGradientPaint p =
97   *         new RadialGradientPaint(center, radius, focus,
98   *                                 dist, colors,
99   *                                 CycleMethod.NO_CYCLE);
100  * </pre>
101  *
102  * <p>
103  * This image demonstrates the previous example code, with non-centered
104  * focus for each of the three cycle methods:
105  * <p>
106  * <center>
107  * <img src = "doc-files/RadialGradientPaint-2.png">
108  * </center>
109  *
110  * @see java.awt.Paint
111  * @see java.awt.Graphics2D#setPaint
112  * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans
113  * @since 1.6
114  */
115 public final class RadialGradientPaint extends MultipleGradientPaint   {
116 
117     /** Focus point which defines the 0% gradient stop X coordinate. */
118     private final Point2D   focus;
119 
120     /** Center of the circle defining the 100% gradient stop X coordinate. */
121     private final Point2D   center;
122 
123     /** Radius of the outermost circle defining the 100% gradient stop. */
124     private final float radius;
125 
126     /**
127      * Constructs a {@code RadialGradientPaint} with a default
128      * {@code NO_CYCLE} repeating method and {@code SRGB} color space,
129      * using the center as the focus point.
130      *
131      * @param cx the X coordinate in user space of the center point of the 
132      *           circle defining the gradient.  The last color of the
133      *           gradient is mapped to the perimeter of this circle.
134      * @param cy the Y coordinate in user space of the center point of the 
135      *           circle defining the gradient.  The last color of the
136      *           gradient is mapped to the perimeter of this circle.
137      * @param radius the radius of the circle defining the extents of the 
138      *               color gradient   
139      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
140      *                  distribution of colors along the gradient
141      * @param colors array of colors to use in the gradient.  The first color 
142      *               is used at the focus point, the last color around the
143      *               perimeter of the circle.
144      *
145      * @throws NullPointerException
146      * if {@code fractions} array is null,
147      * or {@code colors} array is null
148      * @throws IllegalArgumentException
149      * if {@code radius} is non-positive,
150      * or {@code fractions.length != colors.length},
151      * or {@code colors} is less than 2 in size,
152      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
153      * or the {@code fractions} are not provided in strictly increasing order
154      */
155     public RadialGradientPaint(float cx, float cy, float radius,
156                                float[] fractions, Color  [] colors)
157     {
158         this(cx, cy,
159              radius,
160              cx, cy,
161              fractions,
162              colors,
163              CycleMethod.NO_CYCLE);
164     }    
165     
166     /**
167      * Constructs a {@code RadialGradientPaint} with a default
168      * {@code NO_CYCLE} repeating method and {@code SRGB} color space,
169      * using the center as the focus point.
170      *
171      * @param center the center point, in user space, of the circle defining 
172      *               the gradient
173      * @param radius the radius of the circle defining the extents of the 
174      *               color gradient
175      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
176      *                  distribution of colors along the gradient
177      * @param colors array of colors to use in the gradient.  The first color 
178      *               is used at the focus point, the last color around the
179      *               perimeter of the circle.
180      *
181      * @throws NullPointerException
182      * if {@code center} point is null,
183      * or {@code fractions} array is null,
184      * or {@code colors} array is null
185      * @throws IllegalArgumentException
186      * if {@code radius} is non-positive,
187      * or {@code fractions.length != colors.length},
188      * or {@code colors} is less than 2 in size,
189      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
190      * or the {@code fractions} are not provided in strictly increasing order
191      */
192     public RadialGradientPaint(Point2D   center, float radius,
193                                float[] fractions, Color  [] colors)
194     {
195         this(center,
196              radius,
197              center,        
198              fractions,
199              colors,
200              CycleMethod.NO_CYCLE);
201     }
202 
203     /**
204      * Constructs a {@code RadialGradientPaint} with a default
205      * {@code SRGB} color space, using the center as the focus point.
206      *
207      * @param cx the X coordinate in user space of the center point of the 
208      *           circle defining the gradient.  The last color of the
209      *           gradient is mapped to the perimeter of this circle.
210      * @param cy the Y coordinate in user space of the center point of the 
211      *           circle defining the gradient.  The last color of the
212      *           gradient is mapped to the perimeter of this circle.
213      * @param radius the radius of the circle defining the extents of the 
214      *               color gradient   
215      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
216      *                  distribution of colors along the gradient
217      * @param colors array of colors to use in the gradient.  The first color 
218      *               is used at the focus point, the last color around the
219      *               perimeter of the circle.
220      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
221      *                    or {@code REPEAT}
222      *
223      * @throws NullPointerException
224      * if {@code fractions} array is null,
225      * or {@code colors} array is null,
226      * or {@code cycleMethod} is null
227      * @throws IllegalArgumentException
228      * if {@code radius} is non-positive,
229      * or {@code fractions.length != colors.length},
230      * or {@code colors} is less than 2 in size,
231      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
232      * or the {@code fractions} are not provided in strictly increasing order
233      */
234     public RadialGradientPaint(float cx, float cy, float radius,
235                                float[] fractions, Color  [] colors,
236                                CycleMethod cycleMethod)
237     {
238         this(cx, cy,
239              radius,
240              cx, cy,
241              fractions,
242              colors,
243              cycleMethod);
244     }    
245     
246     /**
247      * Constructs a {@code RadialGradientPaint} with a default
248      * {@code SRGB} color space, using the center as the focus point.
249      *
250      * @param center the center point, in user space, of the circle defining 
251      *               the gradient
252      * @param radius the radius of the circle defining the extents of the 
253      *               color gradient
254      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
255      *                  distribution of colors along the gradient
256      * @param colors array of colors to use in the gradient.  The first color 
257      *               is used at the focus point, the last color around the
258      *               perimeter of the circle.
259      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
260      *                    or {@code REPEAT}
261      *
262      * @throws NullPointerException
263      * if {@code center} point is null,
264      * or {@code fractions} array is null,
265      * or {@code colors} array is null,
266      * or {@code cycleMethod} is null
267      * @throws IllegalArgumentException
268      * if {@code radius} is non-positive,
269      * or {@code fractions.length != colors.length},
270      * or {@code colors} is less than 2 in size,
271      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
272      * or the {@code fractions} are not provided in strictly increasing order
273      */
274     public RadialGradientPaint(Point2D   center, float radius,
275                                float[] fractions, Color  [] colors,
276                                CycleMethod cycleMethod)
277     {
278         this(center,
279              radius,
280              center,        
281              fractions,
282              colors,
283              cycleMethod);
284     }
285 
286     /**
287      * Constructs a {@code RadialGradientPaint} with a default
288      * {@code SRGB} color space.
289      *
290      * @param cx the X coordinate in user space of the center point of the 
291      *           circle defining the gradient.  The last color of the
292      *           gradient is mapped to the perimeter of this circle.
293      * @param cy the Y coordinate in user space of the center point of the 
294      *           circle defining the gradient.  The last color of the
295      *           gradient is mapped to the perimeter of this circle.
296      * @param radius the radius of the circle defining the extents of the 
297      *               color gradient   
298      * @param fx the X coordinate of the point in user space to which the 
299      *           first color is mapped
300      * @param fy the Y coordinate of the point in user space to which the 
301      *           first color is mapped
302      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
303      *                  distribution of colors along the gradient
304      * @param colors array of colors to use in the gradient.  The first color 
305      *               is used at the focus point, the last color around the
306      *               perimeter of the circle.
307      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
308      *                    or {@code REPEAT}
309      *  
310      * @throws NullPointerException
311      * if {@code fractions} array is null,
312      * or {@code colors} array is null,
313      * or {@code cycleMethod} is null
314      * @throws IllegalArgumentException
315      * if {@code radius} is non-positive,
316      * or {@code fractions.length != colors.length},
317      * or {@code colors} is less than 2 in size,
318      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
319      * or the {@code fractions} are not provided in strictly increasing order
320      */
321     public RadialGradientPaint(float cx, float cy, float radius,
322                                float fx, float fy,
323                                float[] fractions, Color  [] colors,
324                                CycleMethod cycleMethod)
325     {
326         this(new Point2D.Float  (cx, cy),
327              radius,
328              new Point2D.Float  (fx, fy),
329              fractions,
330              colors,
331              cycleMethod);
332     }
333     
334     /**
335      * Constructs a {@code RadialGradientPaint} with a default
336      * {@code SRGB} color space.
337      *
338      * @param center the center point, in user space, of the circle defining 
339      *               the gradient.  The last color of the gradient is mapped
340      *               to the perimeter of this circle.
341      * @param radius the radius of the circle defining the extents of the color
342      *               gradient
343      * @param focus the point in user space to which the first color is mapped
344      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
345      *                  distribution of colors along the gradient
346      * @param colors array of colors to use in the gradient. The first color 
347      *               is used at the focus point, the last color around the
348      *               perimeter of the circle.
349      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
350      *                    or {@code REPEAT}
351      *  
352      * @throws NullPointerException
353      * if one of the points is null,
354      * or {@code fractions} array is null,
355      * or {@code colors} array is null,
356      * or {@code cycleMethod} is null
357      * @throws IllegalArgumentException
358      * if {@code radius} is non-positive,
359      * or {@code fractions.length != colors.length},
360      * or {@code colors} is less than 2 in size,
361      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
362      * or the {@code fractions} are not provided in strictly increasing order
363      */
364     public RadialGradientPaint(Point2D   center, float radius,
365                                Point2D   focus,
366                                float[] fractions, Color  [] colors,
367                                CycleMethod cycleMethod)
368     {
369         this(center,
370              radius,
371              focus,
372              fractions,
373              colors,
374              cycleMethod,
375              ColorSpaceType.SRGB,
376              new AffineTransform  ());
377     }
378     
379     /**
380      * Constructs a {@code RadialGradientPaint}.
381      *
382      * @param center the center point in user space of the circle defining the
383      *               gradient.  The last color of the gradient is mapped to
384      *               the perimeter of this circle.
385      * @param radius the radius of the circle defining the extents of the
386      *               color gradient
387      * @param focus the point in user space to which the first color is mapped
388      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
389      *                  distribution of colors along the gradient
390      * @param colors array of colors to use in the gradient.  The first color
391      *               is used at the focus point, the last color around the
392      *               perimeter of the circle.
393      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
394      *                    or {@code REPEAT}
395      * @param colorSpace which color space to use for interpolation, 
396      *                   either {@code SRGB} or {@code LINEAR_RGB}
397      * @param gradientTransform transform to apply to the gradient
398      *
399      * @throws NullPointerException
400      * if one of the points is null,
401      * or {@code fractions} array is null,
402      * or {@code colors} array is null,
403      * or {@code cycleMethod} is null,
404      * or {@code colorSpace} is null,
405      * or {@code gradientTransform} is null
406      * @throws IllegalArgumentException
407      * if {@code radius} is non-positive,
408      * or {@code fractions.length != colors.length},
409      * or {@code colors} is less than 2 in size,
410      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
411      * or the {@code fractions} are not provided in strictly increasing order
412      */
413     public RadialGradientPaint(Point2D   center,
414                                float radius,
415                                Point2D   focus,
416                                float[] fractions, Color  [] colors,
417                                CycleMethod cycleMethod, 
418                                ColorSpaceType colorSpace,
419                                AffineTransform   gradientTransform)
420     {
421         super(fractions, colors, cycleMethod, colorSpace, gradientTransform);
422 
423         // check input arguments
424         if (center == null) {
425             throw new NullPointerException  ("Center point must be non-null");
426         }
427     
428         if (focus == null) {
429             throw new NullPointerException  ("Focus point must be non-null");
430         }
431 
432         if (radius <= 0) {
433             throw new IllegalArgumentException  ("Radius must be greater " +
434                                                "than zero");
435         }
436 
437         // copy parameters
438         this.center = new Point2D.Double  (center.getX(), center.getY());
439         this.focus = new Point2D.Double  (focus.getX(), focus.getY());
440         this.radius = radius;
441     }
442     
443     /**
444      * Constructs a {@code RadialGradientPaint} with a default
445      * {@code SRGB} color space.
446      * The gradient circle of the {@code RadialGradientPaint} is defined
447      * by the given bounding box.
448      * <p>
449      * This constructor is a more convenient way to express the
450      * following (equivalent) code:<br>
451      *
452      * <pre>
453      *     double gw = gradientBounds.getWidth();
454      *     double gh = gradientBounds.getHeight();
455      *     double cx = gradientBounds.getCenterX();
456      *     double cy = gradientBounds.getCenterY();
457      *     Point2D center = new Point2D.Double(cx, cy);
458      *
459      *     AffineTransform gradientTransform = new AffineTransform();
460      *     gradientTransform.translate(cx, cy);
461      *     gradientTransform.scale(gw / 2, gh / 2);
462      *     gradientTransform.translate(-cx, -cy);
463      *
464      *     RadialGradientPaint gp =
465      *         new RadialGradientPaint(center, 1.0f, center,
466      *                                 fractions, colors,
467      *                                 cycleMethod,
468      *                                 ColorSpaceType.SRGB,
469      *                                 gradientTransform);
470      * </pre>
471      *
472      * @param gradientBounds the bounding box, in user space, of the circle
473      *                       defining the outermost extent of the gradient
474      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
475      *                  distribution of colors along the gradient
476      * @param colors array of colors to use in the gradient.  The first color 
477      *               is used at the focus point, the last color around the
478      *               perimeter of the circle.
479      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
480      *                    or {@code REPEAT}
481      *
482      * @throws NullPointerException
483      * if {@code gradientBounds} is null,
484      * or {@code fractions} array is null,
485      * or {@code colors} array is null,
486      * or {@code cycleMethod} is null
487      * @throws IllegalArgumentException
488      * if {@code gradientBounds} is empty,
489      * or {@code fractions.length != colors.length},
490      * or {@code colors} is less than 2 in size,
491      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
492      * or the {@code fractions} are not provided in strictly increasing order
493      */
494     public RadialGradientPaint(Rectangle2D   gradientBounds,
495                                float[] fractions, Color  [] colors,
496                                CycleMethod cycleMethod)
497     {
498         // gradient center/focal point is the center of the bounding box,
499         // radius is set to 1.0, and then we set a scale transform
500         // to achieve an elliptical gradient defined by the bounding box
501         this(new Point2D.Double  (gradientBounds.getCenterX(),
502                                 gradientBounds.getCenterY()),
503              1.0f,
504              new Point2D.Double  (gradientBounds.getCenterX(),
505                                 gradientBounds.getCenterY()),
506              fractions,
507              colors,
508              cycleMethod,
509              ColorSpaceType.SRGB,
510              createGradientTransform(gradientBounds));
511 
512         if (gradientBounds.isEmpty()) {
513             throw new IllegalArgumentException  ("Gradient bounds must be " +
514                                                "non-empty");
515         }
516     }
517 
518     private static AffineTransform   createGradientTransform(Rectangle2D   r) {
519         double cx = r.getCenterX();
520         double cy = r.getCenterY();
521         AffineTransform   xform = AffineTransform.getTranslateInstance(cx, cy);
522         xform.scale(r.getWidth()/2, r.getHeight()/2);
523         xform.translate(-cx, -cy);
524         return xform;
525     }
526 
527     /**
528      * {@inheritDoc}
529      */
530     public PaintContext   createContext(ColorModel   cm,
531                                       Rectangle   deviceBounds,
532                                       Rectangle2D   userBounds,
533                                       AffineTransform   transform,
534                                       RenderingHints   hints)
535     {
536         // avoid modifying the user's transform...
537         transform = new AffineTransform  (transform);
538         // incorporate the gradient transform
539         transform.concatenate(gradientTransform);
540 
541         return new RadialGradientPaintContext  (this, cm,
542                                               deviceBounds, userBounds,
543                                               transform, hints,
544                                               (float)center.getX(),
545                                               (float)center.getY(),
546                                               radius,
547                                               (float)focus.getX(),
548                                               (float)focus.getY(),
549                                               fractions, colors,
550                                               cycleMethod, colorSpace);
551     }
552 
553     /**
554      * Returns a copy of the center point of the radial gradient.
555      *
556      * @return a {@code Point2D} object that is a copy of the center point     
557      */
558     public Point2D   getCenterPoint() {
559         return new Point2D.Double  (center.getX(), center.getY());
560     }
561     
562     /**
563      * Returns a copy of the end point of the gradient axis.
564      *
565      * @return a {@code Point2D} object that is a copy of the focus point     
566      */
567     public Point2D   getFocusPoint() {
568         return new Point2D.Double  (focus.getX(), focus.getY());
569     }
570 
571     /**
572      * Returns the radius of the circle defining the radial gradient.
573      *
574      * @return the radius of the circle defining the radial gradient
575      */
576     public float getRadius() {
577         return radius;
578     }
579 }
580
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags