diff --git a/Android.mk b/Android.mk index 552103d4d1a54..514ed47de3680 100644 --- a/Android.mk +++ b/Android.mk @@ -1129,7 +1129,9 @@ LOCAL_DROIDDOC_OPTIONS:=\ -proofread $(OUT_DOCS)/$(LOCAL_MODULE)-proofread.txt \ -sdkvalues $(OUT_DOCS) \ -hdf android.whichdoc offline \ - -referenceonly + -referenceonly \ + -resourcesdir $(LOCAL_PATH)/docs/html/reference/images/ \ + -resourcesoutdir reference/android/images/ LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR:=build/tools/droiddoc/templates-sdk diff --git a/docs/html/reference/images/graphics/colorspace_aces.png b/docs/html/reference/images/graphics/colorspace_aces.png new file mode 100644 index 0000000000000..efafe5c851e75 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_aces.png differ diff --git a/docs/html/reference/images/graphics/colorspace_acescg.png b/docs/html/reference/images/graphics/colorspace_acescg.png new file mode 100644 index 0000000000000..55f6ab58c42fa Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_acescg.png differ diff --git a/docs/html/reference/images/graphics/colorspace_adobe_rgb.png b/docs/html/reference/images/graphics/colorspace_adobe_rgb.png new file mode 100644 index 0000000000000..cb7d60258cb43 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_adobe_rgb.png differ diff --git a/docs/html/reference/images/graphics/colorspace_bt2020.png b/docs/html/reference/images/graphics/colorspace_bt2020.png new file mode 100644 index 0000000000000..34a3853c1cc51 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_bt2020.png differ diff --git a/docs/html/reference/images/graphics/colorspace_bt709.png b/docs/html/reference/images/graphics/colorspace_bt709.png new file mode 100644 index 0000000000000..ba637f525c438 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_bt709.png differ diff --git a/docs/html/reference/images/graphics/colorspace_dci_p3.png b/docs/html/reference/images/graphics/colorspace_dci_p3.png new file mode 100644 index 0000000000000..19144e768fa65 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_dci_p3.png differ diff --git a/docs/html/reference/images/graphics/colorspace_display_p3.png b/docs/html/reference/images/graphics/colorspace_display_p3.png new file mode 100644 index 0000000000000..a86c60ab9ae6f Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_display_p3.png differ diff --git a/docs/html/reference/images/graphics/colorspace_ntsc_1953.png b/docs/html/reference/images/graphics/colorspace_ntsc_1953.png new file mode 100644 index 0000000000000..bce93da60bda1 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_ntsc_1953.png differ diff --git a/docs/html/reference/images/graphics/colorspace_pro_photo_rgb.png b/docs/html/reference/images/graphics/colorspace_pro_photo_rgb.png new file mode 100644 index 0000000000000..74c95be64de51 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_pro_photo_rgb.png differ diff --git a/docs/html/reference/images/graphics/colorspace_scrgb.png b/docs/html/reference/images/graphics/colorspace_scrgb.png new file mode 100644 index 0000000000000..2351b8e35fb74 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_scrgb.png differ diff --git a/docs/html/reference/images/graphics/colorspace_smpte_c.png b/docs/html/reference/images/graphics/colorspace_smpte_c.png new file mode 100644 index 0000000000000..360bb73c78c00 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_smpte_c.png differ diff --git a/docs/html/reference/images/graphics/colorspace_srgb.png b/docs/html/reference/images/graphics/colorspace_srgb.png new file mode 100644 index 0000000000000..ba637f525c438 Binary files /dev/null and b/docs/html/reference/images/graphics/colorspace_srgb.png differ diff --git a/graphics/java/android/graphics/ColorSpace.java b/graphics/java/android/graphics/ColorSpace.java index d114deb0a2435..4f2465fd5da41 100644 --- a/graphics/java/android/graphics/ColorSpace.java +++ b/graphics/java/android/graphics/ColorSpace.java @@ -19,6 +19,7 @@ package android.graphics; import android.annotation.IntRange; import android.annotation.NonNull; import android.annotation.Size; +import android.annotation.Nullable; import java.util.Arrays; import java.util.function.DoubleUnaryOperator; @@ -207,6 +208,11 @@ public abstract class ColorSpace { * ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3); * * + *

The properties of each color space are described below (see {@link #SRGB sRGB} + * for instance). When applicable, the color gamut of each color space is compared + * to the color gamut of sRGB using a CIE 1931 xy chromaticity diagram. This diagram + * shows the location of the color space's primaries and white point.

+ * * @see ColorSpace#get(Named) */ public enum Named { @@ -240,6 +246,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

sRGB
+ *

*/ SRGB, /** @@ -263,6 +273,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

sRGB
+ *

*/ LINEAR_SRGB, /** @@ -298,6 +312,10 @@ public abstract class ColorSpace { * * Range\([-0.5..7.5[\) * + *

+ * + *

Extended RGB (orange) vs sRGB (white)
+ *

*/ EXTENDED_SRGB, /** @@ -321,6 +339,10 @@ public abstract class ColorSpace { * * Range\([-0.5..7.5[\) * + *

+ * + *

Extended RGB (orange) vs sRGB (white)
+ *

*/ LINEAR_EXTENDED_SRGB, /** @@ -352,6 +374,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

BT.709
+ *

*/ BT709, /** @@ -383,6 +409,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

BT.2020 (orange) vs sRGB (white)
+ *

*/ BT2020, /** @@ -406,6 +436,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

DCI-P3 (orange) vs sRGB (white)
+ *

*/ DCI_P3, /** @@ -437,6 +471,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

Display P3 (orange) vs sRGB (white)
+ *

*/ DISPLAY_P3, /** @@ -468,6 +506,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

NTSC 1953 (orange) vs sRGB (white)
+ *

*/ NTSC_1953, /** @@ -499,6 +541,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

SMPTE-C (orange) vs sRGB (white)
+ *

*/ SMPTE_C, /** @@ -522,6 +568,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

Adobe RGB (orange) vs sRGB (white)
+ *

*/ ADOBE_RGB, /** @@ -553,6 +603,10 @@ public abstract class ColorSpace { * * Range\([0..1]\) * + *

+ * + *

ProPhoto RGB (orange) vs sRGB (white)
+ *

*/ PRO_PHOTO_RGB, /** @@ -576,6 +630,10 @@ public abstract class ColorSpace { * * Range\([-65504.0, 65504.0]\) * + *

+ * + *

ACES (orange) vs sRGB (white)
+ *

*/ ACES, /** @@ -599,6 +657,10 @@ public abstract class ColorSpace { * * Range\([-65504.0, 65504.0]\) * + *

+ * + *

ACEScg (orange) vs sRGB (white)
+ *

*/ ACESCG, /** @@ -1110,7 +1172,7 @@ public abstract class ColorSpace { if (source.equals(destination)) return Connector.identity(source); if (source.getModel() == Model.RGB && destination.getModel() == Model.RGB) { - return new Connector.RGB((Rgb) source, (Rgb) destination, intent); + return new Connector.Rgb((Rgb) source, (Rgb) destination, intent); } return new Connector(source, destination, intent); @@ -1162,7 +1224,7 @@ public abstract class ColorSpace { if (source.isSrgb()) return Connector.identity(source); if (source.getModel() == Model.RGB) { - return new Connector.RGB((Rgb) source, (Rgb) get(Named.SRGB), intent); + return new Connector.Rgb((Rgb) source, (Rgb) get(Named.SRGB), intent); } return new Connector(source, get(Named.SRGB), intent); @@ -1740,6 +1802,11 @@ public abstract class ColorSpace { * primaries and white point in the CIE XYZ space. The tristimulus XYZ values * are internally converted to xyY.

* + *

+ * + *

sRGB primaries and white point
+ *

+ * *

Transfer functions

*

A transfer function is a color component conversion function, defined as * a single variable, monotonic mathematical function. It is applied to each @@ -1788,6 +1855,11 @@ public abstract class ColorSpace { * range \([-0.5..7.5]\) while {@link Named#ACES ACES} can be used throughout * the range \([-65504, 65504]\).

* + *

+ * + *

Extended sRGB and its large range
+ *

+ * *

Converting between RGB color spaces

*

Conversion between two color spaces is achieved by using an intermediate * color space called the profile connection space (PCS). The PCS used by @@ -1854,7 +1926,7 @@ public abstract class ColorSpace { @NonNull @Size(9) float[] toXYZ, @NonNull DoubleUnaryOperator oetf, @NonNull DoubleUnaryOperator eotf) { - this(name,computePrimaries(toXYZ, eotf), computeWhitePoint(toXYZ, eotf), + this(name, computePrimaries(toXYZ, eotf), computeWhitePoint(toXYZ, eotf), oetf, eotf, 0.0f, 1.0f, MIN_ID); } @@ -1996,8 +2068,8 @@ public abstract class ColorSpace { // A color space is wide-gamut if its area is >90% of NTSC 1953 and // if it entirely contains the Color space definition in xyY - mIsWideGamut = isWideGamut(primaries, min, max); - mIsSrgb = isSrgb(primaries, whitePoint, oetf, eotf, min, max, id); + mIsWideGamut = isWideGamut(mPrimaries, min, max); + mIsSrgb = isSrgb(mPrimaries, mWhitePoint, oetf, eotf, min, max, id); } /** @@ -2450,7 +2522,7 @@ public abstract class ColorSpace { * If the conditions above are not met, the color space is considered as having * a wide color gamut if its range is larger than [0..1]. * - * @param primaries RGB primaries in CIE xyY or XYZ as an array of 6 or 9 floats + * @param primaries RGB primaries in CIE xyY as an array of 6 floats * @param min The minimum value of the color space's range * @param max The minimum value of the color space's range * @return True if the color space has a wide gamut, false otherwise @@ -2458,7 +2530,7 @@ public abstract class ColorSpace { * @see #isWideGamut() * @see #area(float[]) */ - private static boolean isWideGamut(@NonNull @Size(min = 6, max = 9) float[] primaries, + private static boolean isWideGamut(@NonNull @Size(6) float[] primaries, float min, float max) { return (area(primaries) / area(NTSC_1953_PRIMARIES) > 0.9f && contains(primaries, SRGB_PRIMARIES)) || (min < 0.0f && max > 1.0f); @@ -2643,7 +2715,7 @@ public abstract class ColorSpace { * @return A new array of 6 floats containing the primaries in xyY */ @NonNull - @Size(2) + @Size(6) private static float[] xyPrimaries(@NonNull @Size(min = 6, max = 9) float[] primaries) { float[] xyPrimaries = new float[6]; @@ -2818,7 +2890,7 @@ public abstract class ColorSpace { private Connector( @NonNull ColorSpace source, @NonNull ColorSpace destination, @NonNull ColorSpace transformSource, @NonNull ColorSpace transformDestination, - @NonNull RenderIntent intent, @NonNull @Size(3) float[] transform) { + @NonNull RenderIntent intent, @Nullable @Size(3) float[] transform) { mSource = source; mDestination = destination; mTransformSource = transformSource; @@ -2938,13 +3010,12 @@ public abstract class ColorSpace { /** * Optimized connector for RGB->RGB conversions. */ - private static class RGB extends Connector { + private static class Rgb extends Connector { @NonNull private final ColorSpace.Rgb mSource; @NonNull private final ColorSpace.Rgb mDestination; @NonNull private final float[] mTransform; - RGB(@NonNull ColorSpace.Rgb source, - @NonNull ColorSpace.Rgb destination, + Rgb(@NonNull ColorSpace.Rgb source, @NonNull ColorSpace.Rgb destination, @NonNull RenderIntent intent) { super(source, destination, source, destination, intent, null); mSource = source;