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

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

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

val Black: Color

val Blue: Color

val Cyan: Color

val DarkGray: Color

val Gray: Color

val Green: Color

val LightGray: Color

val Magenta: Color

val Red: Color

val Transparent: Color

val Unspecified: Color

val White: Color

val Yellow: Color

Color(value: ULong)

inline operator fun component1(): Float

inline operator fun component2(): Float

inline operator fun component3(): Float

inline operator fun component4(): Float

inline operator fun component5(): ColorSpace

fun convert(colorSpace: ColorSpace): Color

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

open fun toString(): String

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

Color(0.0, 0.0, 0.0, 1.0, sRGB IEC61966-2.1)

val alpha: Float

val blue: Float

val colorSpace: ColorSpace

val green: Float

val red: Float

val value: ULong

fun Color.compositeOver(background: Color): Color

fun Color.luminance(): Float

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

fun Color.toArgb(): @ColorInt Int

val Color.isSpecified: Boolean

val Color.isUnspecified: Boolean