Package limn.graphics

Record Class Color

java.lang.Object
java.lang.Record
limn.graphics.Color
Record Components:
r - red
g - green
b - blue
a - alpha (1 = opaque)
All Implemented Interfaces:
Paint
public record Color(float r, float g, float b, float a) extends Record implements Paint
Immutable straight-alpha RGBA color, channels in [0..1].

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Color
    BLACK
     
    static final Color
    TRANSPARENT
     
    static final Color
    WHITE
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Color(float r, float g, float b, float a)
    Creates an instance of a Color record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    float
    a()
    Returns the value of the a record component.
    float
    b()
    Returns the value of the b record component.
    static Color
    cmyk(float cyan, float magenta, float yellow, float key, float alpha)
    From cyan/magenta/yellow/key, each in [0,1].
    Color
    compositeOver(Color backdrop)
    The colour this one shows over backdrop: source-over, as the renderer composites.
    static double
    contrastRatio(Color a, Color b)
    WCAG 2.1 contrast ratio between two colours, from 1 (identical) to 21 (black on white).
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static @Nullable Color
    fromHex(@Nullable String text)
    Parses #RGB, #RGBA, #RRGGBB or #RRGGBBAA, with or without the #.
    float
    g()
    Returns the value of the g record component.
    final int
    hashCode()
    Returns a hash code value for this object.
    static Color
    hsv(float hue, float saturation, float value, float alpha)
    From hue/saturation/value.
    float
    hue()
    Hue in degrees [0,360).
    Color
    lerp(Color other, float t)
    Linear interpolation between this color and other at t in [0..1], with the channels weighted by their alpha (premultiplied), as the renderer's gradients interpolate.
    double
    lightness()
    CIE L* in [0,100]: perceptual lightness, where a difference of 1 is roughly the smallest step a person can see anywhere on the scale.
    static double
    linearToSrgb(double linear)
    Encodes one linear-light channel back to sRGB, the display's OETF.
    float
    r()
    Returns the value of the r record component.
    double
    relativeLuminance()
    WCAG 2.1 relative luminance in [0,1]: the sRGB channels linearized and weighted for the eye's response, so 0 is black and 1 is white.
    static Color
    rgb(int rgb)
    Opaque color from a 0xRRGGBB value.
    static Color
    rgba(int rgb, float alpha)
    Color from a 0xRRGGBB value plus explicit alpha.
    float
    saturation()
    Saturation in [0,1]: how far from grey.
    static double
    srgbToLinear(double channel)
    Decodes one sRGB-encoded channel in [0,1] to linear light.
    Color
    timesAlpha(float factor)
    This colour made more transparent by factor: its alpha multiplied, so a translucent colour faded to half is half as opaque as it was, where withAlpha(float) would set it to one half whatever it was.
    static int
    toByte(float channel)
    A unit channel as the byte a file or a framebuffer holds: clamped to [0,1], scaled to 0..255 and rounded to nearest.
    float[]
    toCmyk(float[] out)
    Cyan, magenta, yellow and key in [0,1]: the inverse of cmyk(float, float, float, float, float).
    String
    toHex()
    "#RRGGBB", or "#RRGGBBAA" when not fully opaque.
    final String
    toString()
    Returns a string representation of this record class.
    float
    value()
    Value in [0,1]: the brightest channel.
    Color
    withAlpha(float alpha)
     

    Methods inherited from class java.lang.Object

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

  • Field Details

    • TRANSPARENT

      public static final Color TRANSPARENT

    • BLACK

      public static final Color BLACK

    • WHITE

      public static final Color WHITE

  • Constructor Details

    • Color

      public Color(float r, float g, float b, float a)
      Creates an instance of a Color record class.
      Parameters:
      r - the value for the r record component
      g - the value for the g record component
      b - the value for the b record component
      a - the value for the a record component

  • Method Details

    • rgb

      public static Color rgb(int rgb)
      Opaque color from a 0xRRGGBB value.

    • rgba

      public static Color rgba(int rgb, float alpha)
      Color from a 0xRRGGBB value plus explicit alpha.

    • timesAlpha

      public Color timesAlpha(float factor)
      This colour made more transparent by factor: its alpha multiplied, so a translucent colour faded to half is half as opaque as it was, where withAlpha(float) would set it to one half whatever it was. The form to fade a tone by an animation's value, or to draw a tint of a tone that may itself be translucent.
      Parameters:
      factor - from 0 (clear) to 1 (this colour); values outside are clamped
      Returns:
      the colour with its alpha times factor

    • withAlpha

      public Color withAlpha(float alpha)
      Returns:
      this color with its alpha replaced by alpha

    • lerp

      public Color lerp(Color other, float t)
      Linear interpolation between this color and other at t in [0..1], with the channels weighted by their alpha (premultiplied), as the renderer's gradients interpolate. Between two opaque colours that is the plain mix of the channels. Toward a translucent one it is what a fade looks like: a fade from white to TRANSPARENT stays white as it thins, where mixing the channels as they are written went grey midway, because TRANSPARENT is a transparent black.

      Not a composite: the alpha is interpolated too, so a translucent colour mixed with an opaque one is translucent. compositeOver(limn.graphics.Color) is the colour a translucent one shows over a backdrop.

    • compositeOver

      public Color compositeOver(Color backdrop)
      The colour this one shows over backdrop: source-over, as the renderer composites. Over an opaque backdrop the result is opaque, which is what relativeLuminance() and contrastRatio(limn.graphics.Color, limn.graphics.Color) need of a translucent ink, a veil or a selection tint.
      Parameters:
      backdrop - what is under this colour
      Returns:
      the composite

    • hsv

      public static Color hsv(float hue, float saturation, float value, float alpha)
      From hue/saturation/value. hue is in degrees and wraps, so 370 and -350 both mean 10; saturation, value and alpha are clamped to [0,1].

    • hue

      public float hue()
      Hue in degrees [0,360). Grey has no hue and answers 0; a picker must keep its own hue across a trip through grey, or dragging saturation to zero would lose which colour you were on.

    • saturation

      public float saturation()
      Saturation in [0,1]: how far from grey.

    • value

      public float value()
      Value in [0,1]: the brightest channel.

    • cmyk

      public static Color cmyk(float cyan, float magenta, float yellow, float key, float alpha)
      From cyan/magenta/yellow/key, each in [0,1].

      Naive, not colour-managed. This is the plain arithmetic conversion every colour picker offers, and it is a convenience for people who think in ink percentages, not a substitute for a profile. Print work needs one; this will not match a press.

    • toCmyk

      public float[] toCmyk(float[] out)
      Cyan, magenta, yellow and key in [0,1]: the inverse of cmyk(float, float, float, float, float).

    • toHex

      public String toHex()
      "#RRGGBB", or "#RRGGBBAA" when not fully opaque.

    • fromHex

      public static @Nullable Color fromHex(@Nullable String text)
      Parses #RGB, #RGBA, #RRGGBB or #RRGGBBAA, with or without the #. Missing alpha is opaque.
      Returns:
      the colour, or null if the text is not one of those forms: a field being typed into is half-written most of the time, and an exception per keystroke is not a parser, it is a nuisance

    • relativeLuminance

      public double relativeLuminance()
      WCAG 2.1 relative luminance in [0,1]: the sRGB channels linearized and weighted for the eye's response, so 0 is black and 1 is white.

      Alpha is ignored. A translucent colour has no luminance of its own; what a reader sees is the composite. Composite it over its backdrop first (this.compositeOver(backdrop)) and ask that colour.

    • contrastRatio

      public static double contrastRatio(Color a, Color b)
      WCAG 2.1 contrast ratio between two colours, from 1 (identical) to 21 (black on white). Symmetric: which argument is the ink does not change it.

      The bars the guideline sets: 4.5 for body text, 3 for large text and for meaningful non-text such as an accent-filled indicator or a focus ring, and 7 for the enhanced (AAA) level.

      Both colours must be opaque for the answer to mean anything; see relativeLuminance().

    • lightness

      public double lightness()
      CIE L* in [0,100]: perceptual lightness, where a difference of 1 is roughly the smallest step a person can see anywhere on the scale.

      This is the scale to measure elevation on. A contrast ratio cannot describe the step from a surface to the card above it in a light palette at all: the step a dark palette reaches at 1.46:1 would need a luminance above 1 to reproduce from a near-white canvas, so the ratio reports two palettes as wildly different when they read identically.

      Alpha is ignored, exactly as in relativeLuminance().

    • srgbToLinear

      public static double srgbToLinear(double channel)
      Decodes one sRGB-encoded channel in [0,1] to linear light.
      Parameters:
      channel - the encoded value
      Returns:
      the linear value

    • linearToSrgb

      public static double linearToSrgb(double linear)
      Encodes one linear-light channel back to sRGB, the display's OETF. The input is held to [0,1] first: a value past white encodes as white, and a negative one as black.
      Parameters:
      linear - the linear value
      Returns:
      the encoded value, in [0,1]

    • toByte

      public static int toByte(float channel)
      A unit channel as the byte a file or a framebuffer holds: clamped to [0,1], scaled to 0..255 and rounded to nearest.
      Parameters:
      channel - the value
      Returns:
      0..255

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • r

      public float r()
      Returns the value of the r record component.
      Returns:
      the value of the r record component

    • g

      public float g()
      Returns the value of the g record component.
      Returns:
      the value of the g record component

    • b

      public float b()
      Returns the value of the b record component.
      Returns:
      the value of the b record component

    • a

      public float a()
      Returns the value of the a record component.
      Returns:
      the value of the a record component