001    /* Color.java -- represents a color in Java
002       Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt;
040    
041    import java.awt.color.ColorSpace;
042    import java.awt.geom.AffineTransform;
043    import java.awt.geom.Rectangle2D;
044    import java.awt.image.ColorModel;
045    import java.io.Serializable;
046    
047    /**
048     * This class represents a color value in the AWT system. It uses the sRGB
049     * (standard Red-Green-Blue) system, along with an alpha value ranging from
050     * transparent (0.0f or 0) and opaque (1.0f or 255). The color is not
051     * pre-multiplied by the alpha value an any of the accessor methods. Further
052     * information about sRGB can be found at
053     * <a href="http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html">
054     * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html</a>.
055     *
056     * @author Aaron M. Renn (arenn@urbanophile.com)
057     * @see ColorSpace
058     * @see AlphaComposite
059     * @since 1.0
060     * @status updated to 1.4
061     */
062    public class Color implements Paint, Serializable
063    {
064      /**
065       * Compatible with JDK 1.0+.
066       */
067      private static final long serialVersionUID = 118526816881161077L;
068    
069      /** Constant for the color white: R=255, G=255, B=255. */
070      public static final Color white = new Color(0xffffff, false);
071    
072      /**
073       * Constant for the color white: R=255, G=255, B=255.
074       *
075       * @since 1.4
076       */
077      public static final Color WHITE = white;
078    
079      /** Constant for the color light gray: R=192, G=192, B=192. */
080      public static final Color lightGray = new Color(0xc0c0c0, false);
081    
082      /**
083       * Constant for the color light gray: R=192, G=192, B=192.
084       *
085       * @since 1.4
086       */
087      public static final Color LIGHT_GRAY = lightGray;
088    
089      /** Constant for the color gray: R=128, G=128, B=128. */
090      public static final Color gray = new Color(0x808080, false);
091    
092      /**
093       * Constant for the color gray: R=128, G=128, B=128.
094       *
095       * @since 1.4
096       */
097      public static final Color GRAY = gray;
098    
099      /** Constant for the color dark gray: R=64, G=64, B=64. */
100      public static final Color darkGray = new Color(0x404040, false);
101    
102      /**
103       * Constant for the color dark gray: R=64, G=64, B=64.
104       *
105       * @since 1.4
106       */
107      public static final Color DARK_GRAY = darkGray;
108    
109      /** Constant for the color black: R=0, G=0, B=0. */
110      public static final Color black = new Color(0x000000, false);
111    
112      /**
113       * Constant for the color black: R=0, G=0, B=0.
114       *
115       * @since 1.4
116       */
117      public static final Color BLACK = black;
118    
119      /** Constant for the color red: R=255, G=0, B=0. */
120      public static final Color red = new Color(0xff0000, false);
121    
122      /**
123       * Constant for the color red: R=255, G=0, B=0.
124       *
125       * @since 1.4
126       */
127      public static final Color RED = red;
128    
129      /** Constant for the color pink: R=255, G=175, B=175. */
130      public static final Color pink = new Color(0xffafaf, false);
131    
132      /**
133       * Constant for the color pink: R=255, G=175, B=175.
134       *
135       * @since 1.4
136       */
137      public static final Color PINK = pink;
138    
139      /** Constant for the color orange: R=255, G=200, B=0. */
140      public static final Color orange = new Color(0xffc800, false);
141    
142      /**
143       * Constant for the color orange: R=255, G=200, B=0.
144       *
145       * @since 1.4
146       */
147      public static final Color ORANGE = orange;
148    
149      /** Constant for the color yellow: R=255, G=255, B=0. */
150      public static final Color yellow = new Color(0xffff00, false);
151    
152      /**
153       * Constant for the color yellow: R=255, G=255, B=0.
154       *
155       * @since 1.4
156       */
157      public static final Color YELLOW = yellow;
158    
159      /** Constant for the color green: R=0, G=255, B=0. */
160      public static final Color green = new Color(0x00ff00, false);
161    
162      /**
163       * Constant for the color green: R=0, G=255, B=0.
164       *
165       * @since 1.4
166       */
167      public static final Color GREEN = green;
168    
169      /** Constant for the color magenta: R=255, G=0, B=255. */
170      public static final Color magenta = new Color(0xff00ff, false);
171    
172      /**
173       * Constant for the color magenta: R=255, G=0, B=255.
174       *
175       * @since 1.4
176       */
177      public static final Color MAGENTA = magenta;
178    
179      /** Constant for the color cyan: R=0, G=255, B=255. */
180      public static final Color cyan = new Color(0x00ffff, false);
181    
182      /**
183       * Constant for the color cyan: R=0, G=255, B=255.
184       *
185       * @since 1.4
186       */
187      public static final Color CYAN = cyan;
188    
189      /** Constant for the color blue: R=0, G=0, B=255. */
190      public static final Color blue = new Color(0x0000ff, false);
191    
192      /**
193       * Constant for the color blue: R=0, G=0, B=255.
194       *
195       * @since 1.4
196       */
197      public static final Color BLUE = blue;
198    
199      /** Internal mask for red. */
200      private static final int RED_MASK = 255 << 16;
201    
202      /** Internal mask for green. */
203      private static final int GREEN_MASK = 255 << 8;
204    
205      /** Internal mask for blue. */
206      private static final int BLUE_MASK = 255;
207    
208      /** Internal mask for alpha. Package visible for use in subclass. */
209      static final int ALPHA_MASK = 255 << 24;
210    
211      /** Amount to scale a color by when brightening or darkening. */
212      private static final float BRIGHT_SCALE = 0.7f;
213    
214      /**
215       * The color value, in sRGB. Note that the actual color may be more
216       * precise if frgbvalue or fvalue is non-null. This class stores alpha, red,
217       * green, and blue, each 0-255, packed in an int. However, the subclass
218       * SystemColor stores an index into an array. Therefore, for serial
219       * compatibility (and because of poor design on Sun's part), this value
220       * cannot be used directly; instead you must use <code>getRGB()</code>.
221       *
222       * @see #getRGB()
223       * @serial the value of the color, whether an RGB literal or array index
224       */
225      final int value;
226    
227      /**
228       * The color value, in sRGB. This may be null if the color was constructed
229       * with ints; and it does not include alpha. This stores red, green, and
230       * blue, in the range 0.0f - 1.0f.
231       *
232       * @see #getRGBColorComponents(float[])
233       * @see #getRGBComponents(float[])
234       * @serial the rgb components of the value
235       * @since 1.2
236       */
237      private float[] frgbvalue;
238    
239      /**
240       * The color value, in the native ColorSpace components. This may be null
241       * if the color was constructed with ints or in the sRGB color space; and
242       * it does not include alpha.
243       *
244       * @see #getRGBColorComponents(float[])
245       * @see #getRGBComponents(float[])
246       * @serial the original color space components of the color
247       * @since 1.2
248       */
249      private float[] fvalue;
250    
251      /**
252       * The alpha value. This is in the range 0.0f - 1.0f, but is invalid if
253       * deserialized as 0.0 when frgbvalue is null.
254       *
255       * @see #getRGBComponents(float[])
256       * @see #getComponents(float[])
257       * @serial the alpha component of this color
258       * @since 1.2
259       */
260      private final float falpha;
261    
262      /**
263       * The ColorSpace. Null means the default sRGB space.
264       *
265       * @see #getColor(String)
266       * @see #getColorSpace()
267       * @see #getColorComponents(float[])
268       * @serial the color space for this color
269       * @since 1.2
270       */
271      private final ColorSpace cs;
272    
273      /**
274       * The paint context for this solid color. Package visible for use in
275       * subclass.
276       */
277      transient ColorPaintContext context;
278    
279      /**
280       * Initializes a new instance of <code>Color</code> using the specified
281       * red, green, and blue values, which must be given as integers in the
282       * range of 0-255. Alpha will default to 255 (opaque). When drawing to
283       * screen, the actual color may be adjusted to the best match of hardware
284       * capabilities.
285       *
286       * @param red the red component of the RGB value
287       * @param green the green component of the RGB value
288       * @param blue the blue component of the RGB value
289       * @throws IllegalArgumentException if the values are out of range 0-255
290       * @see #getRed()
291       * @see #getGreen()
292       * @see #getBlue()
293       * @see #getRGB()
294       * @see #Color(int, int, int, int)
295       */
296      public Color(int red, int green, int blue)
297      {
298        this(red, green, blue, 255);
299      }
300    
301      /**
302       * Initializes a new instance of <code>Color</code> using the specified
303       * red, green, blue, and alpha values, which must be given as integers in
304       * the range of 0-255. When drawing to screen, the actual color may be
305       * adjusted to the best match of hardware capabilities.
306       *
307       * @param red the red component of the RGB value
308       * @param green the green component of the RGB value
309       * @param blue the blue component of the RGB value
310       * @param alpha the alpha value of the color
311       * @throws IllegalArgumentException if the values are out of range 0-255
312       * @see #getRed()
313       * @see #getGreen()
314       * @see #getBlue()
315       * @see #getAlpha()
316       * @see #getRGB()
317       */
318      public Color(int red, int green, int blue, int alpha)
319      {
320        if ((red & 255) != red || (green & 255) != green || (blue & 255) != blue
321            || (alpha & 255) != alpha)
322          throw new IllegalArgumentException("Bad RGB values"
323                                            +" red=0x"+Integer.toHexString(red)
324                                            +" green=0x"+Integer.toHexString(green)
325                                            +" blue=0x"+Integer.toHexString(blue)
326                                            +" alpha=0x"+Integer.toHexString(alpha)  );
327    
328        value = (alpha << 24) | (red << 16) | (green << 8) | blue;
329        falpha = 1;
330        cs = null;
331      }
332    
333      /**
334       * Initializes a new instance of <code>Color</code> using the specified
335       * RGB value. The blue value is in bits 0-7, green in bits 8-15, and
336       * red in bits 16-23. The other bits are ignored. The alpha value is set
337       * to 255 (opaque). When drawing to screen, the actual color may be
338       * adjusted to the best match of hardware capabilities.
339       *
340       * @param value the RGB value
341       * @see ColorModel#getRGBdefault()
342       * @see #getRed()
343       * @see #getGreen()
344       * @see #getBlue()
345       * @see #getRGB()
346       * @see #Color(int, boolean)
347       */
348      public Color(int value)
349      {
350        this(value, false);
351      }
352    
353      /**
354       * Initializes a new instance of <code>Color</code> using the specified
355       * RGB value. The blue value is in bits 0-7, green in bits 8-15, and
356       * red in bits 16-23. The alpha value is in bits 24-31, unless hasalpha
357       * is false, in which case alpha is set to 255. When drawing to screen, the
358       * actual color may be adjusted to the best match of hardware capabilities.
359       *
360       * @param value the RGB value
361       * @param hasalpha true if value includes the alpha
362       * @see ColorModel#getRGBdefault()
363       * @see #getRed()
364       * @see #getGreen()
365       * @see #getBlue()
366       * @see #getAlpha()
367       * @see #getRGB()
368       */
369      public Color(int value, boolean hasalpha)
370      {
371        // Note: SystemColor calls this constructor, setting falpha to 0; but
372        // code in getRGBComponents correctly reports falpha as 1.0 to the user
373        // for all instances of SystemColor since frgbvalue is left null here.
374        if (hasalpha)
375          falpha = ((value & ALPHA_MASK) >> 24) / 255f;
376        else
377          {
378            value |= ALPHA_MASK;
379            falpha = 1;
380          }
381        this.value = value;
382        cs = null;
383      }
384    
385      /**
386       * Initializes a new instance of <code>Color</code> using the specified
387       * RGB values. These must be in the range of 0.0-1.0. Alpha is assigned
388       * the value of 1.0 (opaque). When drawing to screen, the actual color may
389       * be adjusted to the best match of hardware capabilities.
390       *
391       * @param red the red component of the RGB value
392       * @param green the green component of the RGB value
393       * @param blue the blue component of the RGB value
394       * @throws IllegalArgumentException tf the values are out of range 0.0f-1.0f
395       * @see #getRed()
396       * @see #getGreen()
397       * @see #getBlue()
398       * @see #getRGB()
399       * @see #Color(float, float, float, float)
400       */
401      public Color(float red, float green, float blue)
402      {
403        this(red, green, blue, 1.0f);
404      }
405    
406      /**
407       * Initializes a new instance of <code>Color</code> using the specified
408       * RGB and alpha values. These must be in the range of 0.0-1.0. When drawing
409       * to screen, the actual color may be adjusted to the best match of
410       * hardware capabilities.
411       *
412       * @param red the red component of the RGB value
413       * @param green the green component of the RGB value
414       * @param blue the blue component of the RGB value
415       * @param alpha the alpha value of the color
416       * @throws IllegalArgumentException tf the values are out of range 0.0f-1.0f
417       * @see #getRed()
418       * @see #getGreen()
419       * @see #getBlue()
420       * @see #getAlpha()
421       * @see #getRGB()
422       */
423      public Color(float red, float green, float blue, float alpha)
424      {
425        value = convert(red, green, blue, alpha);
426        frgbvalue = new float[] {red, green, blue};
427        falpha = alpha;
428        cs = null;
429      }
430    
431      /**
432       * Creates a color in the given ColorSpace with the specified alpha. The
433       * array must be non-null and have enough elements for the color space
434       * (for example, RGB requires 3 elements, CMYK requires 4). When drawing
435       * to screen, the actual color may be adjusted to the best match of
436       * hardware capabilities.
437       *
438       * @param space the color space of components
439       * @param components the color components, except alpha
440       * @param alpha the alpha value of the color
441       * @throws NullPointerException if cpsace or components is null
442       * @throws ArrayIndexOutOfBoundsException if components is too small
443       * @throws IllegalArgumentException if alpha or any component is out of range
444       * @see #getComponents(float[])
445       * @see #getColorComponents(float[])
446       */
447      public Color(ColorSpace space, float[] components, float alpha)
448      {
449        frgbvalue = space.toRGB(components);
450        fvalue = components;
451        falpha = alpha;
452        cs = space;
453        value = convert(frgbvalue[0], frgbvalue[1], frgbvalue[2], alpha);
454      }
455    
456      /**
457       * Returns the red value for this color, as an integer in the range 0-255
458       * in the sRGB color space.
459       *
460       * @return the red value for this color
461       * @see #getRGB()
462       */
463      public int getRed()
464      {
465        // Do not inline getRGB() to value, because of SystemColor.
466        return (getRGB() & RED_MASK) >> 16;
467      }
468    
469      /**
470       * Returns the green value for this color, as an integer in the range 0-255
471       * in the sRGB color space.
472       *
473       * @return the green value for this color
474       * @see #getRGB()
475       */
476      public int getGreen()
477      {
478        // Do not inline getRGB() to value, because of SystemColor.
479        return (getRGB() & GREEN_MASK) >> 8;
480      }
481    
482      /**
483       * Returns the blue value for this color, as an integer in the range 0-255
484       * in the sRGB color space.
485       *
486       * @return the blue value for this color
487       * @see #getRGB()
488       */
489      public int getBlue()
490      {
491        // Do not inline getRGB() to value, because of SystemColor.
492        return getRGB() & BLUE_MASK;
493      }
494    
495      /**
496       * Returns the alpha value for this color, as an integer in the range 0-255.
497       *
498       * @return the alpha value for this color
499       * @see #getRGB()
500       */
501      public int getAlpha()
502      {
503        // Do not inline getRGB() to value, because of SystemColor.
504        return (getRGB() & ALPHA_MASK) >>> 24;
505      }
506    
507      /**
508       * Returns the RGB value for this color, in the sRGB color space. The blue
509       * value will be in bits 0-7, green in 8-15, red in 16-23, and alpha value in
510       * 24-31.
511       *
512       * @return the RGB value for this color
513       * @see ColorModel#getRGBdefault()
514       * @see #getRed()
515       * @see #getGreen()
516       * @see #getBlue()
517       * @see #getAlpha()
518       */
519      public int getRGB()
520      {
521        return value;
522      }
523    
524      /**
525       * Returns a brighter version of this color. This is done by increasing the
526       * RGB values by an arbitrary scale factor. The new color is opaque (an
527       * alpha of 255). Note that this method and the <code>darker()</code>
528       * method are not necessarily inverses.
529       *
530       * @return a brighter version of this color
531       * @see #darker()
532       */
533      public Color brighter()
534      {
535        // Do not inline getRGB() to this.value, because of SystemColor.
536        int value = getRGB();
537        int[] hues = new int[3];
538        hues[0] = (value & RED_MASK) >> 16;
539        hues[1] = (value & GREEN_MASK) >> 8;
540        hues[2] = value & BLUE_MASK;
541      
542        // (0,0,0) is a special case.
543        if (hues[0] == 0 && hues[1] == 0 && hues[2] ==0)
544          {
545            hues[0] = 3;
546            hues[1] = 3;
547            hues[2] = 3;
548          }
549        else
550          {                    
551            for (int index = 0; index < 3; index++)
552              {
553                
554                if (hues[index] > 2)
555                  hues[index] = (int) Math.min(255, hues[index]/0.7f);
556                if (hues[index] == 1 || hues[index] == 2)
557                  hues[index] = 4;
558              }
559          }
560    
561        return new Color(hues[0], hues[1], hues[2], 255);
562      }
563    
564      /**
565       * Returns a darker version of this color. This is done by decreasing the
566       * RGB values by an arbitrary scale factor. The new color is opaque (an
567       * alpha of 255). Note that this method and the <code>brighter()</code>
568       * method are not necessarily inverses.
569       *
570       * @return a darker version of this color
571       * @see #brighter()
572       */
573      public Color darker()
574      {
575        // Do not inline getRGB() to this.value, because of SystemColor.
576        int value = getRGB();
577        return new Color((int) (((value & RED_MASK) >> 16) * BRIGHT_SCALE),
578                         (int) (((value & GREEN_MASK) >> 8) * BRIGHT_SCALE),
579                         (int) ((value & BLUE_MASK) * BRIGHT_SCALE), 255);
580      }
581    
582      /**
583       * Returns a hash value for this color. This is simply the color in 8-bit
584       * precision, in the format 0xAARRGGBB (alpha, red, green, blue).
585       *
586       * @return a hash value for this color
587       */
588      public int hashCode()
589      {
590        return value;
591      }
592    
593      /**
594       * Tests this object for equality against the specified object.  This will
595       * be true if and only if the specified object is an instance of
596       * <code>Color</code> and has the same 8-bit integer red, green, and blue
597       * values as this object. Note that two colors may be slightly different
598       * as float values, but round to the same integer values. Also note that
599       * this does not accurately compare SystemColors, since that class does
600       * not store its internal data in RGB format like regular colors.
601       *
602       * @param obj the object to compare to
603       * @return true if the specified object is semantically equal to this one
604       */
605      public boolean equals(Object obj)
606      {
607        return obj instanceof Color && ((Color) obj).value == value;
608      }
609    
610      /**
611       * Returns a string representation of this object. Subclasses may return
612       * any desired format, except for null, but this implementation returns
613       * <code>getClass().getName() + "[r=" + getRed() + ",g=" + getGreen()
614       * + ",b=" + getBlue() + ']'</code>.
615       *
616       * @return a string representation of this object
617       */
618      public String toString()
619      {
620        return getClass().getName() + "[r=" + ((value & RED_MASK) >> 16)
621          + ",g=" + ((value & GREEN_MASK) >> 8) + ",b=" + (value & BLUE_MASK)
622          + ']';
623      }
624    
625      /**
626       * Converts the specified string to a number, using Integer.decode, and
627       * creates a new instance of <code>Color</code> from the value. The alpha
628       * value will be 255 (opaque).
629       *
630       * @param str the numeric color string
631       * @return a new instance of <code>Color</code> for the string
632       * @throws NumberFormatException if the string cannot be parsed
633       * @throws NullPointerException if the string is null
634       * @see Integer#decode(String)
635       * @see #Color(int)
636       * @since 1.1
637       */
638      public static Color decode(String str)
639      {
640        return new Color(Integer.decode(str).intValue(), false);
641      }
642    
643      /**
644       * Returns a new instance of <code>Color</code> from the value of the
645       * system property named by the specified string.  If the property does not
646       * exist, or cannot be parsed, then <code>null</code> will be returned.
647       *
648       * @param prop the system property to retrieve
649       * @throws SecurityException if getting the property is denied
650       * @see #getColor(String, Color)
651       * @see Integer#getInteger(String)
652       */
653      public static Color getColor(String prop)
654      {
655        return getColor(prop, null);
656      }
657    
658      /**
659       * Returns a new instance of <code>Color</code> from the value of the
660       * system property named by the specified string.  If the property does
661       * not exist, or cannot be parsed, then the default color value will be
662       * returned.
663       *
664       * @param prop the system property to retrieve
665       * @param defcolor the default color
666       * @throws SecurityException if getting the property is denied
667       * @see Integer#getInteger(String)
668       */
669      public static Color getColor(String prop, Color defcolor)
670      {
671        Integer val = Integer.getInteger(prop, null);
672        return val == null ? defcolor
673          : new Color(val.intValue(), false);
674      }
675    
676      /**
677       * Returns a new instance of <code>Color</code> from the value of the
678       * system property named by the specified string.  If the property does
679       * not exist, or cannot be parsed, then the default RGB value will be
680       * used to create a return value.
681       *
682       * @param prop the system property to retrieve
683       * @param defrgb the default RGB value
684       * @throws SecurityException if getting the property is denied
685       * @see #getColor(String, Color)
686       * @see Integer#getInteger(String, int)
687       */
688      public static Color getColor(String prop, int defrgb)
689      {
690        Color c = getColor(prop, null);
691        return c == null ? new Color(defrgb, false) : c;
692      }
693    
694      /**
695       * Converts from the HSB (hue, saturation, brightness) color model to the
696       * RGB (red, green, blue) color model. The hue may be any floating point;
697       * it's fractional portion is used to select the angle in the HSB model.
698       * The saturation and brightness must be between 0 and 1. The result is
699       * suitable for creating an RGB color with the one-argument constructor.
700       *
701       * @param hue the hue of the HSB value
702       * @param saturation the saturation of the HSB value
703       * @param brightness the brightness of the HSB value
704       * @return the RGB value
705       * @see #getRGB()
706       * @see #Color(int)
707       * @see ColorModel#getRGBdefault()
708       */
709      public static int HSBtoRGB(float hue, float saturation, float brightness)
710      {
711        if (saturation == 0)
712          return convert(brightness, brightness, brightness, 0);
713        if (saturation < 0 || saturation > 1 || brightness < 0 || brightness > 1)
714          throw new IllegalArgumentException();
715        hue = hue - (float) Math.floor(hue);
716        int i = (int) (6 * hue);
717        float f = 6 * hue - i;
718        float p = brightness * (1 - saturation);
719        float q = brightness * (1 - saturation * f);
720        float t = brightness * (1 - saturation * (1 - f));
721        switch (i)
722          {
723          case 0:
724            return convert(brightness, t, p, 0);
725          case 1:
726            return convert(q, brightness, p, 0);
727          case 2:
728            return convert(p, brightness, t, 0);
729          case 3:
730            return convert(p, q, brightness, 0);
731          case 4:
732            return convert(t, p, brightness, 0);
733          case 5:
734            return convert(brightness, p, q, 0);
735          default:
736            throw new InternalError("impossible");
737          }
738      }
739    
740      /**
741       * Converts from the RGB (red, green, blue) color model to the HSB (hue,
742       * saturation, brightness) color model. If the array is null, a new one
743       * is created, otherwise it is recycled. The results will be in the range
744       * 0.0-1.0 if the inputs are in the range 0-255.
745       *
746       * @param red the red part of the RGB value
747       * @param green the green part of the RGB value
748       * @param blue the blue part of the RGB value
749       * @param array an array for the result (at least 3 elements), or null
750       * @return the array containing HSB value
751       * @throws ArrayIndexOutOfBoundsException of array is too small
752       * @see #getRGB()
753       * @see #Color(int)
754       * @see ColorModel#getRGBdefault()
755       */
756      public static float[] RGBtoHSB(int red, int green, int blue, float array[])
757      {
758        if (array == null)
759          array = new float[3];
760        // Calculate brightness.
761        int min;
762        int max;
763        if (red < green)
764          {
765            min = red;
766            max = green;
767          }
768        else
769          {
770            min = green;
771            max = red;
772          }
773        if (blue > max)
774          max = blue;
775        else if (blue < min)
776          min = blue;
777        array[2] = max / 255f;
778        // Calculate saturation.
779        if (max == 0)
780          array[1] = 0;
781        else
782          array[1] = ((float) (max - min)) / ((float) max);
783        // Calculate hue.
784        if (array[1] == 0)
785          array[0] = 0;
786        else
787          {
788            float delta = (max - min) * 6;
789            if (red == max)
790              array[0] = (green - blue) / delta;
791            else if (green == max)
792              array[0] = 1f / 3 + (blue - red) / delta;
793            else
794              array[0] = 2f / 3 + (red - green) / delta;
795            if (array[0] < 0)
796              array[0]++;
797          }
798        return array;
799      }
800    
801      /**
802       * Returns a new instance of <code>Color</code> based on the specified
803       * HSB values. The hue may be any floating point; it's fractional portion
804       * is used to select the angle in the HSB model. The saturation and
805       * brightness must be between 0 and 1.
806       *
807       * @param hue the hue of the HSB value
808       * @param saturation the saturation of the HSB value
809       * @param brightness the brightness of the HSB value
810       * @return the new <code>Color</code> object
811       */
812      public static Color getHSBColor(float hue, float saturation,
813                                      float brightness)
814      {
815        return new Color(HSBtoRGB(hue, saturation, brightness), false);
816      }
817    
818      /**
819       * Returns a float array with the red, green, and blue components, and the
820       * alpha value, in the default sRGB space, with values in the range 0.0-1.0.
821       * If the array is null, a new one is created, otherwise it is recycled.
822       *
823       * @param array the array to put results into (at least 4 elements), or null
824       * @return the RGB components and alpha value
825       * @throws ArrayIndexOutOfBoundsException if array is too small
826       */
827      public float[] getRGBComponents(float[] array)
828      {
829        if (array == null)
830          array = new float[4];
831        getRGBColorComponents(array);
832        // Stupid serialization issues require this check.
833        array[3] = (falpha == 0 && frgbvalue == null
834                    ? ((getRGB() & ALPHA_MASK) >> 24) / 255f : falpha);
835        return array;
836      }
837    
838      /**
839       * Returns a float array with the red, green, and blue components, in the
840       * default sRGB space, with values in the range 0.0-1.0. If the array is
841       * null, a new one is created, otherwise it is recycled.
842       *
843       * @param array the array to put results into (at least 3 elements), or null
844       * @return the RGB components
845       * @throws ArrayIndexOutOfBoundsException if array is too small
846       */
847      public float[] getRGBColorComponents(float[] array)
848      {
849        if (array == null)
850          array = new float[3];
851        else if (array == frgbvalue)
852          return array; // Optimization for getColorComponents(float[]).
853        if (frgbvalue == null)
854          {
855            // Do not inline getRGB() to this.value, because of SystemColor.
856            int value = getRGB();
857            frgbvalue = new float[] { ((value & RED_MASK) >> 16) / 255f,
858                                      ((value & GREEN_MASK) >> 8) / 255f,
859                                      (value & BLUE_MASK) / 255f };
860          }
861        array[0] = frgbvalue[0];
862        array[1] = frgbvalue[1];
863        array[2] = frgbvalue[2];
864        return array;
865      }
866    
867      /**
868       * Returns a float array containing the color and alpha components of this
869       * color in the ColorSpace it was created with (the constructors which do
870       * not take a ColorSpace parameter use a default sRGB ColorSpace). If the
871       * array is null, a new one is created, otherwise it is recycled, and must
872       * have at least one more position than components used in the color space.
873       *
874       * @param array the array to put results into, or null
875       * @return the original color space components and alpha value
876       * @throws ArrayIndexOutOfBoundsException if array is too small
877       */
878      public float[] getComponents(float[] array)
879      {
880        int numComponents = cs == null ? 3 : cs.getNumComponents();
881        if (array == null)
882          array = new float[1 + numComponents];
883        getColorComponents(array);
884        // Stupid serialization issues require this check.
885        array[numComponents] = (falpha == 0 && frgbvalue == null
886                                ? ((getRGB() & ALPHA_MASK) >> 24) / 255f : falpha);
887        return array;
888      }
889    
890      /**
891       * Returns a float array containing the color components of this color in
892       * the ColorSpace it was created with (the constructors which do not take
893       * a ColorSpace parameter use a default sRGB ColorSpace). If the array is
894       * null, a new one is created, otherwise it is recycled, and must have at
895       * least as many positions as used in the color space.
896       *
897       * @param array the array to put results into, or null
898       * @return the original color space components
899       * @throws ArrayIndexOutOfBoundsException if array is too small
900       */
901      public float[] getColorComponents(float[] array)
902      {
903        int numComponents = cs == null ? 3 : cs.getNumComponents();
904        if (array == null)
905          array = new float[numComponents];
906        if (fvalue == null) // If fvalue is null, cs should be null too.
907          fvalue = getRGBColorComponents(frgbvalue);
908        System.arraycopy(fvalue, 0, array, 0, numComponents);
909        return array;
910      }
911    
912      /**
913       * Returns a float array containing the color and alpha components of this
914       * color in the given ColorSpace. If the array is null, a new one is
915       * created, otherwise it is recycled, and must have at least one more
916       * position than components used in the color space.
917       *
918       * @param space the color space to translate to
919       * @param array the array to put results into, or null
920       * @return the color space components and alpha value
921       * @throws ArrayIndexOutOfBoundsException if array is too small
922       * @throws NullPointerException if space is null
923       */
924      public float[] getComponents(ColorSpace space, float[] array)
925      {
926        int numComponents = space.getNumComponents();
927        if (array == null)
928          array = new float[1 + numComponents];
929        getColorComponents(space, array);
930        // Stupid serialization issues require this check.
931        array[numComponents] = (falpha == 0 && frgbvalue == null
932                                ? ((getRGB() & ALPHA_MASK) >> 24) / 255f : falpha);
933        return array;
934      }
935    
936      /**
937       * Returns a float array containing the color components of this color in
938       * the given ColorSpace. If the array is null, a new one is created,
939       * otherwise it is recycled, and must have at least as many positions as
940       * used in the color space.
941       *
942       * @param space the color space to translate to
943       * @return the color space components
944       * @throws ArrayIndexOutOfBoundsException if array is too small
945       * @throws NullPointerException if space is null
946       */
947      public float[] getColorComponents(ColorSpace space, float[] array)
948      {
949        float[] components = space.fromRGB(getRGBColorComponents(frgbvalue));
950        if (array == null)
951          return components;
952        System.arraycopy(components, 0, array, 0, components.length);
953        return array;
954      }
955    
956      /**
957       * Returns the color space of this color. Except for the constructor which
958       * takes a ColorSpace argument, this will be an implementation of
959       * ColorSpace.CS_sRGB.
960       *
961       * @return the color space
962       */
963      public ColorSpace getColorSpace()
964      {
965        return cs == null ? ColorSpace.getInstance(ColorSpace.CS_sRGB) : cs;
966      }
967    
968      /**
969       * Returns a paint context, used for filling areas of a raster scan with
970       * this color. Since the color is constant across the entire rectangle, and
971       * since it is always in sRGB space, this implementation returns the same
972       * object, regardless of the parameters. Subclasses, however, may have a
973       * mutable result.
974       *
975       * @param cm the requested color model
976       * @param deviceBounds the bounding box in device coordinates, ignored
977       * @param userBounds the bounding box in user coordinates, ignored
978       * @param xform the bounds transformation, ignored
979       * @param hints any rendering hints, ignored
980       * @return a context for painting this solid color
981       */
982      public PaintContext createContext(ColorModel cm, Rectangle deviceBounds,
983                                        Rectangle2D userBounds,
984                                        AffineTransform xform,
985                                        RenderingHints hints)
986      {
987        if (context == null || !context.getColorModel().equals(cm))
988          context = new ColorPaintContext(cm,value);
989        return context;
990      }
991    
992      /**
993       * Returns the transparency level of this color.
994       *
995       * @return one of {@link #OPAQUE}, {@link #BITMASK}, or {@link #TRANSLUCENT}
996       */
997      public int getTransparency()
998      {
999        // Do not inline getRGB() to this.value, because of SystemColor.
1000        int alpha = getRGB() & ALPHA_MASK;
1001        return alpha == (255 << 24) ? OPAQUE : alpha == 0 ? BITMASK : TRANSLUCENT;
1002      }
1003    
1004      /**
1005       * Converts float values to integer value.
1006       *
1007       * @param red the red value
1008       * @param green the green value
1009       * @param blue the blue value
1010       * @param alpha the alpha value
1011       * @return the integer value made of 8-bit sections
1012       * @throws IllegalArgumentException if parameters are out of range 0.0-1.0
1013       */
1014      private static int convert(float red, float green, float blue, float alpha)
1015      {
1016        if (red < 0 || red > 1 || green < 0 || green > 1 || blue < 0 || blue > 1
1017            || alpha < 0 || alpha > 1)
1018          throw new IllegalArgumentException("Bad RGB values");
1019        int redval = Math.round(255 * red);
1020        int greenval = Math.round(255 * green);
1021        int blueval = Math.round(255 * blue);
1022        int alphaval = Math.round(255 * alpha);
1023        return (alphaval << 24) | (redval << 16) | (greenval << 8) | blueval;
1024      }
1025    } // class Color