Color

Kotlin |Java

open class Color

kotlin.Any
↳	android.graphics.Color

The Color class provides methods for creating, converting and manipulating colors. Colors have three different representations:

Color ints, the most common representation
Color longs
Color instances

The section below describe each representation in detail.

Color ints

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 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.

Usage in code

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.

Encoding

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.

Decoding

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 component
red(int) to extract the red component
green(int) to extract the green component
blue(int) to extract the blue component

Color longs

Color longs are a representation introduced in Android O to store colors in different color spaces, 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 color model. The most common color model is the 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 Display P3 color space use the \([0..1]\) range. Please refer to the documentation of the various color spaces 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 sRGB colors do not use the same encoding as other color longs.

Component	Name	Size	Range
`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]\)
`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\)
`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]\)
`Lab` 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]\)
`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.

Usage in code

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.

Encoding

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.

Decoding

This class offers convenience methods to easily extract the components of a color long:

alpha(long) to extract the alpha component
red(long) to extract the red/X/L component
green(long) to extract the green/Y/a component
blue(long) to extract the blue/Z/b component

The 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 color spaces for the exact ranges.

Color instances

Color instances are a representation introduced in Android O to store colors in different color spaces, 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 value
red(), 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 value
getComponents(), returns all component values as an array

Color space conversions

You 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 space
convert(float,float,float,float,android.graphics.ColorSpace,android.graphics.ColorSpace) to convert a color from a source color space to a destination color space
convert(long,android.graphics.ColorSpace) to convert a color long from its built-in color space to a destination color space
convert(int,android.graphics.ColorSpace) to convert a color int from sRGB to a destination color space

Please refere to the ColorSpace documentation for more information.

Alpha and transparency

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).

Summary

Constants
static Int	`BLACK`
static Int	`BLUE`
static Int	`CYAN`
static Int	`DKGRAY`
static Int	`GRAY`
static Int	`GREEN`
static Int	`LTGRAY`
static Int	`MAGENTA`
static Int	`RED`
static Int	`TRANSPARENT`
static Int	`WHITE`
static Int	`YELLOW`

Public constructors
`Color()` Creates a new color instance set to opaque black in the `sRGB` color space.

Public methods
open static Int	`HSVToColor(hsv: FloatArray!)` Convert HSV components to an ARGB color.
open static Int	`HSVToColor(alpha: Int, hsv: FloatArray!)` Convert HSV components to an ARGB color.
open static Unit	`RGBToHSV(red: Int, green: Int, blue: Int, hsv: FloatArray!)` Convert RGB components to HSV.
open Float	`alpha()` Returns the value of the alpha component in the range \([0..1]\).
open static Float	`alpha(color: Long)` Returns the alpha component encoded in the specified color long.
open static Int	`alpha(color: Int)` Return the alpha component of a color int.
open static Int	`argb(alpha: Int, red: Int, green: Int, blue: Int)` Return a color-int from alpha, red, green, blue components.
open static Int	`argb(alpha: Float, red: Float, green: Float, blue: Float)` Return a color-int from alpha, red, green, blue float components in the range \([0..1]\).
open 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)`).
open static Float	`blue(color: Long)` Returns the blue component encoded in the specified color long.
open static Int	`blue(color: Int)` Return the blue component of a color int.
open static ColorSpace	`colorSpace(color: Long)` Returns the color space encoded in the specified color long.
open static Unit	`colorToHSV(color: Int, hsv: FloatArray!)` Convert the ARGB color to its HSV components.
open Color	`convert(colorSpace: ColorSpace)` Converts this color from its color space to the specified color space.
open static Long	`convert(color: Int, colorSpace: ColorSpace)` Converts the specified ARGB color int from the `sRGB` color space into the specified destination color space.
open static Long	`convert(color: Long, colorSpace: ColorSpace)` Converts the specified color long from its color space into the specified destination color space.
open static Long	`convert(r: Float, g: Float, b: Float, a: Float, source: ColorSpace, destination: ColorSpace)` Converts the specified 3 component color from the source color space to the destination color space.
open static Long	`convert(color: Long, connector: ColorSpace.Connector)` Converts the specified color long from a color space to another using the specified color space `connector`.
open static Long	`convert(r: Float, g: Float, b: Float, a: Float, connector: ColorSpace.Connector)` Converts the specified 3 component color from a color space to another using the specified color space `connector`.
open Boolean	`equals(other: Any?)`
open ColorSpace	`getColorSpace()` Returns this color's color space.
open Float	`getComponent(component: Int)` 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)`).
open 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.
open FloatArray	`getComponents()` Returns this color's components as a new array.
open FloatArray	`getComponents(components: FloatArray?)` Copies this color's components in the supplied array.
open ColorSpace.Model!	`getModel()` Returns the color model of this color.
open 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)`).
open static Float	`green(color: Long)` Returns the green component encoded in the specified color long.
open static Int	`green(color: Int)` Return the green component of a color int.
open Int	`hashCode()`
open static Boolean	`isInColorSpace(color: Long, colorSpace: ColorSpace)` Indicates whether the specified color is in the specified color space.
open Boolean	`isSrgb()` Indicates whether this color is in the `sRGB` color space.
open static Boolean	`isSrgb(color: Long)` Indicates whether the specified color is in the `sRGB` color space.
open Boolean	`isWideGamut()` Indicates whether this color color is in a wide-gamut color space.
open static Boolean	`isWideGamut(color: Long)` Indicates whether the specified color is in a wide-gamut color space.
open Float	`luminance()` Returns the relative luminance of this color.
open static Float	`luminance(color: Long)` Returns the relative luminance of a color.
open static Float	`luminance(color: Int)` Returns the relative luminance of a color.
open Long	`pack()` Packs this color into a color long.
open static Long	`pack(color: Int)` Converts the specified ARGB color int to an RGBA color long in the sRGB color space.
open static Long	`pack(red: Float, green: Float, blue: Float)` Packs the sRGB color defined by the specified red, green and blue component values into an RGBA color long in the sRGB color space.
open static Long	`pack(red: Float, green: Float, blue: Float, alpha: Float)` 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.
open static Long	`pack(red: Float, green: Float, blue: Float, alpha: Float, 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.
open static Int	`parseColor(colorString: String!)` Parse the color string, and return the corresponding color-int.
open 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)`).
open static Float	`red(color: Long)` Returns the red component encoded in the specified color long.
open static Int	`red(color: Int)` Return the red component of a color int.
open static Int	`rgb(red: Int, green: Int, blue: Int)` Return a color-int from red, green, blue components.
open static Int	`rgb(red: Float, green: Float, blue: Float)` Return a color-int from red, green, blue float components in the range \([0..1]\).
open Int	`toArgb()` Converts this color to an ARGB color int.
open static Int	`toArgb(color: Long)` Converts the specified color long to an ARGB color int.
open String	`toString()` Returns a string representation of the object.
open static Color	`valueOf(color: Int)` Creates a new `Color` instance from an ARGB color int.
open static Color	`valueOf(color: Long)` Creates a new `Color` instance from a color long.
open static Color	`valueOf(r: Float, g: Float, b: Float)` Creates a new opaque `Color` in the `sRGB` color space with the specified red, green and blue component values.
open static Color	`valueOf(r: Float, g: Float, b: Float, a: Float)` Creates a new `Color` in the `sRGB` color space with the specified red, green, blue and alpha component values.
open static Color	`valueOf(r: Float, g: Float, b: Float, a: Float, colorSpace: ColorSpace)` Creates a new `Color` in the specified color space with the specified red, green, blue and alpha component values.
open static Color	`valueOf(components: FloatArray, colorSpace: ColorSpace)` Creates a new `Color` in the specified color space with the specified component values.

Constants

BLACK

Added in API level 1

static val BLACK: Int

Value: -16777216

BLUE

Added in API level 1

static val BLUE: Int

Value: -16776961

CYAN

Added in API level 1

static val CYAN: Int

Value: -16711681

DKGRAY

Added in API level 1

static val DKGRAY: Int

Value: -12303292

GRAY

Added in API level 1

static val GRAY: Int

Value: -7829368

GREEN

Added in API level 1

static val GREEN: Int

Value: -16711936

LTGRAY

Added in API level 1

static val LTGRAY: Int

Value: -3355444

MAGENTA

Added in API level 1

static val MAGENTA: Int

Value: -65281

RED

Added in API level 1

static val RED: Int

Value: -65536

TRANSPARENT

Added in API level 1

static val TRANSPARENT: Int

Value: 0

WHITE

Added in API level 1

static val WHITE: Int

Value: -1

YELLOW

Added in API level 1

static val YELLOW: Int

Value: -256

Public constructors

Color

Added in API level 1

Color()

Creates a new color instance set to opaque black in the sRGB color space.

See Also

#valueOf(float, float, float)
#valueOf(float, float, float, float)
#valueOf(float, float, float, float, ColorSpace)
#valueOf(float[], ColorSpace)
#valueOf(int)
#valueOf(long)

Public methods

HSVToColor

Added in API level 1

open static fun HSVToColor(hsv: FloatArray!): Int

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]\)

If hsv values are out of range, they are pinned.

Parameters
`hsv`	FloatArray!: 3 element array which holds the input HSV components.

Return
`Int`	the resulting argb color

HSVToColor

Added in API level 1

open static fun HSVToColor(
    alpha: Int, 
    hsv: FloatArray!
): Int

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]\)

If hsv values are out of range, they are pinned.

Parameters
`alpha`	Int: the alpha component of the returned argb color. Value is between 0 and 255 inclusive
`hsv`	FloatArray!: 3 element array which holds the input HSV components.

Return
`Int`	the resulting argb color

RGBToHSV

Added in API level 1

open static fun RGBToHSV(
    red: Int, 
    green: Int, 
    blue: Int, 
    hsv: FloatArray!
): Unit

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`	FloatArray!: 3 element array which holds the resulting HSV components.

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

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

Parameters
`color`	Int: the argb color to convert. The alpha component is ignored.
`hsv`	FloatArray!: 3 element array which holds the resulting HSV components.

Parameters
`color`	Int: The sRGB color int to convert
`colorSpace`	ColorSpace: The destination color space This value cannot be `null`.

Parameters
`color`	Long: The color long to convert
`colorSpace`	ColorSpace: The destination color space This value cannot be `null`.

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
`destination`	ColorSpace: The destination color space, cannot be null

Parameters
`color`	Long: The color long to convert
`connector`	ColorSpace.Connector: A color space connector, cannot be null

Parameters
`color`	Long: The color to test
`colorSpace`	ColorSpace: The color space to test against This value cannot be `null`.

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]\)

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]\)

Parameters
`components`	FloatArray: 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`.

Color

Color ints

Usage in code

Encoding

Decoding

Color longs

Usage in code

Encoding

Decoding

Color instances

Color space conversions

Alpha and transparency

Summary

Constants

BLACK

BLUE

CYAN

DKGRAY

GRAY

GREEN

LTGRAY

MAGENTA

RED

TRANSPARENT

WHITE

YELLOW

Public constructors

Color

Public methods

HSVToColor

HSVToColor

RGBToHSV

alpha

alpha

alpha

argb

argb

blue

blue

blue

colorSpace

colorToHSV

convert

convert

convert

convert

convert

convert

equals

getColorSpace

getComponent

getComponentCount

getComponents

getComponents

getModel

green

green

green

hashCode

isInColorSpace

isSrgb

isSrgb

isWideGamut

isWideGamut

luminance

luminance

luminance

pack

pack

pack

pack

pack

parseColor

red

red

red

rgb

rgb

toArgb

toArgb