# Print output for @column tags ?>
public
class
Color
extends Object
java.lang.Object | |
↳ | android.graphics.Color |
The Color
class provides methods for creating, converting and
manipulating colors. Colors have three different representations:
Color
instancesThe section below describe each representation in detail.
Color ints are the most common representation of colors on Android and
have been used since API level 1
.
A color int always defines a color in the ColorSpace.Named#SRGB
color space using 4 components packed in a single 32 bit integer value:
Component | Name | Size | Range |
---|---|---|---|
A | Alpha | 8 bits | \([0..255]\) |
R | Red | 8 bits | \([0..255]\) |
G | Green | 8 bits | \([0..255]\) |
B | Blue | 8 bits | \([0..255]\) |
The components in this table are listed in encoding order (see below), which is why color ints are called ARGB colors.
To avoid confusing color ints with arbitrary integer values, it is a
good practice to annotate them with the @ColorInt
annotation
found in the Android Support Library.
The four components of a color int are encoded in the following way:
int color = (A & 0xff) << 24 | (R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff);
Because of this encoding, color ints can easily be described as an integer
constant in source. For instance, opaque blue is 0xff0000ff
and yellow is 0xffffff00
.
To easily encode color ints, it is recommended to use the static methods
argb(int, int, int, int)
and rgb(int, int, int)
. The second
method omits the alpha component and assumes the color is opaque (alpha is 255).
As a convenience this class also offers methods to encode color ints from components
defined in the \([0..1]\) range: argb(float, float, float, float)
and
rgb(float, float, float)
.
Color longs (defined below) can be easily converted to color ints by invoking
the toArgb(long)
method. This method performs a color space conversion
if needed.
It is also possible to create a color int by invoking the method toArgb()
on a color instance.
The four ARGB components can be individually extracted from a color int using the following expressions:
int A = (color >> 24) & 0xff; // or color >>> 24 int R = (color >> 16) & 0xff; int G = (color >> 8) & 0xff; int B = (color ) & 0xff;
This class offers convenience methods to easily extract these components:
alpha(int)
to extract the alpha componentred(int)
to extract the red componentgreen(int)
to extract the green componentblue(int)
to extract the blue componentColor longs are a representation introduced in
Android O
to store colors in different
ColorSpace
, with more precision than color ints.
A color long always defines a color using 4 components packed in a single
64 bit long value. One of these components is always alpha while the other
three components depend on the color space's ColorSpace.Model
.
The most common color model is the ColorSpace.Model#RGB
model in
which the components represent red, green and blue values.
Component ranges: the ranges defined in the tables
below indicate the ranges that can be encoded in a color long. They do not
represent the actual ranges as they may differ per color space. For instance,
the RGB components of a color in the ColorSpace.Named#DISPLAY_P3
color space use the \([0..1]\) range. Please refer to the documentation of the
various ColorSpace.Named
to find their respective ranges.
Alpha range: while alpha is encoded in a color long using a 10 bit integer (thus using a range of \([0..1023]\)), it is converted to and from \([0..1]\) float values when decoding and encoding color longs.
sRGB color space: for compatibility reasons and ease of
use, color longs encoding ColorSpace.Named#SRGB
colors do not
use the same encoding as other color longs.
Component | Name | Size | Range |
---|---|---|---|
ColorSpace.Model#RGB color model | |||
R | Red | 16 bits | \([-65504.0, 65504.0]\) |
G | Green | 16 bits | \([-65504.0, 65504.0]\) |
B | Blue | 16 bits | \([-65504.0, 65504.0]\) |
A | Alpha | 10 bits | \([0..1023]\) |
Color space | 6 bits | \([0..63]\) | |
ColorSpace.Named#SRGB color space | |||
A | Alpha | 8 bits | \([0..255]\) |
R | Red | 8 bits | \([0..255]\) |
G | Green | 8 bits | \([0..255]\) |
B | Blue | 8 bits | \([0..255]\) |
X | Unused | 32 bits | \(0\) |
ColorSpace.Model#XYZ color model | |||
X | X | 16 bits | \([-65504.0, 65504.0]\) |
Y | Y | 16 bits | \([-65504.0, 65504.0]\) |
Z | Z | 16 bits | \([-65504.0, 65504.0]\) |
A | Alpha | 10 bits | \([0..1023]\) |
Color space | 6 bits | \([0..63]\) | |
ColorSpace.Model#XYZ color model | |||
L | L | 16 bits | \([-65504.0, 65504.0]\) |
a | a | 16 bits | \([-65504.0, 65504.0]\) |
b | b | 16 bits | \([-65504.0, 65504.0]\) |
A | Alpha | 10 bits | \([0..1023]\) |
Color space | 6 bits | \([0..63]\) | |
ColorSpace.Model#CMYK color model | |||
Unsupported |
The components in this table are listed in encoding order (see below), which is why color longs in the RGB model are called RGBA colors (even if this doesn't quite hold for the special case of sRGB colors).
The color long encoding relies on half-precision float values (fp16). If you
wish to know more about the limitations of half-precision float values, please
refer to the documentation of the Half
class.
To avoid confusing color longs with arbitrary long values, it is a
good practice to annotate them with the @ColorLong
annotation
found in the Android Support Library.
Given the complex nature of color longs, it is strongly encouraged to use the various methods provided by this class to encode them.
The most flexible way to encode a color long is to use the method
pack(float, float, float, float, android.graphics.ColorSpace)
. This method allows you
to specify three color components (typically RGB), an alpha component and a
color space. To encode sRGB colors, use pack(float, float, float)
and pack(float, float, float, float)
which are the
equivalent of rgb(int, int, int)
and argb(int, int, int, int)
for color ints. If you simply need to convert a color int into a color long,
use pack(int)
.
It is also possible to create a color long value by invoking the method
pack()
on a color instance.
This class offers convenience methods to easily extract the components of a color long:
alpha(long)
to extract the alpha componentred(long)
to extract the red/X/L componentgreen(long)
to extract the green/Y/a componentblue(long)
to extract the blue/Z/b componentThe values returned by these methods depend on the color space encoded
in the color long. The values are however typically in the \([0..1]\) range
for RGB colors. Please refer to the documentation of the various
ColorSpace.Named
for the exact ranges.
Color instances are a representation introduced in
Android O
to store colors in different
ColorSpace
, with more precision than both color ints and
color longs. Color instances also offer the ability to store more than 4
components if necessary.
Colors instances are immutable and can be created using one of the various
valueOf
methods. For instance:
// sRGB Color opaqueRed = Color.valueOf(0xffff0000); // from a color int Color translucentRed = Color.valueOf(1.0f, 0.0f, 0.0f, 0.5f); // Wide gamut color @ColorLong long p3 = pack(1.0f, 1.0f, 0.0f, 1.0f, colorSpaceP3); Color opaqueYellow = Color.valueOf(p3); // from a color long // CIE L*a*b* color space ColorSpace lab = ColorSpace.get(ColorSpace.Named.LAB); Color green = Color.valueOf(100.0f, -128.0f, 128.0f, 1.0f, lab);
Color instances can be converted to color ints (toArgb()
) or
color longs (pack()
). They also offer easy access to their various
components using the following methods:
alpha()
, returns the alpha component valuered()
, returns the red component value (or first
component value in non-RGB models)green()
, returns the green component value (or second
component value in non-RGB models)blue()
, returns the blue component value (or third
component value in non-RGB models)getComponent(int)
, returns a specific component valuegetComponents()
, returns all component values as an arrayYou can convert colors from one color space to another using
ColorSpace#connect(ColorSpace, ColorSpace)
and its variants. However,
the Color
class provides a few convenience methods to simplify
the process. Here is a brief description of some of them:
convert(android.graphics.ColorSpace)
to convert a color instance in a color
space to a new color instance in a different color spaceconvert(float, float, float, float, android.graphics.ColorSpace, android.graphics.ColorSpace)
to
convert a color from a source color space to a destination color spaceconvert(long, android.graphics.ColorSpace)
to convert a color long from its
built-in color space to a destination color spaceconvert(int, android.graphics.ColorSpace)
to convert a color int from sRGB
to a destination color spacePlease refere to the ColorSpace
documentation for more
information.
The alpha component of a color defines the level of transparency of a color. When the alpha component is 0, the color is completely transparent. When the alpha is component is 1 (in the \([0..1]\) range) or 255 (in the \([0..255]\) range), the color is completely opaque.
The color representations described above do not use pre-multiplied
color components (a pre-multiplied color component is a color component
that has been multiplied by the value of the alpha component).
For instance, the color int representation of opaque red is
0xffff0000
. For semi-transparent (50%) red, the
representation becomes 0x80ff0000
. The equivalent color
instance representations would be (1.0, 0.0, 0.0, 1.0)
and (1.0, 0.0, 0.0, 0.5)
.
Constants | |
---|---|
int |
BLACK
|
int |
BLUE
|
int |
CYAN
|
int |
DKGRAY
|
int |
GRAY
|
int |
GREEN
|
int |
LTGRAY
|
int |
MAGENTA
|
int |
RED
|
int |
TRANSPARENT
|
int |
WHITE
|
int |
YELLOW
|
Public constructors | |
---|---|
Color()
Creates a new color instance set to opaque black in the
|
Public methods | |
---|---|
static
int
|
HSVToColor(float[] hsv)
Convert HSV components to an ARGB color. |
static
int
|
HSVToColor(int alpha, float[] hsv)
Convert HSV components to an ARGB color. |
static
void
|
RGBToHSV(int red, int green, int blue, float[] hsv)
Convert RGB components to HSV. |
static
int
|
alpha(int color)
Return the alpha component of a color int. |
float
|
alpha()
Returns the value of the alpha component in the range \([0..1]\). |
static
float
|
alpha(long color)
Returns the alpha component encoded in the specified color long. |
static
int
|
argb(int alpha, int red, int green, int blue)
Return a color-int from alpha, red, green, blue components. |
static
int
|
argb(float alpha, float red, float green, float blue)
Return a color-int from alpha, red, green, blue float components in the range \([0..1]\). |
static
int
|
blue(int color)
Return the blue component of a color int. |
float
|
blue()
Returns the value of the blue component in the range defined by this
color's color space (see |
static
float
|
blue(long color)
Returns the blue component encoded in the specified color long. |
static
ColorSpace
|
colorSpace(long color)
Returns the color space encoded in the specified color long. |
static
void
|
colorToHSV(int color, float[] hsv)
Convert the ARGB color to its HSV components. |
static
long
|
convert(long color, ColorSpace.Connector connector)
Converts the specified color long from a color space to another using the
specified color space |
Color
|
convert(ColorSpace colorSpace)
Converts this color from its color space to the specified color space. |
static
long
|
convert(int color, ColorSpace colorSpace)
Converts the specified ARGB color int from the |
static
long
|
convert(float r, float g, float b, float a, ColorSpace source, ColorSpace destination)
Converts the specified 3 component color from the source color space to the destination color space. |
static
long
|
convert(float r, float g, float b, float a, ColorSpace.Connector connector)
Converts the specified 3 component color from a color space to another using
the specified color space |
static
long
|
convert(long color, ColorSpace colorSpace)
Converts the specified color long from its color space into the specified destination color space. |
boolean
|
equals(Object o)
Indicates whether some other object is "equal to" this one. |
ColorSpace
|
getColorSpace()
Returns this color's color space. |
float
|
getComponent(int component)
Returns the value of the specified component in the range defined by
this color's color space (see |
int
|
getComponentCount()
Returns the number of components that form a color value according to this color space's color model, plus one extra component for alpha. |
float[]
|
getComponents()
Returns this color's components as a new array. |
float[]
|
getComponents(float[] components)
Copies this color's components in the supplied array. |
ColorSpace.Model
|
getModel()
Returns the color model of this color. |
static
float
|
green(long color)
Returns the green component encoded in the specified color long. |
float
|
green()
Returns the value of the green component in the range defined by this
color's color space (see |
static
int
|
green(int color)
Return the green component of a color int. |
int
|
hashCode()
Returns a hash code value for the object. |
static
boolean
|
isInColorSpace(long color, ColorSpace colorSpace)
Indicates whether the specified color is in the specified color space. |
boolean
|
isSrgb()
Indicates whether this color is in the |
static
boolean
|
isSrgb(long color)
Indicates whether the specified color is in the
|
static
boolean
|
isWideGamut(long color)
Indicates whether the specified color is in a wide-gamut color space. |
boolean
|
isWideGamut()
Indicates whether this color color is in a wide-gamut color space. |
static
float
|
luminance(long color)
Returns the relative luminance of a color. |
static
float
|
luminance(int color)
Returns the relative luminance of a color. |
float
|
luminance()
Returns the relative luminance of this color. |
static
long
|
pack(int color)
Converts the specified ARGB color int to an RGBA color long in the sRGB color space. |
static
long
|
pack(float red, float green, float blue, float alpha)
Packs the sRGB color defined by the specified red, green, blue and alpha component values into an RGBA color long in the sRGB color space. |
static
long
|
pack(float red, float green, float blue, float alpha, ColorSpace colorSpace)
Packs the 3 component color defined by the specified red, green, blue and alpha component values into a color long in the specified color space. |
static
long
|
pack(float red, float green, float blue)
Packs the sRGB color defined by the specified red, green and blue component values into an RGBA color long in the sRGB color space. |
long
|
pack()
Packs this color into a color long. |
static
int
|
parseColor(String colorString)
Parse the color string, and return the corresponding color-int.
|
float
|
red()
Returns the value of the red component in the range defined by this
color's color space (see |
static
float
|
red(long color)
Returns the red component encoded in the specified color long. |
static
int
|
red(int color)
Return the red component of a color int. |
static
int
|
rgb(float red, float green, float blue)
Return a color-int from red, green, blue float components in the range \([0..1]\). |
static
int
|
rgb(int red, int green, int blue)
Return a color-int from red, green, blue components. |
int
|
toArgb()
Converts this color to an ARGB color int. |
static
int
|
toArgb(long color)
Converts the specified color long to an ARGB color int. |
String
|
toString()
Returns a string representation of the object. |
static
Color
|
valueOf(float r, float g, float b)
Creates a new opaque |
static
Color
|
valueOf(float r, float g, float b, float a)
Creates a new |
static
Color
|
valueOf(int color)
Creates a new |
static
Color
|
valueOf(float[] components, ColorSpace colorSpace)
Creates a new |
static
Color
|
valueOf(long color)
Creates a new |
static
Color
|
valueOf(float r, float g, float b, float a, ColorSpace colorSpace)
Creates a new |
Inherited methods | |
---|---|
public static final int BLACK
Constant Value: -16777216 (0xff000000)
public static final int BLUE
Constant Value: -16776961 (0xff0000ff)
public static final int CYAN
Constant Value: -16711681 (0xff00ffff)
public static final int DKGRAY
Constant Value: -12303292 (0xff444444)
public static final int GRAY
Constant Value: -7829368 (0xff888888)
public static final int GREEN
Constant Value: -16711936 (0xff00ff00)
public static final int LTGRAY
Constant Value: -3355444 (0xffcccccc)
public static final int MAGENTA
Constant Value: -65281 (0xffff00ff)
public static final int RED
Constant Value: -65536 (0xffff0000)
public static final int TRANSPARENT
Constant Value: 0 (0x00000000)
public static final int WHITE
Constant Value: -1 (0xffffffff)
public static final int YELLOW
Constant Value: -256 (0xffffff00)
public Color ()
Creates a new color instance set to opaque black in the
ColorSpace.Named#SRGB
color space.
public static int HSVToColor (float[] hsv)
Convert HSV components to an ARGB color. Alpha set to 0xFF.
hsv[0]
is Hue \([0..360[\)hsv[1]
is Saturation \([0...1]\)hsv[2]
is Value \([0...1]\)Parameters | |
---|---|
hsv |
float : 3 element array which holds the input HSV components. |
Returns | |
---|---|
int |
the resulting argb color |
public static int HSVToColor (int alpha, float[] hsv)
Convert HSV components to an ARGB color. The alpha component is passed through unchanged.
hsv[0]
is Hue \([0..360[\)hsv[1]
is Saturation \([0...1]\)hsv[2]
is Value \([0...1]\)Parameters | |
---|---|
alpha |
int : the alpha component of the returned argb color.
Value is between 0 and 255 inclusive |
hsv |
float : 3 element array which holds the input HSV components. |
Returns | |
---|---|
int |
the resulting argb color |
public static void RGBToHSV (int red, int green, int blue, float[] hsv)
Convert RGB components to HSV.
hsv[0]
is Hue \([0..360[\)hsv[1]
is Saturation \([0...1]\)hsv[2]
is Value \([0...1]\)Parameters | |
---|---|
red |
int : red component value \([0..255]\)
Value is between 0 and 255 inclusive |
green |
int : green component value \([0..255]\)
Value is between 0 and 255 inclusive |
blue |
int : blue component value \([0..255]\)
Value is between 0 and 255 inclusive |
hsv |
float : 3 element array which holds the resulting HSV components. |
public static int alpha (int color)
Return the alpha component of a color int. This is the same as saying color >>> 24
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
int |
Value is between 0 and 255 inclusive |
public float alpha ()
Returns the value of the alpha component in the range \([0..1]\).
Calling this method is equivalent to
getComponent(getComponentCount() - 1)
.
Returns | |
---|---|
float |
public static float alpha (long color)
Returns the alpha component encoded in the specified color long. The returned value is always in the range \([0..1]\).
Parameters | |
---|---|
color |
long : The color long whose blue channel to extract |
Returns | |
---|---|
float |
A float value in the range \([0..1]\) |
public static int argb (int alpha, int red, int green, int blue)
Return a color-int from alpha, red, green, blue components. These component values should be \([0..255]\), but there is no range check performed, so if they are out of range, the returned color is undefined.
Parameters | |
---|---|
alpha |
int : Alpha component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
red |
int : Red component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
green |
int : Green component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
blue |
int : Blue component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
Returns | |
---|---|
int |
public static int argb (float alpha, float red, float green, float blue)
Return a color-int from alpha, red, green, blue float components in the range \([0..1]\). If the components are out of range, the returned color is undefined.
Parameters | |
---|---|
alpha |
float : Alpha component \([0..1]\) of the color |
red |
float : Red component \([0..1]\) of the color |
green |
float : Green component \([0..1]\) of the color |
blue |
float : Blue component \([0..1]\) of the color |
Returns | |
---|---|
int |
public static int blue (int color)
Return the blue component of a color int. This is the same as saying color & 0xFF
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
int |
Value is between 0 and 255 inclusive |
public float blue ()
Returns the value of the blue component in the range defined by this
color's color space (see ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
).
If this color's color model is not ColorSpace.Model#RGB
,
calling this method is equivalent to getComponent(2)
.
Returns | |
---|---|
float |
See also:
public static float blue (long color)
Returns the blue component encoded in the specified color long.
The range of the returned value depends on the color space
associated with the specified color. The color space can be
queried by calling colorSpace(long)
.
Parameters | |
---|---|
color |
long : The color long whose blue channel to extract |
Returns | |
---|---|
float |
A float value with a range defined by the specified color's color space |
public static ColorSpace colorSpace (long color)
Returns the color space encoded in the specified color long.
Parameters | |
---|---|
color |
long : The color long whose color space to extract |
Returns | |
---|---|
ColorSpace |
A non-null color space instance |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public static void colorToHSV (int color, float[] hsv)
Convert the ARGB color to its HSV components.
hsv[0]
is Hue \([0..360[\)hsv[1]
is Saturation \([0...1]\)hsv[2]
is Value \([0...1]\)Parameters | |
---|---|
color |
int : the argb color to convert. The alpha component is ignored. |
hsv |
float : 3 element array which holds the resulting HSV components. |
public static long convert (long color, ColorSpace.Connector connector)
Converts the specified color long from a color space to another using the
specified color space ColorSpace.Connector
. The resulting
color is returned as a color long. See the documentation of this class for a
description of the color long format.
When converting several colors in a row, this method is preferable to
convert(long, android.graphics.ColorSpace)
as it prevents a new connector from being
created on every invocation.
The connector's source color space should match the color long's color space.
Parameters | |
---|---|
color |
long : The color long to convert |
connector |
ColorSpace.Connector : A color space connector, cannot be null
This value cannot be null . |
Returns | |
---|---|
long |
A color long in the destination color space of the connector |
public Color convert (ColorSpace colorSpace)
Converts this color from its color space to the specified color space.
The conversion is done using the default rendering intent as specified
by ColorSpace#connect(ColorSpace, ColorSpace)
.
Parameters | |
---|---|
colorSpace |
ColorSpace : The destination color space, cannot be null
This value cannot be null . |
Returns | |
---|---|
Color |
A non-null color instance in the specified color space |
public static long convert (int color, ColorSpace colorSpace)
Converts the specified ARGB color int from the ColorSpace.Named#SRGB
color space into the specified destination color space. The resulting color is
returned as a color long. See the documentation of this class for a description
of the color long format.
Parameters | |
---|---|
color |
int : The sRGB color int to convert |
colorSpace |
ColorSpace : The destination color space
This value cannot be null . |
Returns | |
---|---|
long |
A color long in the destination color space |
public static long convert (float r, float g, float b, float a, ColorSpace source, ColorSpace destination)
Converts the specified 3 component color from the source color space to the destination color space. The resulting color is returned as a color long. See the documentation of this class for a description of the color long format.
When converting multiple colors in a row, it is recommended to use
convert(float, float, float, float, android.graphics.ColorSpace.Connector)
instead to
avoid the creation of a ColorSpace.Connector
on every invocation.
The red, green and blue components must be in the range defined by the
specified color space. See ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
.
Parameters | |
---|---|
r |
float : The red component of the color to convert |
g |
float : The green component of the color to convert |
b |
float : The blue component of the color to convert |
a |
float : The alpha component of the color to convert, in \([0..1]\) |
source |
ColorSpace : The source color space, cannot be null
This value cannot be null . |
destination |
ColorSpace : The destination color space, cannot be null
This value cannot be null . |
Returns | |
---|---|
long |
A color long in the destination color space |
public static long convert (float r, float g, float b, float a, ColorSpace.Connector connector)
Converts the specified 3 component color from a color space to another using
the specified color space ColorSpace.Connector
. The resulting
color is returned as a color long. See the documentation of this class for a
description of the color long format.
When converting several colors in a row, this method is preferable to
convert(float, float, float, float, android.graphics.ColorSpace, android.graphics.ColorSpace)
as
it prevents a new connector from being created on every invocation.
The red, green and blue components must be in the range defined by the
source color space of the connector. See ColorSpace#getMinValue(int)
and ColorSpace#getMaxValue(int)
.
Parameters | |
---|---|
r |
float : The red component of the color to convert |
g |
float : The green component of the color to convert |
b |
float : The blue component of the color to convert |
a |
float : The alpha component of the color to convert, in \([0..1]\) |
connector |
ColorSpace.Connector : A color space connector, cannot be null
This value cannot be null . |
Returns | |
---|---|
long |
A color long in the destination color space of the connector |
public static long convert (long color, ColorSpace colorSpace)
Converts the specified color long from its color space into the specified destination color space. The resulting color is returned as a color long. See the documentation of this class for a description of the color long format.
When converting several colors in a row, it is recommended to use
convert(long, android.graphics.ColorSpace.Connector)
instead to
avoid the creation of a ColorSpace.Connector
on every invocation.
Parameters | |
---|---|
color |
long : The color long to convert |
colorSpace |
ColorSpace : The destination color space
This value cannot be null . |
Returns | |
---|---|
long |
A color long in the destination color space |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public boolean equals (Object o)
Indicates whether some other object is "equal to" this one.
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y)
consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals
method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode
method whenever this method is overridden, so as to maintain the
general contract for the hashCode
method, which states
that equal objects must have equal hash codes.
Parameters | |
---|---|
o |
Object : the reference object with which to compare. |
Returns | |
---|---|
boolean |
true if this object is the same as the obj
argument; false otherwise. |
public ColorSpace getColorSpace ()
Returns this color's color space.
Returns | |
---|---|
ColorSpace |
A non-null instance of ColorSpace |
public float getComponent (int component)
Returns the value of the specified component in the range defined by
this color's color space (see ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
).
If the requested component index is getComponentCount()
,
this method returns the alpha component, always in the range
\([0..1]\).
Parameters | |
---|---|
component |
int : Value is between 0 and 4 inclusive |
Returns | |
---|---|
float |
Throws | |
---|---|
ArrayIndexOutOfBoundsException |
If the specified component index
is < 0 or >= getComponentCount() |
See also:
public int getComponentCount ()
Returns the number of components that form a color value according to this color space's color model, plus one extra component for alpha.
Returns | |
---|---|
int |
The integer 4 or 5 Value is between 4 and 5 inclusive |
public float[] getComponents ()
Returns this color's components as a new array. The last element of the array is always the alpha component.
Returns | |
---|---|
float[] |
A new, non-null array whose size is equal to getComponentCount() |
See also:
public float[] getComponents (float[] components)
Copies this color's components in the supplied array. The last element of the array is always the alpha component.
Parameters | |
---|---|
components |
float : An array of floats whose size must be at least
getComponentCount() , can be null
This value may be null . |
Returns | |
---|---|
float[] |
The array passed as a parameter if not null, or a new array of length
getComponentCount() |
Throws | |
---|---|
IllegalArgumentException |
If the specified array's length is less than
getComponentCount() |
See also:
public ColorSpace.Model getModel ()
Returns the color model of this color.
Returns | |
---|---|
ColorSpace.Model |
A non-null ColorSpace.Model |
public static float green (long color)
Returns the green component encoded in the specified color long.
The range of the returned value depends on the color space
associated with the specified color. The color space can be
queried by calling colorSpace(long)
.
Parameters | |
---|---|
color |
long : The color long whose green channel to extract |
Returns | |
---|---|
float |
A float value with a range defined by the specified color's color space |
public float green ()
Returns the value of the green component in the range defined by this
color's color space (see ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
).
If this color's color model is not ColorSpace.Model#RGB
,
calling this method is equivalent to getComponent(1)
.
Returns | |
---|---|
float |
See also:
public static int green (int color)
Return the green component of a color int. This is the same as saying (color >> 8) & 0xFF
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
int |
Value is between 0 and 255 inclusive |
public int hashCode ()
Returns a hash code value for the object. This method is
supported for the benefit of hash tables such as those provided by
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
Returns | |
---|---|
int |
a hash code value for this object. |
public static boolean isInColorSpace (long color, ColorSpace colorSpace)
Indicates whether the specified color is in the specified color space.
Parameters | |
---|---|
color |
long : The color to test |
colorSpace |
ColorSpace : The color space to test against
This value cannot be null . |
Returns | |
---|---|
boolean |
True if the color is in the specified color space, false otherwise |
See also:
public boolean isSrgb ()
Indicates whether this color is in the ColorSpace.Named#SRGB
color space.
Returns | |
---|---|
boolean |
True if this color is in the sRGB color space, false otherwise |
See also:
public static boolean isSrgb (long color)
Indicates whether the specified color is in the
ColorSpace.Named#SRGB
color space.
Parameters | |
---|---|
color |
long : The color to test |
Returns | |
---|---|
boolean |
True if the color is in the sRGB color space, false otherwise |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public static boolean isWideGamut (long color)
Indicates whether the specified color is in a wide-gamut color space.
See ColorSpace#isWideGamut()
for a definition of a wide-gamut
color space.
Parameters | |
---|---|
color |
long : The color to test |
Returns | |
---|---|
boolean |
True if the color is in a wide-gamut color space, false otherwise |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public boolean isWideGamut ()
Indicates whether this color color is in a wide-gamut color space.
See ColorSpace#isWideGamut()
for a definition of a wide-gamut
color space.
Returns | |
---|---|
boolean |
True if this color is in a wide-gamut color space, false otherwise |
See also:
public static float luminance (long color)
Returns the relative luminance of a color.
Based on the formula for relative luminance defined in WCAG 2.0, W3C Recommendation 11 December 2008.
Parameters | |
---|---|
color |
long |
Returns | |
---|---|
float |
A value between 0 (darkest black) and 1 (lightest white) |
Throws | |
---|---|
IllegalArgumentException |
If the specified color's color space
is unknown or does not use the ColorSpace.Model#RGB color model |
public static float luminance (int color)
Returns the relative luminance of a color.
Assumes sRGB encoding. Based on the formula for relative luminance defined in WCAG 2.0, W3C Recommendation 11 December 2008.
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
float |
a value between 0 (darkest black) and 1 (lightest white) |
public float luminance ()
Returns the relative luminance of this color.
Based on the formula for relative luminance defined in WCAG 2.0, W3C Recommendation 11 December 2008.
Returns | |
---|---|
float |
A value between 0 (darkest black) and 1 (lightest white) |
Throws | |
---|---|
IllegalArgumentException |
If the this color's color space
does not use the ColorSpace.Model#RGB color model |
public static long pack (int color)
Converts the specified ARGB color int to an RGBA color long in the sRGB color space. See the documentation of this class for a description of the color long format.
Parameters | |
---|---|
color |
int : The ARGB color int to convert to an RGBA color long in sRGB |
Returns | |
---|---|
long |
A color long |
public static long pack (float red, float green, float blue, float alpha)
Packs the sRGB color defined by the specified red, green, blue and alpha component values into an RGBA color long in the sRGB color space. See the documentation of this class for a description of the color long format.
Parameters | |
---|---|
red |
float : The red component of the sRGB color to create, in \([0..1]\) |
green |
float : The green component of the sRGB color to create, in \([0..1]\) |
blue |
float : The blue component of the sRGB color to create, in \([0..1]\) |
alpha |
float : The alpha component of the sRGB color to create, in \([0..1]\) |
Returns | |
---|---|
long |
A color long |
public static long pack (float red, float green, float blue, float alpha, ColorSpace colorSpace)
Packs the 3 component color defined by the specified red, green, blue and alpha component values into a color long in the specified color space. See the documentation of this class for a description of the color long format.
The red, green and blue components must be in the range defined by the
specified color space. See ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
.
Parameters | |
---|---|
red |
float : The red component of the color to create |
green |
float : The green component of the color to create |
blue |
float : The blue component of the color to create |
alpha |
float : The alpha component of the color to create, in \([0..1]\) |
colorSpace |
ColorSpace : This value cannot be null . |
Returns | |
---|---|
long |
A color long |
Throws | |
---|---|
IllegalArgumentException |
If the color space's id is ColorSpace#MIN_ID
or if the color space's color model has more than 3 components |
public static long pack (float red, float green, float blue)
Packs the sRGB color defined by the specified red, green and blue component values into an RGBA color long in the sRGB color space. The alpha component is set to 1.0. See the documentation of this class for a description of the color long format.
Parameters | |
---|---|
red |
float : The red component of the sRGB color to create, in \([0..1]\) |
green |
float : The green component of the sRGB color to create, in \([0..1]\) |
blue |
float : The blue component of the sRGB color to create, in \([0..1]\) |
Returns | |
---|---|
long |
A color long |
public long pack ()
Packs this color into a color long. See the documentation of this class for a description of the color long format.
Returns | |
---|---|
long |
A color long |
Throws | |
---|---|
IllegalArgumentException |
If this color's color space has the id
ColorSpace#MIN_ID or if this color has more than 4 components |
public static int parseColor (String colorString)Parse the color string, and return the corresponding color-int. If the string cannot be parsed, throws an IllegalArgumentException exception. Supported formats are:
#RRGGBB
#AARRGGBB
The following names are also accepted: red
, blue
,
green
, black
, white
, gray
,
cyan
, magenta
, yellow
, lightgray
,
darkgray
, grey
, lightgrey
, darkgrey
,
aqua
, fuchsia
, lime
, maroon
,
navy
, olive
, purple
, silver
,
and teal
.
Parameters | |
---|---|
colorString |
String |
Returns | |
---|---|
int |
public float red ()
Returns the value of the red component in the range defined by this
color's color space (see ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
).
If this color's color model is not ColorSpace.Model#RGB
,
calling this method is equivalent to getComponent(0)
.
Returns | |
---|---|
float |
See also:
public static float red (long color)
Returns the red component encoded in the specified color long.
The range of the returned value depends on the color space
associated with the specified color. The color space can be
queried by calling colorSpace(long)
.
Parameters | |
---|---|
color |
long : The color long whose red channel to extract |
Returns | |
---|---|
float |
A float value with a range defined by the specified color's color space |
public static int red (int color)
Return the red component of a color int. This is the same as saying (color >> 16) & 0xFF
Parameters | |
---|---|
color |
int |
Returns | |
---|---|
int |
Value is between 0 and 255 inclusive |
public static int rgb (float red, float green, float blue)
Return a color-int from red, green, blue float components in the range \([0..1]\). The alpha component is implicitly 1.0 (fully opaque). If the components are out of range, the returned color is undefined.
Parameters | |
---|---|
red |
float : Red component \([0..1]\) of the color |
green |
float : Green component \([0..1]\) of the color |
blue |
float : Blue component \([0..1]\) of the color |
Returns | |
---|---|
int |
public static int rgb (int red, int green, int blue)
Return a color-int from red, green, blue components. The alpha component is implicitly 255 (fully opaque). These component values should be \([0..255]\), but there is no range check performed, so if they are out of range, the returned color is undefined.
Parameters | |
---|---|
red |
int : Red component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
green |
int : Green component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
blue |
int : Blue component \([0..255]\) of the color
Value is between 0 and 255 inclusive |
Returns | |
---|---|
int |
public int toArgb ()
Converts this color to an ARGB color int. A color int is always in
the ColorSpace.Named#SRGB
color space. This implies
a color space conversion is applied if needed.
Returns | |
---|---|
int |
An ARGB color in the sRGB color space |
public static int toArgb (long color)
Converts the specified color long to an ARGB color int. A color int is
always in the ColorSpace.Named#SRGB
color space. This implies
a color space conversion is applied if needed.
Parameters | |
---|---|
color |
long |
Returns | |
---|---|
int |
An ARGB color in the sRGB color space |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public String toString ()
Returns a string representation of the object. This method returns a string equal to the value of:
"Color(" + r + ", " + g + ", " + b + ", " + a + ", " + getColorSpace().getName + ')'
For instance, the string representation of opaque black in the sRGB color space is equal to the following value:
Color(0.0, 0.0, 0.0, 1.0, sRGB IEC61966-2.1)
Returns | |
---|---|
String |
A non-null string representation of the object |
public static Color valueOf (float r, float g, float b)
Creates a new opaque Color
in the ColorSpace.Named#SRGB
color space with the specified red, green and blue component values. The component
values must be in the range \([0..1]\).
Parameters | |
---|---|
r |
float : The red component of the opaque sRGB color to create, in \([0..1]\) |
g |
float : The green component of the opaque sRGB color to create, in \([0..1]\) |
b |
float : The blue component of the opaque sRGB color to create, in \([0..1]\) |
Returns | |
---|---|
Color |
A non-null instance of Color |
public static Color valueOf (float r, float g, float b, float a)
Creates a new Color
in the ColorSpace.Named#SRGB
color space with the specified red, green, blue and alpha component values.
The component values must be in the range \([0..1]\).
Parameters | |
---|---|
r |
float : The red component of the sRGB color to create, in \([0..1]\) |
g |
float : The green component of the sRGB color to create, in \([0..1]\) |
b |
float : The blue component of the sRGB color to create, in \([0..1]\) |
a |
float : The alpha component of the sRGB color to create, in \([0..1]\) |
Returns | |
---|---|
Color |
A non-null instance of Color |
public static Color valueOf (int color)
Creates a new Color
instance from an ARGB color int.
The resulting color is in the ColorSpace.Named#SRGB
color space.
Parameters | |
---|---|
color |
int : The ARGB color int to create a Color from |
Returns | |
---|---|
Color |
A non-null instance of Color |
public static Color valueOf (float[] components, ColorSpace colorSpace)
Creates a new Color
in the specified color space with the
specified component values. The range of the components is defined by
ColorSpace#getMinValue(int)
and ColorSpace#getMaxValue(int)
.
The values passed to this method must be in the proper range. The alpha
component is always in the range \([0..1]\).
The length of the array of components must be at least
. The component at index
ColorSpace#getComponentCount()
+ 1ColorSpace#getComponentCount()
is always alpha.
Parameters | |
---|---|
components |
float : The components of the color to create, with alpha as the last component
This value cannot be null . |
colorSpace |
ColorSpace : The color space of the color to create
This value cannot be null . |
Returns | |
---|---|
Color |
A non-null instance of Color |
Throws | |
---|---|
IllegalArgumentException |
If the array of components is smaller than required by the color space |
public static Color valueOf (long color)
Creates a new Color
instance from a color long.
The resulting color is in the same color space as the specified color long.
Parameters | |
---|---|
color |
long : The color long to create a Color from |
Returns | |
---|---|
Color |
A non-null instance of Color |
Throws | |
---|---|
IllegalArgumentException |
If the encoded color space is invalid or unknown |
public static Color valueOf (float r, float g, float b, float a, ColorSpace colorSpace)
Creates a new Color
in the specified color space with the
specified red, green, blue and alpha component values. The range of the
components is defined by ColorSpace#getMinValue(int)
and
ColorSpace#getMaxValue(int)
. The values passed to this method
must be in the proper range.
Parameters | |
---|---|
r |
float : The red component of the color to create |
g |
float : The green component of the color to create |
b |
float : The blue component of the color to create |
a |
float : The alpha component of the color to create, in \([0..1]\) |
colorSpace |
ColorSpace : The color space of the color to create
This value cannot be null . |
Returns | |
---|---|
Color |
A non-null instance of Color |
Throws | |
---|---|
IllegalArgumentException |
If the specified color space uses a color model with more than 3 components |