{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

Color

value public final class Color


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 |
| R | Red | 8 bits | `[0..255]` |
| G | Green | 8 bits | `[0..255]` |
| B | Blue | 8 bits | `[0..255]` |
| A | Alpha | 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 (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 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 static class Color.Companion

Public constructors

Public methods

final float
final float
final float
final float
final @NonNull ColorSpace
final @NonNull Color
convert(@NonNull ColorSpace colorSpace)

Converts this color from its color space to the specified color space.

final @NonNull Color
copy(float alpha, float red, float green, float blue)

Copies the existing color, changing only the provided values.

final float

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

final float

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

final @NonNull ColorSpace

Returns this color's color space.

final float

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

final float

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

final @NonNull ULong
@NonNull String

Returns a string representation of the object.

Extension functions

final @NonNull Color
ColorKt.compositeOver(@NonNull Color receiver, @NonNull Color background)

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

final boolean

false when this is Color.Unspecified.

final boolean

true when this is Color.Unspecified.

final float

Returns the relative luminance of this color.

final @NonNull Color
ColorKt.takeOrElse(
    @NonNull Color receiver,
    @NonNull Function0<@NonNull Color> block
)

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

final int

Converts this color to an ARGB color int.

Public constructors

Color

public Color(@NonNull ULong value)

Public methods

component1

public final float component1()

component2

public final float component2()

component3

public final float component3()

component4

public final float component4()

component5

public final @NonNull ColorSpace component5()

convert

public final @NonNull Color convert(@NonNull 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.

Parameters
@NonNull ColorSpace colorSpace

The destination color space, cannot be null

Returns
@NonNull Color

A non-null color instance in the specified color space

copy

public final @NonNull Color copy(float alpha, float red, float green, float blue)

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

getAlpha

public final float getAlpha()

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

See also
red
green
blue

getBlue

public final float getBlue()

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

getColorSpace

public final @NonNull ColorSpace getColorSpace()

Returns this color's color space.

Returns
@NonNull ColorSpace

A non-null instance of ColorSpace

getGreen

public final float getGreen()

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

getRed

public final float getRed()

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

getValue

public final @NonNull ULong getValue()

toString

public @NonNull String toString()

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
@NonNull String

A non-null string representation of the object

Extension functions

ColorKt.compositeOver

public final @NonNull Color ColorKt.compositeOver(@NonNull Color receiver, @NonNull Color background)

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
@NonNull Color

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

ColorKt.isSpecified

public final boolean ColorKt.isSpecified(@NonNull Color receiver)

false when this is Color.Unspecified.

ColorKt.isUnspecified

public final boolean ColorKt.isUnspecified(@NonNull Color receiver)

true when this is Color.Unspecified.

ColorKt.luminance

public final float ColorKt.luminance(@NonNull Color receiver)

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

ColorKt.takeOrElse

public final @NonNull Color ColorKt.takeOrElse(
    @NonNull Color receiver,
    @NonNull Function0<@NonNull Color> block
)

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

ColorKt.toArgb

public final int ColorKt.toArgb(@NonNull Color receiver)

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
int

An ARGB color in the sRGB color space