Add images to document built-in color spaces
Bug: 32984164
Test: make offline-sdk-referenceonly-docs and manual validation of output
Change-Id: I2f0e00e5a0581517bb7c535e8aee150f87ac7a6e
diff --git a/Android.mk b/Android.mk
index 552103d..514ed47 100644
--- a/Android.mk
+++ b/Android.mk
@@ -1129,7 +1129,9 @@
-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 0000000..efafe5c
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_aces.png
Binary files 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 0000000..55f6ab5
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_acescg.png
Binary files 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 0000000..cb7d602
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_adobe_rgb.png
Binary files 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 0000000..34a3853
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_bt2020.png
Binary files 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 0000000..ba637f5
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_bt709.png
Binary files 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 0000000..19144e7
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_dci_p3.png
Binary files 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 0000000..a86c60a
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_display_p3.png
Binary files 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 0000000..bce93da
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_ntsc_1953.png
Binary files 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 0000000..74c95be
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_pro_photo_rgb.png
Binary files 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 0000000..2351b8e
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_scrgb.png
Binary files 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 0000000..360bb73
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_smpte_c.png
Binary files 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 0000000..ba637f5
--- /dev/null
+++ b/docs/html/reference/images/graphics/colorspace_srgb.png
Binary files differ
diff --git a/graphics/java/android/graphics/ColorSpace.java b/graphics/java/android/graphics/ColorSpace.java
index d114deb..4f2465f 100644
--- a/graphics/java/android/graphics/ColorSpace.java
+++ b/graphics/java/android/graphics/ColorSpace.java
@@ -19,6 +19,7 @@
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 @@
* ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3);
* </pre>
*
+ * <p>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.</p>
+ *
* @see ColorSpace#get(Named)
*/
public enum Named {
@@ -240,6 +246,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" />
+ * <figcaption style="text-align: center;">sRGB</figcaption>
+ * </p>
*/
SRGB,
/**
@@ -263,6 +273,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" />
+ * <figcaption style="text-align: center;">sRGB</figcaption>
+ * </p>
*/
LINEAR_SRGB,
/**
@@ -298,6 +312,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([-0.5..7.5[\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" />
+ * <figcaption style="text-align: center;">Extended RGB (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
EXTENDED_SRGB,
/**
@@ -321,6 +339,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([-0.5..7.5[\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" />
+ * <figcaption style="text-align: center;">Extended RGB (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
LINEAR_EXTENDED_SRGB,
/**
@@ -352,6 +374,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_bt709.png" />
+ * <figcaption style="text-align: center;">BT.709</figcaption>
+ * </p>
*/
BT709,
/**
@@ -383,6 +409,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_bt2020.png" />
+ * <figcaption style="text-align: center;">BT.2020 (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
BT2020,
/**
@@ -406,6 +436,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_dci_p3.png" />
+ * <figcaption style="text-align: center;">DCI-P3 (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
DCI_P3,
/**
@@ -437,6 +471,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_display_p3.png" />
+ * <figcaption style="text-align: center;">Display P3 (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
DISPLAY_P3,
/**
@@ -468,6 +506,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_ntsc_1953.png" />
+ * <figcaption style="text-align: center;">NTSC 1953 (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
NTSC_1953,
/**
@@ -499,6 +541,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_smpte_c.png" />
+ * <figcaption style="text-align: center;">SMPTE-C (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
SMPTE_C,
/**
@@ -522,6 +568,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_adobe_rgb.png" />
+ * <figcaption style="text-align: center;">Adobe RGB (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
ADOBE_RGB,
/**
@@ -553,6 +603,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([0..1]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_pro_photo_rgb.png" />
+ * <figcaption style="text-align: center;">ProPhoto RGB (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
PRO_PHOTO_RGB,
/**
@@ -576,6 +630,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([-65504.0, 65504.0]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_aces.png" />
+ * <figcaption style="text-align: center;">ACES (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
ACES,
/**
@@ -599,6 +657,10 @@
* </tr>
* <tr><td>Range</td><td colspan="4">\([-65504.0, 65504.0]\)</td></tr>
* </table>
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_acescg.png" />
+ * <figcaption style="text-align: center;">ACEScg (orange) vs sRGB (white)</figcaption>
+ * </p>
*/
ACESCG,
/**
@@ -1110,7 +1172,7 @@
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 @@
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 @@
* primaries and white point in the CIE XYZ space. The tristimulus XYZ values
* are internally converted to xyY.</p>
*
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_srgb.png" />
+ * <figcaption style="text-align: center;">sRGB primaries and white point</figcaption>
+ * </p>
+ *
* <h3>Transfer functions</h3>
* <p>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 @@
* range \([-0.5..7.5]\) while {@link Named#ACES ACES} can be used throughout
* the range \([-65504, 65504]\).</p>
*
+ * <p>
+ * <img src="{@docRoot}reference/android/images/graphics/colorspace_scrgb.png" />
+ * <figcaption style="text-align: center;">Extended sRGB and its large range</figcaption>
+ * </p>
+ *
* <h3>Converting between RGB color spaces</h3>
* <p>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 @@
@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 @@
// 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 @@
* 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 @@
* @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 @@
* @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 @@
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 @@
/**
* 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;
