Document two special cases of NewColorTransform()

Officially document the two special cases of
gfx::ColorTransform::NewColorTransform(): the source color space is
invalid, or the target color space is invalid. I discovered them while
reading the source code, and found that they are enforced by unit tests.
I am interested in relying on the second special case for YUV to RGB
color conversion. So I'd like to document the special cases officially.

Also some minor test cleanup.

Tested:
gfx_unittests --gtest_filter=SimpleColorSpace.ToUndefined

Change-Id: Ie80948dc8bf1677d7f7fbd69e78790d3e45df76d
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2211127Reviewed-by: Dale Curtis <dalecurtis@chromium.org>
Reviewed-by: ccameron <ccameron@chromium.org>
Commit-Queue: Wan-Teh Chang <wtc@google.com>
Cr-Commit-Position: refs/heads/master@{#771970}

ui/gfx/color_transform.h

@@ -44,9 +44,15 @@ class GFX_EXPORT ColorTransform {
 
   virtual size_t NumberOfStepsForTesting() const = 0;
 
+  // Two special cases:
+  // 1. If no source color space is specified (i.e., src.IsValid() is false), do
+  // no transformation.
+  // 2. If the target color space is not defined (i.e., dst.IsValid() is false),
+  // just apply the range adjust and inverse transfer matrices. This can be used
+  // for YUV to RGB color conversion.
   static std::unique_ptr<ColorTransform> NewColorTransform(
-      const ColorSpace& from,
-      const ColorSpace& to,
+      const ColorSpace& src,
+      const ColorSpace& dst,
       Intent intent);
 
  private:

ui/gfx/color_transform_unittest.cc

@@ -388,6 +388,12 @@ TEST(SimpleColorSpace, ToUndefined) {
       ColorTransform::NewColorTransform(
           video, null, ColorTransform::Intent::INTENT_PERCEPTUAL));
   EXPECT_EQ(video_to_null->NumberOfStepsForTesting(), 1u);
+  // Without optimization, video should have 2 steps: limited range to full
+  // range, and YUV to RGB.
+  std::unique_ptr<ColorTransform> video_to_null_no_opt(
+      ColorTransform::NewColorTransform(video, null,
+                                        ColorTransform::Intent::TEST_NO_OPT));
+  EXPECT_EQ(video_to_null_no_opt->NumberOfStepsForTesting(), 2u);
 
   // Test with an ICC profile that can't be represented as matrix+transfer.
   ColorSpace luttrcicc = ICCProfileForTestingNoAnalyticTrFn().GetColorSpace();
@@ -412,15 +418,15 @@ TEST(SimpleColorSpace, ToUndefined) {
   EXPECT_GT(adobeicc_to_nonnull->NumberOfStepsForTesting(), 0u);
 
   // And with something analytic.
-  ColorSpace srgb = gfx::ColorSpace::CreateXYZD50();
-  std::unique_ptr<ColorTransform> srgb_to_null(
+  ColorSpace xyzd50 = gfx::ColorSpace::CreateXYZD50();
+  std::unique_ptr<ColorTransform> xyzd50_to_null(
       ColorTransform::NewColorTransform(
-          srgb, null, ColorTransform::Intent::INTENT_PERCEPTUAL));
-  EXPECT_EQ(srgb_to_null->NumberOfStepsForTesting(), 0u);
-  std::unique_ptr<ColorTransform> srgb_to_nonnull(
+          xyzd50, null, ColorTransform::Intent::INTENT_PERCEPTUAL));
+  EXPECT_EQ(xyzd50_to_null->NumberOfStepsForTesting(), 0u);
+  std::unique_ptr<ColorTransform> xyzd50_to_nonnull(
       ColorTransform::NewColorTransform(
-          srgb, nonnull, ColorTransform::Intent::INTENT_PERCEPTUAL));
-  EXPECT_GT(srgb_to_nonnull->NumberOfStepsForTesting(), 0u);
+          xyzd50, nonnull, ColorTransform::Intent::INTENT_PERCEPTUAL));
+  EXPECT_GT(xyzd50_to_nonnull->NumberOfStepsForTesting(), 0u);
 }
 
 TEST(SimpleColorSpace, DefaultToSRGB) {