Package icyllis.arc3d.core

# Class ColorSpace.Connector

java.lang.Object
icyllis.arc3d.core.ColorSpace.Connector

Direct Known Subclasses:
  `ColorSpace.Connector.Rgb`

Enclosing class:
  `ColorSpace`

public static class ColorSpace.Connector extends Object

A connector transforms colors from a source color space to a destination color space.

A source color space is connected to a destination color space using the color transform \(C\) computed from their respective transforms noted \(T_{src}\) and \(T_{dst}\) in the following equation:

$$C = T^{-1}_{dst} . T_{src}$$

The transform \(C\) shown above is only valid when the source and destination color spaces have the same profile connection space (PCS). We know that instances of `ColorSpace` always use CIE XYZ as their PCS but their white points might differ. When they do, we must perform a chromatic adaptation of the color spaces' transforms. To do so, we use the von Kries method described in the documentation of `ColorSpace.Adaptation`, using the CIE standard illuminant `D50` as the target white point.

Example of conversion from `sRGB` to `DCI-P3`:

     ColorSpace.Connector connector = ColorSpace.connect(
             ColorSpace.get(ColorSpace.Named.SRGB),
             ColorSpace.get(ColorSpace.Named.DCI_P3));
     float[] p3 = connector.transform(1.0f, 0.0f, 0.0f);
     // p3 contains { 0.9473, 0.2740, 0.2076 }

See Also:
  - `ColorSpace.Adaptation`
  - `ColorSpace.adapt(ColorSpace, float[], Adaptation)`
  - `ColorSpace.adapt(ColorSpace, float[])`
  - `ColorSpace.connect(ColorSpace, ColorSpace, RenderIntent)`
  - `ColorSpace.connect(ColorSpace, ColorSpace)`
  - `ColorSpace.connect(ColorSpace, RenderIntent)`
  - `ColorSpace.connect(ColorSpace)`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ColorSpace.Connector.Rgb`
  Optimized connector for RGB->RGB conversions.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ColorSpace`
  `getDestination()`
  Returns the destination color space this connector will convert to.
  `ColorSpace.RenderIntent`
  `getRenderIntent()`
  Returns the render intent this connector will use when mapping the source color space to the destination color space.
  `ColorSpace`
  `getSource()`
  Returns the source color space this connector will convert from.
  `float[]`
  `transform(float[] v)`
  Transforms the specified color from the source color space to a color in the destination color space.
  `float[]`
  `transform(float r, float g, float b)`
  Transforms the specified color from the source color space to a color in the destination color space.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getSource

    @Nonnull public ColorSpace getSource()
    Returns the source color space this connector will convert from.
    Returns:
      A non-null instance of `ColorSpace`
    See Also:
      - `getDestination()`

  - ### getDestination

    @Nonnull public ColorSpace getDestination()
    Returns the destination color space this connector will convert to.
    Returns:
      A non-null instance of `ColorSpace`
    See Also:
      - `getSource()`

  - ### getRenderIntent

    public ColorSpace.RenderIntent getRenderIntent()
    Returns the render intent this connector will use when mapping the source color space to the destination color space.
    Returns:
      A non-null `ColorSpace.RenderIntent`
    See Also:
      - `ColorSpace.RenderIntent`

  - ### transform

    @Nonnull @Size(3L) public float[] transform(float r, float g, float b)

    Transforms the specified color from the source color space to a color in the destination color space. This convenience method assumes a source color model with 3 components (typically RGB). To transform from color models with more than 3 components, such as `CMYK`, use `transform(float[])` instead.

    Parameters:
      `r` - The red component of the color to transform
      `g` - The green component of the color to transform
      `b` - The blue component of the color to transform
    Returns:
      A new array of 3 floats containing the specified color transformed from the source space to the destination space
    See Also:
      - `transform(float[])`

  - ### transform

    @Nonnull @Size(min=3L) public float[] transform(@Nonnull @Size(min=3L) float[] v)

    Transforms the specified color from the source color space to a color in the destination color space.

    Parameters:
      `v` - A non-null array of 3 floats containing the value to transform and that will hold the result of the transform
    Returns:
      The v array passed as a parameter, containing the specified color transformed from the source space to the destination space
    See Also:
      - `transform(float, float, float)`