The Color class contains color information to be used while painting in Canvas. Color supports ColorSpaces with 3 components, plus one for alpha.

Creating

Color can be created with one of these methods:

// from 4 separate [Float] components. Alpha and ColorSpace are optional
val rgbaWhiteFloat = Color(red = 1f, green = 1f, blue = 1f, alpha = 1f,
    ColorSpace.get(ColorSpaces.Srgb))
// from a 32-bit SRGB color integer
val fromIntWhite = Color(android.graphics.Color.WHITE)
val fromLongBlue = Color(0xFF0000FF)
// from SRGB integer component values. Alpha is optional
val rgbaWhiteInt = Color(red = 0xFF, green = 0xFF, blue = 0xFF, alpha = 0xFF)

Representation

A Color 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 encoded sRGB colors do not use the same encoding as other color longs.

| Component | Name        | Size    | Range                 |
|-----------|-------------|---------|-----------------------|
| [RGB][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]`             |
| [SRGB][ColorSpaces.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][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]`             |
| [Lab][ColorSpace.Model.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]`             |

The components in this table are listed in encoding order, 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 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 Float16 class.

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.

Summary

Nested types

Public companion functions
Color
hsl(
    hue: Float,
    saturation: Float,
    lightness: Float,
    alpha: Float,
    colorSpace: Rgb
)

Return a Color from hue, saturation, and lightness (HSL representation).
Cmn
Color
hsv(hue: Float, saturation: Float, value: Float, alpha: Float, colorSpace: Rgb)

Return a Color from hue, saturation, and value (HSV representation).
Cmn

Public companion properties
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color
Cmn
Color

Because Color is an inline class, this represents an unset value without having to box the Color.
Cmn
Color
Cmn
Color
Cmn

Public constructors
Color(value: ULong)
Cmn

Public functions
inline operator Float
Cmn
inline operator Float
Cmn
inline operator Float
Cmn
inline operator Float
Cmn
inline operator ColorSpace
Cmn
Color
convert(colorSpace: ColorSpace)

Converts this color from its color space to the specified color space.
Cmn
Color
copy(alpha: Float, red: Float, green: Float, blue: Float)

Copies the existing color, changing only the provided values.
Cmn
open String

Returns a string representation of the object.
Cmn

Public properties
Float

Returns the value of the alpha component in the range [0..1].
Cmn
Float

Returns the value of the blue component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).
Cmn
ColorSpace

Returns this color's color space.
Cmn
Float

Returns the value of the green component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).
Cmn
Float

Returns the value of the red component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).
Cmn
ULong
Cmn

Extension functions
Color
Color.compositeOver(background: Color)

Composites this color on top of background using the Porter-Duff 'source over' mode.
Cmn
Float

Returns the relative luminance of this color.
Cmn
inline Color
Color.takeOrElse(block: () -> Color)

If this color isSpecified then this is returned, otherwise block is executed and its result is returned.
Cmn
@ColorInt Int

Converts this color to an ARGB color int.
Cmn

Extension properties
Boolean

false when this is Color.Unspecified.
Cmn
Boolean

true when this is Color.Unspecified.
Cmn

Public companion functions

hsl

Cmn
Added in 1.0.0
fun hsl(
    hue: Float,
    saturation: Float,
    lightness: Float,
    alpha: Float = 1.0f,
    colorSpace: Rgb = ColorSpaces.Srgb
): Color

Return a Color from hue, saturation, and lightness (HSL representation).

Parameters
hue: Float

The color value in the range (0..360), where 0 is red, 120 is green, and 240 is blue
saturation: Float

The amount of hue represented in the color in the range (0..1), where 0 has no color and 1 is fully saturated.
lightness: Float

A range of (0..1) where 0 is black, 0.5 is fully colored, and 1 is white.
alpha: Float = 1.0f

Alpha channel to apply to the computed color
colorSpace: Rgb = ColorSpaces.Srgb

The RGB color space used to calculate the Color from the HSL values.

hsv

Cmn
Added in 1.0.0
fun hsv(
    hue: Float,
    saturation: Float,
    value: Float,
    alpha: Float = 1.0f,
    colorSpace: Rgb = ColorSpaces.Srgb
): Color

Return a Color from hue, saturation, and value (HSV representation).

Parameters
hue: Float

The color value in the range (0..360), where 0 is red, 120 is green, and 240 is blue
saturation: Float

The amount of hue represented in the color in the range (0..1), where 0 has no color and 1 is fully saturated.
value: Float

The strength of the color, where 0 is black.
alpha: Float = 1.0f

Alpha channel to apply to the computed color
colorSpace: Rgb = ColorSpaces.Srgb

The RGB color space used to calculate the Color from the HSV values.

Public companion properties

Black

Cmn
Added in 1.0.0
val Black: Color

Blue

Cmn
Added in 1.0.0
val Blue: Color

Cyan

Cmn
Added in 1.0.0
val Cyan: Color

DarkGray

Cmn
Added in 1.0.0
val DarkGray: Color

Gray

Cmn
Added in 1.0.0
val Gray: Color

Green

Cmn
Added in 1.0.0
val Green: Color

LightGray

Cmn
Added in 1.0.0
val LightGray: Color

Magenta

Cmn
Added in 1.0.0
val Magenta: Color

Red

Cmn
Added in 1.0.0
val Red: Color

Transparent

Cmn
Added in 1.0.0
val Transparent: Color

Unspecified

Cmn
Added in 1.0.0
val Unspecified: Color

Because Color is an inline class, this represents an unset value without having to box the Color. It will be treated as Transparent when drawn. A Color can compare with Unspecified for equality or use isUnspecified to check for the unset value or isSpecified for any color that isn't Unspecified.

White

Cmn
Added in 1.0.0
val White: Color

Yellow

Cmn
Added in 1.0.0
val Yellow: Color

Public constructors

Color

Cmn 
Color(value: ULong)

Public functions

component1

Cmn
Added in 1.1.0
inline operator fun component1(): Float

component2

Cmn
Added in 1.1.0
inline operator fun component2(): Float

component3

Cmn
Added in 1.1.0
inline operator fun component3(): Float

component4

Cmn
Added in 1.1.0
inline operator fun component4(): Float

component5

Cmn
Added in 1.1.0
inline operator fun component5(): ColorSpace

convert

Cmn
Added in 1.2.0
fun convert(colorSpace: ColorSpace): Color

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.

Parameters
colorSpace: ColorSpace

The destination color space, cannot be null
Returns
Color

A non-null color instance in the specified color space

copy

Cmn
Added in 1.1.0
fun copy(
    alpha: Float = this.alpha,
    red: Float = this.red,
    green: Float = this.green,
    blue: Float = this.blue
): Color

Copies the existing color, changing only the provided values. The ColorSpace of the returned Color is the same as this colorSpace.

toString

Cmn 
open fun toString(): String

Returns a string representation of the object. This method returns a string equal to the value of:

"Color($r, $g, $b, $a, ${colorSpace.name})"

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 properties

alpha

Cmn
Added in 1.2.0
val alpha: Float

Returns the value of the alpha component in the range [0..1].

See also
red
green
blue

blue

Cmn
Added in 1.2.0
val blue: Float

Returns the value of the blue component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).

If this color's color model is not RGB, calling this is the third component of the ColorSpace.

See also
alpha
red
green

colorSpace

Cmn
Added in 1.2.0
val colorSpace: ColorSpace

Returns this color's color space.

Returns
ColorSpace

A non-null instance of ColorSpace

green

Cmn
Added in 1.2.0
val green: Float

Returns the value of the green component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).

If this color's color model is not RGB, calling this is the second component of the ColorSpace.

See also
alpha
red
blue

red

Cmn
Added in 1.2.0
val red: Float

Returns the value of the red component in the range defined by this color's color space (see ColorSpace.getMinValue and ColorSpace.getMaxValue).

If this color's color model is not RGB, calling this is the first component of the ColorSpace.

See also
alpha
blue
green

value

Cmn
Added in 1.0.0
val value: ULong

Extension functions

compositeOver

Cmn 
fun Color.compositeOver(background: Color): Color

Composites this color on top of background using the Porter-Duff 'source over' mode.

Both this and background must not be pre-multiplied, and the resulting color will also not be pre-multiplied.

The ColorSpace of the result is always the ColorSpace of background.

Returns
Color

the Color representing this composited on top of background, converted to the color space of background.

luminance

Cmn 
fun Color.luminance(): Float

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

If the this color's color space does not use the RGB color model

takeOrElse

Cmn 
inline fun Color.takeOrElse(block: () -> Color): Color

If this color isSpecified then this is returned, otherwise block is executed and its result is returned.

toArgb

Cmn 
fun Color.toArgb(): @ColorInt Int

Converts this color to an ARGB color int. A color int is always in the sRGB color space. This implies a color space conversion is applied if needed.

Returns
@ColorInt Int

An ARGB color in the sRGB color space

Extension properties

isSpecified

Cmn 
val Color.isSpecified: Boolean

false when this is Color.Unspecified.

isUnspecified

Cmn 
val Color.isUnspecified: Boolean

true when this is Color.Unspecified.