Polish gradient docs

Enhance gradient description
Use stop terminology
Add more playground examples

docs/specs/constants.md

@@ -139,3 +139,15 @@
 {schema_string:constants/gradient-type/description}
 
 {schema_enum:gradient-type}
+
+<lottie-playground example="gradient.json">
+    <title>Example</title>
+    <form>
+        <enum title="Type" value="1">gradient-type</enum>
+    </form>
+    <json>lottie.layers[1].shapes[0].it[1]</json>
+    <script>
+    var gradient = lottie.layers[1].shapes[0].it[1];
+    gradient.t = Number(data["Type"]);
+    </script>
+</lottie-playground>

docs/specs/shapes.md

@@ -506,8 +506,19 @@ $$
     gradient.s.k = start_marker.p.k = [data["Start X"], data["Start Y"]];
     gradient.e.k = end_marker.p.k = [data["End X"], data["End Y"]];
     gradient.t = Number(data["Type"]);
-    gradient.h.k = data["Highlight"];
-    gradient.a.k = data["Highlight Angle"];
+    if (gradient.t === 2) {
+        gradient.h = {
+            a: 0, 
+            k: data["Highlight"]
+        };
+        gradient.a = {
+            a: 0, 
+            k: data["Highlight Angle"]
+        };
+    } else {
+        delete gradient.h;
+        delete gradient.a;
+    }
     </script>
 </lottie-playground>
 
@@ -517,6 +528,41 @@ $$
 
 {schema_object:shapes/gradient-stroke}
 
+<lottie-playground example="gradient-stroke.json">
+    <title>Example</title>
+    <form>
+        <input title="Start X" type="range" min="0" max="512"  value="256"/>
+        <input title="Start Y" type="range" min="0" max="512"  value="496"/>
+        <input title="End X" type="range" min="0" max="512"  value="256"/>
+        <input title="End Y" type="range" min="0" max="512"  value="16"/>
+        <enum title="Type" value="1">gradient-type</enum>
+        <input title="Highlight" type="range" min="0" max="100"  value="0"/>
+        <input title="Highlight Angle" type="range" min="0" max="360"  value="0"/>
+    </form>
+    <json>lottie.layers[1].shapes[1]</json>
+    <script>
+    var gradient = lottie.layers[1].shapes[1];
+    var start_marker = lottie.layers[0].shapes[1].it[1];
+    var end_marker = lottie.layers[0].shapes[0].it[1];
+    gradient.s.k = start_marker.p.k = [data["Start X"], data["Start Y"]];
+    gradient.e.k = end_marker.p.k = [data["End X"], data["End Y"]];
+    gradient.t = Number(data["Type"]);
+    if (gradient.t === 2) {
+        gradient.h = {
+            a: 0, 
+            k: data["Highlight"]
+        };
+        gradient.a = {
+            a: 0, 
+            k: data["Highlight Angle"]
+        };
+    } else {
+        delete gradient.h;
+        delete gradient.a;
+    }
+    </script>
+</lottie-playground>
+
 <h2 id="modifier">Modifiers</h2>
 
 {schema_string:shapes/modifier/description}

docs/specs/values.md

@@ -33,15 +33,12 @@ RGB component.
 
 <h2 id="gradient">Gradient</h2>
 
-{schema_string:values/gradient/description}
+The gradient appearance is specified in terms of color stops and opacity stops.
+Color stops are defined as `(position, color)` tuples, where the position is a normalized `[0..1]`value along the gradient axis `[startpoint -> endpoint]`, and the color is 3 floats representing the RGB components. Transparency (opacity) stops are defined as `(position, color)` tuples, where position is similar to color stops' position.
 
-The count of color components is typically specified in a separate field from
-the gradient values. Any remaining values after reaching the specified count of
-color components are transparency components.
+All color and opacity stops are stored sequentially by ascending offsets in a flattened float array (color stops followed by opacity stops), with 4 floats per color stop and 2 floats per opacity stops. Thus, given color stops and opacity stops, the expected size for the gradient data array is `4 * Nc + 2 * No`.
 
-The offset is expressed as a percentage between start (0) and end (1).
-
-Components must be arranged in ascending offset order. 
+The color stop count is typically specified in a separate field from the gradient values, while the count of opacity stops can be inferred from the data array length: `No = (length - 4 * Nc)/2`.
 
 <h3>Gradient without transparency</h3>
 
@@ -72,8 +69,8 @@ the array will look like the following:
 
 <h3>Gradient with transparency</h3>
 
-Transparency components are added at the end. Transparency components may or may
-not match the count and offset of color components.
+Transparency stops are added at the end. Transparency stops may or may
+not match the count and offset of color stops.
 
 So assume the same colors as before, but opacity of 80% for the first color and 100% for the other two.