RadialGradientPaint


1   /*
2   
3      Copyright 2001-2003  The Apache Software Foundation 
4   
5      Licensed under the Apache License, Version 2.0 (the "License");
6      you may not use this file except in compliance with the License.
7      You may obtain a copy of the License at
8   
9          http://www.apache.org/licenses/LICENSE-2.0
10  
11     Unless required by applicable law or agreed to in writing, software
12     distributed under the License is distributed on an "AS IS" BASIS,
13     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14     See the License for the specific language governing permissions and
15     limitations under the License.
16  
17   */
18  package org.apache.batik.ext.awt;
19  
20  import java.awt.Color  ;
21  import java.awt.PaintContext  ;
22  import java.awt.Rectangle  ;
23  import java.awt.RenderingHints  ;
24  import java.awt.geom.AffineTransform  ;
25  import java.awt.geom.NoninvertibleTransformException  ;
26  import java.awt.geom.Point2D  ;
27  import java.awt.geom.Rectangle2D  ;
28  import java.awt.image.ColorModel  ;
29  
30  /**
31   * <p>
32   * This class provides a way to fill a shape with a circular radial color 
33   * gradient pattern. The user may specify 2 or more gradient colors, and this 
34   * paint will provide an interpolation between each color.
35   * <p>
36   *
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   *
42   * <p>
43   * This paint will map the first color of the gradient to a focus point within
44   * the circle, and the last color to the perimeter of the circle, interpolating
45   * smoothly for any inbetween colors specified by the user.  Any line drawn 
46   * from the focus point to the circumference will span the all the gradient 
47   * colors.  By default the focus is set to be the center of the circle.
48   *
49   * <p>
50   * Specifying a focus point outside of the circle's radius will result in the 
51   * focus being set to the intersection point of the focus-center line and the 
52   * perimenter of the circle.
53   * <p>
54   *
55   * Specifying a cycle method allows the user to control the painting behavior 
56   * outside of the bounds of the circle's radius.  See LinearGradientPaint for 
57   * more details.
58   *
59   * <p>
60   * The following code demonstrates typical usage of RadialGradientPaint:
61   * <p>
62   * <code>
63   * Point2D center = new Point2D.Float(0, 0);<br>
64   * float radius = 20;
65   * float[] dist = {0.0, 0.2, 1.0};<br>
66   * Color[] colors = {Color.red, Color.white, Color.blue};<br>
67   * RadialGradientPaint p = new RadialGradientPaint(center, radius, 
68   * dist, colors);
69   * </code>
70   *
71   * <p> In the event that the user does not set the first keyframe value equal
72   * to 0 and the last keyframe value equal to 1, keyframes will be created at
73   * these positions and the first and last colors will be replicated there.
74   * So, if a user specifies the following arrays to construct a gradient:<br>
75   * {Color.blue, Color.red}, {.3, .7}<br>
76   * this will be converted to a gradient with the following keyframes:
77   * {Color.blue, Color.blue, Color.red, Color.red}, {0, .3, .7, 1}
78   *
79   *
80   * <p>
81   * <img src = "radial.jpg">
82   * <p>
83   * This image demonstrates a radial gradient with NO_CYCLE and default focus.
84   * <p>
85   *
86   * <img src = "radial2.jpg">
87   * <p>
88   * This image demonstrates a radial gradient with NO_CYCLE and non-centered 
89   * focus.
90   * <p>
91   * 
92   * <img src = "radial3.jpg">
93   * <p>
94   * This image demonstrates a radial gradient with REFLECT and non-centered 
95   * focus.
96   *
97   * @author  Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans
98   * @author <a HREF="mailto:vincent.hardy@eng.sun.com">Vincent Hardy</a>
99   * @version $Id: RadialGradientPaint.java,v 1.6 2004/08/18 07:13:41 vhardy Exp $
100  *
101  */
102 
103 public final class RadialGradientPaint extends MultipleGradientPaint {
104 
105     /** Focus point which defines the 0% gradient stop x coordinate. */
106     private Point2D   focus;
107 
108     /** Center of the circle defining the 100% gradient stop x coordinate. */
109     private Point2D   center;
110 
111     /** Radius of the outermost circle defining the 100% gradient stop. */
112     private float radius;
113 
114     /**
115      * <p>
116      *
117      * Constructs a <code>RadialGradientPaint</code>, using the center as the 
118      * focus point.
119      *
120      * @param cx the x coordinate in user space of the center point of the 
121      * circle defining the gradient.  The last color of the gradient is mapped
122      * to the perimeter of this circle
123      *
124      * @param cy the y coordinate in user space of the center point of the 
125      * circle defining the gradient.  The last color of the gradient is mapped
126      * to the perimeter of this circle
127      *
128      * @param radius the radius of the circle defining the extents of the 
129      * color gradient   
130      *
131      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
132      * distribution of colors along the gradient
133      *
134      * @param colors array of colors to use in the gradient. The first color 
135      * is used at the focus point, the last color around the perimeter of the 
136      * circle.
137      *        
138      *
139      * @throws IllegalArgumentException  
140      *         if fractions.length != colors.length, or if colors is less 
141      *         than 2 in size, or if radius < 0
142      *
143      *
144      */
145     public RadialGradientPaint(float cx, float cy, float radius,
146                                float[] fractions, Color  [] colors) {
147         this(cx, cy,
148              radius,
149              cx, cy,
150              fractions,
151              colors);
152     }    
153     
154     /**
155      * <p>
156      *
157      * Constructs a <code>RadialGradientPaint</code>, using the center as the 
158      * focus point.
159      *
160      * @param center the center point, in user space, of the circle defining 
161      * the gradient
162      *
163      * @param radius the radius of the circle defining the extents of the 
164      * color gradient
165      *
166      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
167      * distribution of colors along the gradient
168      *
169      * @param colors array of colors to use in the gradient. The first color 
170      * is used at the focus point, the last color around the perimeter of the 
171      * circle.
172      *   
173      * @throws NullPointerException if center point is null
174      *
175      * @throws IllegalArgumentException  
176      *         if fractions.length != colors.length, or if colors is less 
177      *         than 2 in size, or if radius < 0
178      *
179      *
180      */
181     public RadialGradientPaint(Point2D   center, float radius,
182                                float[] fractions, Color  [] colors) {
183         this(center,
184              radius,
185              center,        
186              fractions,
187              colors);
188     }
189 
190     /**
191      * <p>
192      *
193      * Constructs a <code>RadialGradientPaint</code>.
194      *
195      * @param cx the x coordinate in user space of the center point of the 
196      * circle defining the gradient.  The last color of the gradient is mapped
197      * to the perimeter of this circle
198      *
199      * @param cy the y coordinate in user space of the center point of the 
200      * circle defining the gradient.  The last color of the gradient is mapped
201      * to the perimeter of this circle
202      *
203      * @param radius the radius of the circle defining the extents of the 
204      * color gradient
205      *
206      * @param fx the x coordinate of the point in user space to which the 
207      * first color is mapped
208      *
209      * @param fy the y coordinate of the point in user space to which the 
210      * first color is mapped
211      *
212      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
213      * distribution of colors along the gradient
214      *
215      * @param colors array of colors to use in the gradient. The first color 
216      * is used at the focus point, the last color around the perimeter of the 
217      * circle.
218      *  
219      * @throws IllegalArgumentException  
220      *         if fractions.length != colors.length, or if colors is less 
221      *         than 2 in size, or if radius < 0
222      *
223      *
224      */
225     public RadialGradientPaint(float cx, float cy, float radius,
226                                float fx, float fy,
227                                float[] fractions, Color  [] colors) {
228         this(new Point2D.Float  (cx, cy),
229              radius,
230              new Point2D.Float  (fx, fy),
231              fractions,
232              colors,
233              NO_CYCLE,
234              SRGB);
235     }
236     
237     /**
238      * <p>
239      *
240      * Constructs a <code>RadialGradientPaint</code>.
241      *
242      * @param center the center point, in user space, of the circle defining 
243      * the gradient. The last color of the gradient is mapped to the perimeter
244      * of this circle
245      *
246      * @param radius the radius of the circle defining the extents of the color
247      * gradient
248      *
249      * @param focus the point, in user space, to which the first color is 
250      * mapped    
251      *
252      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
253      * distribution of colors along the gradient
254      *
255      * @param colors array of colors to use in the gradient. The first color 
256      * is used at the focus point, the last color around the perimeter of the
257      * circle.
258      *   
259      * @throws NullPointerException if one of the points is null
260      *
261      * @throws IllegalArgumentException  
262      *         if fractions.length != colors.length, or if colors is less 
263      *         than 2 in size, or if radius < 0
264      *
265      */
266     public RadialGradientPaint(Point2D   center, float radius,
267                                Point2D   focus,
268                                float[] fractions, Color  [] colors) {
269         this(center,
270              radius,
271              focus,
272              fractions,
273              colors,
274              NO_CYCLE,
275              SRGB); 
276     }
277     
278     /**
279      * <p>
280      *
281      * Constructs a <code>RadialGradientPaint</code>.
282      *
283      * @param center the center point in user space of the circle defining the
284      * gradient. The last color of the gradient is mapped to the perimeter of 
285      * this circle
286      *
287      * @param radius the radius of the circle defining the extents of the color
288      * gradient
289      *
290      * @param focus the point in user space to which the first color is mapped
291      *   
292      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
293      * distribution of colors along the gradient
294      *
295      * @param colors array of colors to use in the gradient. The first color is
296      * used at the focus point, the last color around the perimeter of the 
297      * circle.
298      *
299      * @param cycleMethod either NO_CYCLE, REFLECT, or REPEAT
300      *
301      * @param colorSpace which colorspace to use for interpolation, 
302      * either SRGB or LINEAR_RGB
303      *   
304      * @throws NullPointerException if one of the points is null
305      *
306      * @throws IllegalArgumentException 
307      *         if fractions.length != colors.length, or if colors is less 
308      *         than 2 in size, or if radius < 0
309      *
310      */
311     public RadialGradientPaint(Point2D   center, float radius,
312                                Point2D   focus,
313                                float[] fractions, Color  [] colors,
314                                CycleMethodEnum cycleMethod, 
315                                ColorSpaceEnum colorSpace) {
316         this(center,
317              radius,
318              focus,
319              fractions,
320              colors,
321              cycleMethod,
322              colorSpace,
323              new AffineTransform  ());
324     }
325 
326     /**
327      * <p>
328      *
329      * Constructs a <code>RadialGradientPaint</code>.
330      *
331      * @param center the center point in user space of the circle defining the
332      * gradient.  The last color of the gradient is mapped to the perimeter of
333      * this circle
334      *
335      * @param radius the radius of the circle defining the extents of the color
336      * gradient. 
337      *
338      * @param focus the point in user space to which the first color is mapped
339      *
340      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
341      * distribution of colors along the gradient
342      *
343      * @param colors array of colors to use in the gradient. The first color is
344      * used at the focus point, the last color around the perimeter of the 
345      * circle.
346      *
347      * @param cycleMethod either NO_CYCLE, REFLECT, or REPEAT
348      *
349      * @param colorSpace which colorspace to use for interpolation, 
350      * either SRGB or LINEAR_RGB          
351      *
352      * @param gradientTransform transform to apply to the gradient
353      *
354      * @throws NullPointerException if one of the points is null, 
355      * or gradientTransform is null
356      *
357      * @throws IllegalArgumentException 
358      *         if fractions.length != colors.length, or if colors is less 
359      *         than 2 in size, or if radius < 0
360      *
361      */
362     public RadialGradientPaint(Point2D   center,
363                                float radius,
364                                Point2D   focus,
365                                float[] fractions,  Color  [] colors,
366                                CycleMethodEnum cycleMethod, 
367                                ColorSpaceEnum colorSpace,
368                                AffineTransform   gradientTransform){
369         super(fractions, colors, cycleMethod, colorSpace, gradientTransform);
370 
371         // Check input arguments
372         if (center == null) {
373             throw new NullPointerException  ("Center point should not be null.");
374         }
375     
376         if (focus == null) {
377             throw new NullPointerException  ("Focus point should not be null.");
378         }
379 
380         if (radius <= 0) {
381             throw new IllegalArgumentException  ("radius should be greater than zero");
382         }
383 
384         //copy parameters
385         this.center = (Point2D  )center.clone();
386         this.focus = (Point2D  )focus.clone();
387         this.radius = radius;
388     }
389     
390     /**
391      * <p>
392      *
393      * Constructs a <code>RadialGradientPaint</code>, the gradient circle is 
394      * defined by a bounding box.
395      *    
396      * @param gradientBounds the bounding box, in user space, of the circle 
397      * defining outermost extent of the gradient.
398      *
399      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
400      * distribution of colors along the gradient
401      *
402      * @param colors array of colors to use in the gradient. The first color 
403      * is used at the focus point, the last color around the perimeter of the 
404      * circle.
405      *
406      * @throws NullPointerException if the gradientBounds is null
407      *
408      * @throws IllegalArgumentException 
409      *         if fractions.length != colors.length, or if colors is less 
410      *         than 2 in size, or if radius < 0
411      *
412      */    
413     public RadialGradientPaint(Rectangle2D   gradientBounds,
414                                float[] fractions,  Color  [] colors) {
415 
416         //calculate center point and radius based on bounding box coordinates.
417         this((float)gradientBounds.getX() +
418              ( (float)gradientBounds.getWidth() / 2),
419          
420              (float)gradientBounds.getY() +
421              ( (float)gradientBounds.getWidth() / 2),
422          
423              (float)gradientBounds.getWidth() / 2, 
424              fractions, colors);
425     }
426 
427 
428     /** <p>
429      * Creates and returns a PaintContext used to generate the color pattern,
430      * for use by the internal rendering engine.
431      *
432      * @param cm {@link ColorModel} that receives
433      * the <code>Paint</code> data. This is used only as a hint.
434      *
435      * @param deviceBounds the device space bounding box of the 
436      * graphics primitive being rendered
437      *
438      * @param userBounds the user space bounding box of the 
439      * graphics primitive being rendered
440      *
441      * @param transform the {@link AffineTransform} from user
442      * space into device space
443      *
444      * @param hints the hints that the context object uses to choose
445      * between rendering alternatives
446      *
447      * @return the {@link PaintContext} that generates color patterns.
448      *
449      * @throws IllegalArgumentException if the transform is not invertible
450      *
451      * @see PaintContext
452      */
453     public PaintContext   createContext(ColorModel   cm,
454                                       Rectangle   deviceBounds,
455                                       Rectangle2D   userBounds,
456                                       AffineTransform   transform,
457                                       RenderingHints   hints) {
458         // Can't modify the transform passed in...
459         transform = new AffineTransform  (transform);
460         // incorporate the gradient transform
461         transform.concatenate(gradientTransform);
462 
463         try{
464             return new RadialGradientPaintContext
465                 (cm, deviceBounds, userBounds, transform, hints,
466                  (float)center.getX(), (float)center.getY(), radius,
467                  (float)focus.getX(), (float)focus.getY(),
468                  fractions, colors, cycleMethod, colorSpace);               
469         }
470     
471         catch(NoninvertibleTransformException   e){
472             throw new IllegalArgumentException  ("transform should be " +
473                                                "invertible");
474         }
475     }
476 
477     /**
478      * Returns a copy of the center point of the radial gradient.
479      * @return a {@link Point2D} object that is a copy of the center point     
480      */
481     public Point2D   getCenterPoint() {
482         return new Point2D.Double  (center.getX(), center.getY());
483     }
484     
485     /** Returns a copy of the end point of the gradient axis.
486      * @return a {@link Point2D} object that is a copy of the focus point     
487      */
488     public Point2D   getFocusPoint() {
489         return new Point2D.Double  (focus.getX(), focus.getY());
490     }
491 
492     /** Returns the radius of the circle defining the radial gradient.
493      * @return the radius of the circle defining the radial gradient
494      */
495     public float getRadius() {
496         return radius;
497     }
498     
499 }
500 
501
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags