Package icyllis.arc3d.core

Class Color

java.lang.Object
icyllis.arc3d.core.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.

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
    COLOR_CHANNEL_A
    Describes different color channels one can manipulate.
    static final int
    COLOR_CHANNEL_B
    Describes different color channels one can manipulate.
    static final int
    COLOR_CHANNEL_FLAG_ALPHA
    Used to represent the channels available in a color type or texture format as a mask.
    static final int
    COLOR_CHANNEL_FLAG_BLUE
    Used to represent the channels available in a color type or texture format as a mask.
    static final int
    COLOR_CHANNEL_FLAG_GRAY
    Used to represent the channels available in a color type or texture format as a mask.
    static final int
    COLOR_CHANNEL_FLAG_GREEN
    Used to represent the channels available in a color type or texture format as a mask.
    static final int
    COLOR_CHANNEL_FLAG_RED
    Used to represent the channels available in a color type or texture format as a mask.
    static final int
    COLOR_CHANNEL_FLAGS_RG
     
    static final int
    COLOR_CHANNEL_FLAGS_RGB
     
    static final int
    COLOR_CHANNEL_FLAGS_RGBA
     
    static final int
    COLOR_CHANNEL_G
    Describes different color channels one can manipulate.
    static final int
    COLOR_CHANNEL_R
    Describes different color channels one can manipulate.
    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.
    float
    mA
     
    static final int
    MAGENTA
    Represents fully opaque magenta.
    float
    mB
     
    float
    mG
     
    float
    mR
     
    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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Color()
    Creates a new transparent Color instance in the sRGB color space.
    Color(float r, float g, float b, float a)
    Creates a new Color instance in the sRGB color space.
    Color(int color)
    Creates a new Color instance from an ARGB color int.
    Color(Color color)
    Creates a new Color instance from an existing color instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    float
    alpha()
    Returns the value of the alpha component in the range \([0..1]\).
    void
    alpha(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
    alpha(int color, int alpha)
    Returns un-premultiplied color with red, blue, and green set from color; and alpha set from alpha.
    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 8-bit 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 \([0..1]\).
    void
    blue(float blue)
    Sets the value of the blue component in the range \([0..1]\).
    static int
    blue(int color)
    Return the blue component of a color int.
    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.
    float
    green()
    Returns the value of the green component in the range \([0..1]\).
    void
    green(float green)
    Sets the value of the green component in the range \([0..1]\).
    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
    isOpaque()
    Returns true if the color is an opaque color (i.e.
    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.
    static float[]
    load_and_premul(int col)
     
    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 int
    parseColor(String s)
    Parse the color string, and return the corresponding color-int.
    float
    red()
    Returns the value of the red component in the range \([0..1]\).
    void
    red(float red)
    Sets the value of the red component in the range \([0..1]\).
    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 8-bit alpha, 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.
    void
    set(float r, float g, float b, float a)
    Set this color values in the sRGB color space.
    void
    set(int color)
    Set this color values from an ARGB color int in the sRGB color space.
    void
    set(Color color)
    Set this color values from an existing color instance.
    int
    toArgb()
    Converts this color to an ARGB color int.
    String
    toString()
    Returns a string representation of the object.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • TRANSPARENT

      @ColorInt public static final int TRANSPARENT
      Represents fully transparent Color. May be used to initialize a destination containing a mask or a non-rectangular image.
      See Also:

    • BLACK

      @ColorInt public static final int BLACK
      Represents fully opaque black.
      See Also:

    • DKGRAY

      @ColorInt public static final int DKGRAY
      Represents fully opaque dark gray. Note that SVG dark gray is equivalent to 0xFFA9A9A9.
      See Also:

    • GRAY

      @ColorInt public static final int GRAY
      Represents fully opaque gray. Note that HTML gray is equivalent to 0xFF808080.
      See Also:

    • LTGRAY

      @ColorInt public static final int LTGRAY
      Represents fully opaque light gray. HTML silver is equivalent to 0xFFC0C0C0. Note that SVG light gray is equivalent to 0xFFD3D3D3.
      See Also:

    • WHITE

      @ColorInt public static final int WHITE
      Represents fully opaque white.
      See Also:

    • RED

      @ColorInt public static final int RED
      Represents fully opaque red.
      See Also:

    • GREEN

      @ColorInt public static final int GREEN
      Represents fully opaque green. HTML lime is equivalent. Note that HTML green is equivalent to 0xFF008000.
      See Also:

    • BLUE

      @ColorInt public static final int BLUE
      Represents fully opaque blue.
      See Also:

    • YELLOW

      @ColorInt public static final int YELLOW
      Represents fully opaque yellow.
      See Also:

    • CYAN

      @ColorInt public static final int CYAN
      Represents fully opaque cyan. HTML aqua is equivalent.
      See Also:

    • MAGENTA

      @ColorInt public static final int MAGENTA
      Represents fully opaque magenta. HTML fuchsia is equivalent.
      See Also:

    • COLOR_CHANNEL_R

      public static final int COLOR_CHANNEL_R
      Describes different color channels one can manipulate.
      See Also:

    • COLOR_CHANNEL_G

      public static final int COLOR_CHANNEL_G
      Describes different color channels one can manipulate.
      See Also:

    • COLOR_CHANNEL_B

      public static final int COLOR_CHANNEL_B
      Describes different color channels one can manipulate.
      See Also:

    • COLOR_CHANNEL_A

      public static final int COLOR_CHANNEL_A
      Describes different color channels one can manipulate.
      See Also:

    • COLOR_CHANNEL_FLAG_RED

      public static final int COLOR_CHANNEL_FLAG_RED
      Used to represent the channels available in a color type or texture format as a mask.
      See Also:

    • COLOR_CHANNEL_FLAG_GREEN

      public static final int COLOR_CHANNEL_FLAG_GREEN
      Used to represent the channels available in a color type or texture format as a mask.
      See Also:

    • COLOR_CHANNEL_FLAG_BLUE

      public static final int COLOR_CHANNEL_FLAG_BLUE
      Used to represent the channels available in a color type or texture format as a mask.
      See Also:

    • COLOR_CHANNEL_FLAG_ALPHA

      public static final int COLOR_CHANNEL_FLAG_ALPHA
      Used to represent the channels available in a color type or texture format as a mask.
      See Also:

    • COLOR_CHANNEL_FLAG_GRAY

      public static final int COLOR_CHANNEL_FLAG_GRAY
      Used to represent the channels available in a color type or texture format as a mask.
      See Also:

    • COLOR_CHANNEL_FLAGS_RG

      public static final int COLOR_CHANNEL_FLAGS_RG
      See Also:

    • COLOR_CHANNEL_FLAGS_RGB

      public static final int COLOR_CHANNEL_FLAGS_RGB
      See Also:

    • COLOR_CHANNEL_FLAGS_RGBA

      public static final int COLOR_CHANNEL_FLAGS_RGBA
      See Also:

    • mR

      @Internal public float mR

    • mG

      @Internal public float mG

    • mB

      @Internal public float mB

    • mA

      @Internal public float mA

  • Constructor Details

    • Color

      public Color()
      Creates a new transparent Color instance in the sRGB color space.

    • Color

      public Color(@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

    • Color

      public Color(float r, float g, float b, float a)
      Creates a new Color instance in the sRGB color space.
      Parameters:
      r - the value of the red channel, must be in [0..1] range
      g - the value of the green channel, must be in [0..1] range
      b - the value of the blue channel, must be in [0..1] range
      a - the value of the alpha channel, must be in [0..1] range

    • Color

      public Color(Color color)
      Creates a new Color instance from an existing color instance.
      Parameters:
      color - an existing color instance to create a new color from

  • Method Details

    • alpha

      public static int alpha(@ColorInt int color)
      Return the alpha component of a color int. This is the same as saying color >>> 24

    • red

      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

      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

      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

    • alpha

      @ColorInt public static int alpha(@ColorInt int color, int alpha)
      Returns un-premultiplied color with red, blue, and green set from color; and alpha set from alpha. The alpha component of color is ignored and is replaced by alpha in result.
      Parameters:
      color - packed RGB, eight bits per component
      alpha - alpha: transparent at zero, fully opaque at 255
      Returns:
      color with transparency

    • rgb

      @ColorInt public static int rgb(int red, int green, int blue)
      Return a color-int from 8-bit alpha, red, green, blue components. The alpha component is implicitly set fully opaque to 255. 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
      Returns:
      color and alpha, un-premultiplied

    • 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
      Returns:
      color and alpha, un-premultiplied

    • argb

      @ColorInt public static int argb(int alpha, int red, int green, int blue)
      Return a color-int from 8-bit 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. Since color is un-premultiplied, alpha may be smaller than the largest of red, green, and blue.
      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
      Returns:
      color and alpha, un-premultiplied

    • 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
      Returns:
      color and alpha, un-premultiplied

    • set

      public void set(@ColorInt int color)
      Set this color values from an ARGB color int in the sRGB color space.
      Parameters:
      color - the ARGB color int to set this from

    • set

      public void set(float r, float g, float b, float a)
      Set this color values in the sRGB color space.
      Parameters:
      r - the value of the red channel, must be in [0..1] range
      g - the value of the green channel, must be in [0..1] range
      b - the value of the blue channel, must be in [0..1] range
      a - the value of the alpha channel, must be in [0..1] range

    • set

      public void set(Color color)
      Set this color values from an existing color instance.
      Parameters:
      color - an existing color instance

    • 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 \([0..1]\).
      See Also:

    • green

      public float green()
      Returns the value of the green component in the range \([0..1]\).
      See Also:

    • blue

      public float blue()
      Returns the value of the blue component in the range \([0..1]\).
      See Also:

    • alpha

      public float alpha()
      Returns the value of the alpha component in the range \([0..1]\).
      See Also:

    • red

      public void red(float red)
      Sets the value of the red component in the range \([0..1]\).
      See Also:

    • green

      public void green(float green)
      Sets the value of the green component in the range \([0..1]\).
      See Also:

    • blue

      public void blue(float blue)
      Sets the value of the blue component in the range \([0..1]\).
      See Also:

    • alpha

      public void alpha(float alpha)
      Returns the value of the alpha component in the range \([0..1]\).
      See Also:

    • isOpaque

      public boolean isOpaque()
      Returns true if the color is an opaque color (i.e. alpha() == 1.0f).
      Returns:
      true if the color is opaque

    • 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 + ')'

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

    • parseColor

      @ColorInt public static int parseColor(@Nonnull String s)

      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

    • RGBToHSV

      public static void RGBToHSV(int r, int g, int b, 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(int color, 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

      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

      public static int HSVToColor(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(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(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(float r, float g, float b)
      Converts a linear RGB color to a luminance value.

    • luminance

      public static float luminance(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

      @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

    • load_and_premul

      @Nonnull public static float[] load_and_premul(int col)