Color

@Immutable inline class Color
kotlin.Any
   ↳ androidx.ui.graphics.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

Public constructors
<init>(value: ULong)

The Color class contains color information to be used while painting in Canvas.

Public methods
operator Float

operator Float

operator Float

operator Float

operator ColorSpace

Color
convert(colorSpace: ColorSpace)

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

Color
copy(alpha: Float = this.alpha, red: Float = this.red, green: Float = this.green, blue: Float = this.blue)

Copies the existing color, changing only the provided values.

String

Returns a string representation of the object.

Extension functions
From androidx.ui.graphics
Color
Color.compositeOver(background: Color)

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

Float

Returns the relative luminance of this color.

Int

Converts this color to an ARGB color int.

Color
Color.useOrElse(block: () -> Color)

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

Properties
Float

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

Float

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

ColorSpace

Returns this color's color space.

Float

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

Float

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

ULong

Companion properties
Color

Color

Color

Color

Color

Color

Color

Color

Color

Color

Color

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

Color

Color

Extension properties
From androidx.ui.graphics
Boolean

false when this is Color.Unset.

Boolean

true when this is Color.Unset.

Public constructors

<init>

Color(value: ULong)

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.

Public methods

component1

@Stable operator fun component1(): Float

component2

@Stable operator fun component2(): Float

component3

@Stable operator fun component3(): Float

component4

@Stable operator fun component4(): Float

component5

@Stable operator fun component5(): ColorSpace

convert

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
Return
A non-null color instance in the specified color space

copy

@Stable 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

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)
Return
A non-null string representation of the object

Properties

alpha

@Stable val alpha: Float

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

See Also

blue

@Stable 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

colorSpace

@Stable val colorSpace: ColorSpace

Returns this color's color space.

Return
A non-null instance of ColorSpace

green

@Stable 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

red

@Stable 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

value

val value: ULong

Companion properties

Black

@Stable val Black: Color

Blue

@Stable val Blue: Color

Cyan

@Stable val Cyan: Color

DarkGray

@Stable val DarkGray: Color

Gray

@Stable val Gray: Color

Green

@Stable val Green: Color

LightGray

@Stable val LightGray: Color

Magenta

@Stable val Magenta: Color

Red

@Stable val Red: Color

Transparent

@Stable val Transparent: Color

Unset

@Stable val Unset: 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 Unset for equality or use isUnset to check for the unset value or isSet for any color that isn't Unset.

White

@Stable val White: Color

Yellow

@Stable val Yellow: Color