test & doc for SkUnitCubicInterp

R=reed@google.com
BUG=skia:959
GOLD_TRYBOT_URL= https://gold.skia.org/search2?unt=true&query=source_type%3Dgm&master=false&issue=1562333002

Review URL: https://codereview.chromium.org/1562333002

2 files changed, 40 insertions, 2 deletions

diff --git a/include/utils/SkInterpolator.h b/include/utils/SkInterpolator.h
index 9547cec8b2..e062b38f65 100644
--- a/include/utils/SkInterpolator.h
+++ b/include/utils/SkInterpolator.h
@@ -121,8 +121,15 @@ private:
     typedef SkInterpolatorBase INHERITED;
 };
 
-/** Given all the parameters are [0...1], apply the cubic specified by (0,0)
-    (bx,by) (cx,cy) (1,1) to value, returning the answer, also [0...1].
+/** Interpolate a cubic curve, typically to provide an ease-in ease-out transition.
+    All the parameters are in the range of [0...1].
+    The input value is treated as the x-coordinate of the cubic.
+    The output value is the y-coordinate on the cubic at the x-coordinate.
+
+    @param value        The x-coordinate pinned between [0..1].
+    @param bx,by,cx,cy  The cubic control points where the cubic is specified
+                        as (0,0) (bx,by) (cx,cy) (1,1)
+    @return             the corresponding y-coordinate value, from [0..1].
 */
 SkScalar SkUnitCubicInterp(SkScalar value, SkScalar bx, SkScalar by,
                            SkScalar cx, SkScalar cy);
diff --git a/tests/InterpolatorTest.cpp b/tests/InterpolatorTest.cpp
index 3cfd19f56b..f520ebb700 100644
--- a/tests/InterpolatorTest.cpp
+++ b/tests/InterpolatorTest.cpp
@@ -58,4 +58,35 @@ DEF_TEST(Interpolator, reporter) {
     result = inter.timeToValues(175, v);
     REPORTER_ASSERT(reporter, result == SkInterpolator::kNormal_Result);
 
+    for (SkScalar val = -0.1f; val <= 1.1f; val += 0.1f) {
+        REPORTER_ASSERT(reporter, SkScalarNearlyEqual(SkTPin(0.f, val, 1.f),
+                        SkUnitCubicInterp(val, 1.f/3, 1.f/3, 2.f/3, 2.f/3)));
+    }
+
+    // These numbers come from
+    // http://www.w3.org/TR/css3-transitions/#transition-timing-function_tag.
+    const SkScalar testTransitions[][4] = {
+        { 0.25f, 0.1f, 0.25f, 1 }, // ease
+        { 0.42f, 0,    1,     1 }, // ease in
+        { 0,     0,    0.58f, 1 }, // ease out
+        { 0.42f, 0,    0.58f, 1 }, // ease in out
+    };
+
+    const SkScalar expectedOutput[][5] = {
+        { 0.0947876f, 0.513367f, 0.80249f,  0.940796f, 0.994263f }, // ease
+        { 0.0170288f, 0.129639f, 0.31543f,  0.554749f, 0.839417f }, // ease in
+        { 0.160583f,  0.445251f, 0.684692f, 0.870361f, 0.982971f }, // ease out
+        { 0.0197144f, 0.187439f, 0.500122f, 0.812561f, 0.980286f }, // ease in out
+    };
+
+    int i = 0;
+    for (const SkScalar* t : testTransitions) {
+        int j = 0;
+        for (SkScalar val = 0.1f; val < 1; val += 0.2f) {
+            REPORTER_ASSERT(reporter, SkScalarNearlyEqual(expectedOutput[i][j++],
+                            SkUnitCubicInterp(val, t[0], t[1], t[2], t[3])));
+        }
+        ++i;
+        SkDebugf("\n");
+    }
 }