Package icyllis.modernui.graphics

Class Color

java.lang.Object
icyllis.modernui.graphics.Color
public final class Color extends Object

The Color class provides methods for creating, converting and manipulating colors.

Color int

Color int is the most common representation.

A color int always defines a color in the sRGB color space using 4 components packed in a single 32 bit integer value:

ComponentNameSizeRange
AAlpha8 bits\([0..255]\)
RRed8 bits\([0..255]\)
GGreen8 bits\([0..255]\)
BBlue8 bits\([0..255]\)

The components in this table are listed in encoding order (see below), which is why color ints are called ARGB colors. Note that this packing format is exactly mapped to Bitmap.Format.BGRA_8888_PACK32.

Usage in code

To avoid confusing color ints with arbitrary integer values, it is a good practice to annotate them with the @ColorInt annotation.

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

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:

Color4f

Color4f is a representation of RGBA color values in the sRGB color space, holding four floating-point components, to store colors with more precision than color ints. Color components are always in a known order. RGB components may be premultiplied by alpha or not, but public API always uses un-premultiplied colors.

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BLACK
    Represents fully opaque black.
    static final int
    BLUE
    Represents fully opaque blue.
    static final int
    CYAN
    Represents fully opaque cyan.
    static final int
    DKGRAY
    Represents fully opaque dark gray.
    static final int
    GRAY
    Represents fully opaque gray.
    static final int
    GREEN
    Represents fully opaque green.
    static final int
    LTGRAY
    Represents fully opaque light gray.
    static final int
    MAGENTA
    Represents fully opaque magenta.
    static final int
    RED
    Represents fully opaque red.
    static final int
    TRANSPARENT
    Represents fully transparent Color.
    static final int
    WHITE
    Represents fully opaque white.
    static final int
    YELLOW
    Represents fully opaque yellow.

  • Method Summary

    Modifier and Type
    Method
    Description
    float
    alpha()
    Returns the value of the alpha component in the range \([0..1]\).
    static int
    alpha(int color)
    Return the alpha component of a color int.
    static int
    argb(float alpha, float red, float green, float blue)
    Return a color-int from alpha, red, green, blue float components in the range \([0..1]\).
    static int
    argb(int alpha, int red, int green, int blue)
    Return a color-int from alpha, red, green, blue components.
    static int
    blend(BlendMode mode, int src, int dst)
    Blends the two colors using premultiplied alpha on CPU side.
    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)).
    static int
    blue(int color)
    Return the blue component of a color int.
    Color
    convert(ColorSpace colorSpace)
    Converts this color from its color space to the specified color space.
    boolean
    equals(Object o)
     
    static float
    GammaToLinear(float x)
    Converts a color component from the sRGB space to the linear RGB space, using the sRGB transfer function.
    static void
    GammaToLinear(float[] col)
    Converts a color from the sRGB space to the linear RGB space, using the sRGB transfer function.
    ColorSpace
    getColorSpace()
    Returns this color's color space.
    float
    getComponent(int component)
    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)).
    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.
    float[]
    getComponents()
    Returns this color's components as a new array.
    float[]
    getComponents(float[] components)
    Copies this color's components in the supplied array.
    ColorSpace.Model
    getModel()
    Returns the color model of this color.
    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)).
    static int
    green(int color)
    Return the green component of a color int.
    int
    hashCode()
     
    static int
    HSVToColor(float[] hsv)
    Converts HSV components to an RGB color.
    static int
    HSVToColor(float h, float s, float v)
    Converts HSV components to an RGB color.
    boolean
    isSrgb()
    Indicates whether this color is in the sRGB color space.
    boolean
    isWideGamut()
    Indicates whether this color color is in a wide-gamut color space.
    static float
    lightness(float lum)
    Coverts a luminance value to a perceptual lightness value.
    static float
    LinearToGamma(float x)
    Converts a color component from the linear RGB space to the sRGB space, using the inverse of sRGB transfer function.
    static void
    LinearToGamma(float[] col)
    Converts a color from the linear RGB space to the sRGB space, using the inverse of sRGB transfer function.
    float
    luminance()
    Returns the relative luminance of this color.
    static float
    luminance(float[] col)
    Converts a linear RGB color to a luminance value.
    static float
    luminance(float r, float g, float b)
    Converts a linear RGB color to a luminance value.
    static float
    luminance(int color)
    Returns the relative luminance of a color.
    static int
    parseColor(String colorString)
    Parse the color string, and return the corresponding color-int.
    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)).
    static int
    red(int color)
    Return the red component of a color int.
    static int
    rgb(float red, float green, float blue)
    Return a color-int from red, green, blue float components in the range \([0..1]\).
    static int
    rgb(int red, int green, int blue)
    Return a color-int from red, green, blue components.
    static void
    RGBToHSV(int color, float[] hsv)
    Converts RGB to its HSV components.
    static void
    RGBToHSV(int r, int g, int b, float[] hsv)
    Converts RGB to its HSV components.
    int
    toArgb()
    Converts this color to an ARGB color int.
    String
    toString()
    Returns a string representation of the object.
    static Color
    valueOf(float[] components, ColorSpace colorSpace)
    Creates a new Color in the specified color space with the specified component values.
    static Color
    valueOf(float r, float g, float b)
    Creates a new opaque Color in the sRGB color space with the specified red, green and blue component values.
    static Color
    valueOf(float r, float g, float b, float a)
    Creates a new Color in the sRGB color space with the specified red, green, blue and alpha component values.
    static Color
    valueOf(float r, float g, float b, float a, ColorSpace colorSpace)
    Creates a new Color in the specified color space with the specified red, green, blue and alpha component values.
    static Color
    valueOf(int color)
    Creates a new Color instance from an ARGB color int.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

  • Method Details

    • getColorSpace

      @NonNull public ColorSpace getColorSpace()
      Returns this color's color space.
      Returns:
      A non-null instance of ColorSpace

    • getModel

      @NonNull public ColorSpace.Model getModel()
      Returns the color model of this color.
      Returns:
      A non-null ColorSpace.Model

    • isWideGamut

      public boolean isWideGamut()
      Indicates whether this color color is in a wide-gamut color space. See ColorSpace.isWideGamut() for a definition of a wide-gamut color space.
      Returns:
      True if this color is in a wide-gamut color space, false otherwise
      See Also:

    • isSrgb

      public boolean isSrgb()
      Indicates whether this color is in the sRGB color space.
      Returns:
      True if this color is in the sRGB color space, false otherwise
      See Also:

    • getComponentCount

      @IntRange(from=4L, to=5L) public 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.
      Returns:
      The integer 4 or 5

    • convert

      @NonNull public 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(ColorSpace, ColorSpace).
      Parameters:
      colorSpace - The destination color space, cannot be null
      Returns:
      A non-null color instance in the specified color space

    • toArgb

      @ColorInt public int toArgb()
      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:
      An ARGB color in the sRGB color space

    • red

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

      If this color's color model is not RGB, calling this method is equivalent to getComponent(0).

      See Also:

    • green

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

      If this color's color model is not RGB, calling this method is equivalent to getComponent(1).

      See Also:

    • blue

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

      If this color's color model is not RGB, calling this method is equivalent to getComponent(2).

      See Also:

    • alpha

      public float alpha()
      Returns the value of the alpha component in the range \([0..1]\). Calling this method is equivalent to getComponent(getComponentCount() - 1).
      See Also:

    • getComponents

      @NonNull @Size(min=4L, max=5L) public float[] getComponents()
      Returns this color's components as a new array. The last element of the array is always the alpha component.
      Returns:
      A new, non-null array whose size is equal to getComponentCount()
      See Also:

    • getComponents

      @NonNull @Size(min=4L) public float[] getComponents(@Nullable @Size(min=4L) float[] components)
      Copies this color's components in the supplied array. The last element of the array is always the alpha component.
      Parameters:
      components - An array of floats whose size must be at least getComponentCount(), can be null
      Returns:
      The array passed as a parameter if not null, or a new array of length getComponentCount()
      Throws:
      IllegalArgumentException - If the specified array's length is less than getComponentCount()
      See Also:

    • getComponent

      public float getComponent(@IntRange(from=0L,to=4L) int component)

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

      If the requested component index is getComponentCount(), this method returns the alpha component, always in the range \([0..1]\).

      Throws:
      ArrayIndexOutOfBoundsException - If the specified component index is invalid input: '<' 0 or >= getComponentCount()
      See Also:

    • luminance

      public float luminance()

      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:
      A value between 0 (darkest black) and 1 (lightest white)
      Throws:
      IllegalArgumentException - If this color's color space does not use the RGB color model

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      @NonNull public String toString()

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

       "Color(" + r + ", " + g + ", " + b + ", " + a +
         ", " + getColorSpace().getName + ')'

      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)
      Overrides:
      toString in class Object
      Returns:
      A non-null string representation of the object

    • valueOf

      @NonNull public static Color valueOf(@ColorInt int color)
      Creates a new Color instance from an ARGB color int. The resulting color is in the sRGB color space.
      Parameters:
      color - The ARGB color int to create a Color from
      Returns:
      A non-null instance of Color

    • valueOf

      @NonNull public static Color valueOf(float r, float g, float b)
      Creates a new opaque Color in the sRGB color space with the specified red, green and blue component values. The component values must be in the range \([0..1]\).
      Parameters:
      r - The red component of the opaque sRGB color to create, in \([0..1]\)
      g - The green component of the opaque sRGB color to create, in \([0..1]\)
      b - The blue component of the opaque sRGB color to create, in \([0..1]\)
      Returns:
      A non-null instance of Color

    • valueOf

      @NonNull public static Color valueOf(float r, float g, float b, float a)
      Creates a new Color in the sRGB color space with the specified red, green, blue and alpha component values. The component values must be in the range \([0..1]\).
      Parameters:
      r - The red component of the sRGB color to create, in \([0..1]\)
      g - The green component of the sRGB color to create, in \([0..1]\)
      b - The blue component of the sRGB color to create, in \([0..1]\)
      a - The alpha component of the sRGB color to create, in \([0..1]\)
      Returns:
      A non-null instance of Color

    • valueOf

      @NonNull public static Color valueOf(float r, float g, float b, float a, @NonNull ColorSpace colorSpace)
      Creates a new Color in the specified color space with the specified red, green, blue and alpha component values. The range of the components is defined by ColorSpace.getMinValue(int) and ColorSpace.getMaxValue(int). The values passed to this method must be in the proper range.
      Parameters:
      r - The red component of the color to create
      g - The green component of the color to create
      b - The blue component of the color to create
      a - The alpha component of the color to create, in \([0..1]\)
      colorSpace - The color space of the color to create
      Returns:
      A non-null instance of Color
      Throws:
      IllegalArgumentException - If the specified color space uses a color model with more than 3 components

    • valueOf

      @NonNull public static Color valueOf(@NonNull @Size(min=4L,max=5L) float[] components, @NonNull ColorSpace colorSpace)

      Creates a new Color in the specified color space with the specified component values. The range of the components is defined by ColorSpace.getMinValue(int) and ColorSpace.getMaxValue(int). The values passed to this method must be in the proper range. The alpha component is always in the range \([0..1]\).

      The length of the array of components must be at least ColorSpace.getComponentCount() + 1. The component at index ColorSpace.getComponentCount() is always alpha.

      Parameters:
      components - The components of the color to create, with alpha as the last component
      colorSpace - The color space of the color to create
      Returns:
      A non-null instance of Color
      Throws:
      IllegalArgumentException - If the array of components is smaller than required by the color space

    • alpha

      @IntRange(from=0L, to=255L) public static int alpha(@ColorInt int color)
      Return the alpha component of a color int. This is the same as saying color >>> 24

    • red

      @IntRange(from=0L, to=255L) public static int red(@ColorInt int color)
      Return the red component of a color int. This is the same as saying (color >> 16) invalid input: '&' 0xFF

    • green

      @IntRange(from=0L, to=255L) public static int green(@ColorInt int color)
      Return the green component of a color int. This is the same as saying (color >> 8) invalid input: '&' 0xFF

    • blue

      @IntRange(from=0L, to=255L) public static int blue(@ColorInt int color)
      Return the blue component of a color int. This is the same as saying color invalid input: '&' 0xFF

    • rgb

      @ColorInt public static int rgb(@IntRange(from=0L,to=255L) int red, @IntRange(from=0L,to=255L) int green, @IntRange(from=0L,to=255L) int blue)
      Return a color-int from red, green, blue components. The alpha component is implicitly 255 (fully opaque). These component values should be \([0..255]\), but there is no range check performed, so if they are out of range, the returned color is undefined.
      Parameters:
      red - Red component \([0..255]\) of the color
      green - Green component \([0..255]\) of the color
      blue - Blue component \([0..255]\) of the color

    • rgb

      @ColorInt public static int rgb(float red, float green, float blue)
      Return a color-int from red, green, blue float components in the range \([0..1]\). The alpha component is implicitly 1.0 (fully opaque). If the components are out of range, the returned color is undefined.
      Parameters:
      red - Red component \([0..1]\) of the color
      green - Green component \([0..1]\) of the color
      blue - Blue component \([0..1]\) of the color

    • argb

      @ColorInt public static int argb(@IntRange(from=0L,to=255L) int alpha, @IntRange(from=0L,to=255L) int red, @IntRange(from=0L,to=255L) int green, @IntRange(from=0L,to=255L) int blue)
      Return a color-int from alpha, red, green, blue components. These component values should be \([0..255]\), but there is no range check performed, so if they are out of range, the returned color is undefined.
      Parameters:
      alpha - Alpha component \([0..255]\) of the color
      red - Red component \([0..255]\) of the color
      green - Green component \([0..255]\) of the color
      blue - Blue component \([0..255]\) of the color

    • argb

      @ColorInt public static int argb(float alpha, float red, float green, float blue)
      Return a color-int from alpha, red, green, blue float components in the range \([0..1]\). If the components are out of range, the returned color is undefined.
      Parameters:
      alpha - Alpha component \([0..1]\) of the color
      red - Red component \([0..1]\) of the color
      green - Green component \([0..1]\) of the color
      blue - Blue component \([0..1]\) of the color

    • parseColor

      @ColorInt public static int parseColor(@NonNull String colorString)

      Parse the color string, and return the corresponding color-int. If the string cannot be parsed, throws an IllegalArgumentException exception. Supported formats are:

      • #RRGGBB
      • #AARRGGBB
      • 0xRRGGBB
      • 0xAARRGGBB

      The following names are also accepted: red, blue, green, black, white, gray, cyan, magenta, yellow, lightgray, darkgray, grey, lightgrey, darkgrey, aqua, fuchsia, lime, maroon, navy, olive, purple, silver, and teal.

    • RGBToHSV

      public static void RGBToHSV(@IntRange(from=0L,to=255L) int r, @IntRange(from=0L,to=255L) int g, @IntRange(from=0L,to=255L) int b, @NonNull @Size(3L) float[] hsv)
      Converts RGB to its HSV components. hsv[0] contains hsv hue, a value from zero to less than 360. hsv[1] contains hsv saturation, a value from zero to one. hsv[2] contains hsv value, a value from zero to one.
      Parameters:
      r - red component value from zero to 255
      g - green component value from zero to 255
      b - blue component value from zero to 255
      hsv - three element array which holds the resulting HSV components

    • RGBToHSV

      public static void RGBToHSV(@ColorInt int color, @NonNull @Size(3L) float[] hsv)
      Converts RGB to its HSV components. Alpha in ARGB (if it has) is ignored. hsv[0] contains hsv hue, and is assigned a value from zero to less than 360. hsv[1] contains hsv saturation, a value from zero to one. hsv[2] contains hsv value, a value from zero to one.
      Parameters:
      color - RGB or ARGB color to convert
      hsv - three element array which holds the resulting HSV components

    • HSVToColor

      @ColorInt public static int HSVToColor(float h, float s, float v)
      Converts HSV components to an RGB color. Alpha is NOT implicitly set.

      Out of range hsv values are clamped.

      Parameters:
      h - hsv hue, an angle from zero to less than 360
      s - hsv saturation, and varies from zero to one
      v - hsv value, and varies from zero to one
      Returns:
      RGB equivalent to HSV, without alpha

    • HSVToColor

      @ColorInt public static int HSVToColor(@NonNull @Size(3L) float[] hsv)
      Converts HSV components to an RGB color. Alpha is NOT implicitly set. hsv[0] represents hsv hue, an angle from zero to less than 360. hsv[1] represents hsv saturation, and varies from zero to one. hsv[2] represents hsv value, and varies from zero to one.

      Out of range hsv values are clamped.

      Parameters:
      hsv - three element array which holds the input HSV components
      Returns:
      RGB equivalent to HSV, without alpha

    • GammaToLinear

      public static float GammaToLinear(float x)
      Converts a color component from the sRGB space to the linear RGB space, using the sRGB transfer function.
      Parameters:
      x - a color component
      Returns:
      transformed color component

    • LinearToGamma

      public static float LinearToGamma(float x)
      Converts a color component from the linear RGB space to the sRGB space, using the inverse of sRGB transfer function.
      Parameters:
      x - a color component
      Returns:
      transformed color component

    • GammaToLinear

      public static void GammaToLinear(@NonNull @Size(min=3L) float[] col)
      Converts a color from the sRGB space to the linear RGB space, using the sRGB transfer function.
      Parameters:
      col - the color components

    • LinearToGamma

      public static void LinearToGamma(@NonNull @Size(min=3L) float[] col)
      Converts a color from the linear RGB space to the sRGB space, using the inverse of sRGB transfer function.
      Parameters:
      col - the color components

    • luminance

      public static float luminance(@ColorInt int color)
      Returns the relative luminance of a color.

      Assumes sRGB encoding. Based on the formula for relative luminance defined in WCAG 2.0, W3C Recommendation 11 December 2008.

      Returns:
      a value between 0 (darkest black) and 1 (lightest white)

    • luminance

      public static float luminance(float r, float g, float b)
      Converts a linear RGB color to a luminance value.

    • luminance

      public static float luminance(@NonNull @Size(min=3L) float[] col)
      Converts a linear RGB color to a luminance value.
      Parameters:
      col - the color components

    • lightness

      public static float lightness(float lum)
      Coverts a luminance value to a perceptual lightness value.

    • blend

      @Internal @ColorInt public static int blend(@NonNull BlendMode mode, @ColorInt int src, @ColorInt int dst)
      Blends the two colors using premultiplied alpha on CPU side. This is to simulate the color blending on GPU side, but this is only used for color filtering (tinting). Do NOT premultiply the src and dst colors with alpha on CPU side. The returned color is un-premultiplied by alpha. This method will not lose precision, color components are still 8-bit.
      Parameters:
      mode - the blend mode that determines blending factors
      src - the source color (straight) to be blended into the destination color
      dst - the destination color (straight) on which the source color is to be blended
      Returns:
      the color (straight) resulting from the color blending