Calculating progress & serialising linear-spline

css-easing-2/Overview.bs

@@ -7,10 +7,12 @@ Level: 2
 Group: csswg
 ED: https://drafts.csswg.org/css-easing/
 TR: https://www.w3.org/TR/css-easing-2/
+Editor: Jake Archibald, Google, jakearchibald@google.com, w3cid 76394
 Editor: Brian Birtles, Mozilla https://www.mozilla.org/, bbirtles@mozilla.com, w3cid 43194
 Editor: Dean Jackson, Apple Inc https://www.apple.com/, dino@apple.com, w3cid 42080
 Editor: Matt Rakow, Microsoft, w3cid 62267
 Former Editor: Shane Stephens, Google, shans@google.com, w3cid 47691
+Markup Shorthands: markdown yes
 
 Abstract: This CSS module describes a way for authors to define a transformation
     that controls the rate of change of some value.
@@ -121,7 +123,6 @@ The syntax for specifying an [=easing function=] is as follows:
   <<cubic-bezier-easing-function>> |
   <<step-easing-function>></div>
 
-
 <h3 id=the-linear-easing-function oldids=linear-timing-function-section>The linear easing function: ''linear''</h3>
 
 The <dfn export lt="linear easing function|linear timing function">linear easing
@@ -132,6 +133,111 @@ meaning that its [=output progress value=] is equal to the
 The syntax for the [=linear easing function=] is simply the
 <dfn dfn-type=value for=easing-function>linear</dfn> keyword.
 
+<h3 id=the-linear-spline-easing-function>The linear spline easing function: ''linear-spline()''</h3>
+
+A <dfn export>linear spline easing function</dfn>
+is an easing function
+that interpolates linearly
+between its [=linear spline easing function/points=].
+
+A [=linear spline easing function=] has:
+
+<dl dfn-for="linear spline easing function">
+
+:   <dfn>points</dfn>
+::  a [=/list=] of [=linear spline easing points=].
+    Initially a new empty [=/list=].
+
+:   <dfn>serializable points</dfn>
+::  a [=/list=] of [=linear spline easing points=].
+    Initially a new empty [=/list=].
+
+    Note: This is only used for producing a computed value.
+
+</dl>
+
+A <dfn>linear spline easing point</dfn>
+is a [=/struct=]
+that has:
+
+<dl dfn-for="linear spline easing point">
+
+: <dfn>input</dfn>
+:: A number or null
+
+: <dfn>output</dfn>
+:: A number
+
+</dl>
+
+<section algorithm="linear spline easing function">
+
+To get a [=linear spline easing function=]'s (|linearSplineEasingFunction|) <dfn for="linear spline easing function" export>computed value</dfn>
+perform the following.
+It returns a [=string=].
+
+1.   Let |output| be "`linear-spline(`".
+
+1.   [=list/For each=] |point| in |linearSplineEasingFunction|'s [=linear spline easing function/serializable points=]:
+
+     1.   If |point| is not the first [=list/item=] of |linearSplineEasingFunction|'s [=linear spline easing function/points=],
+          append "<code>, </code>" to |output|.
+
+     1.   Append the computed value of |point|'s [=linear spline easing point/output=],
+          as a <<number>>,
+          to |output|.
+
+     1.   If |point|'s [=linear spline easing point/input=] is not null, append "<code> </code>"
+          followed by the computed value of |point|'s [=linear spline easing point/input=],
+          as a <<percentage>>
+          to |output|.
+
+1.   Append "`)`" to |output|.
+
+1.   Return |output|.
+
+</section>
+
+<section algorithm="to calculate linear spline output progress">
+
+To <dfn export>calculate linear spline output progress</dfn>
+for a given [=linear spline easing function=] |linearSplineEasingFunction|,
+and an [=input progress value=] |inputProgress|,
+perform the following.
+It returns an [=output progress value=].
+
+Note: TODO explain this with diagrams
+
+1.   Let |points| be |linearSplineEasingFunction|'s [=linear spline easing function/points=].
+
+1.   Let |pointAIndex| be the last [=list/item=] in |points| with an [=linear spline easing point/input=] less than or equal to |inputProgress|,
+     or 0 if there is no match.
+
+1.   If |pointAIndex| is equal to |points| [=list/size=] minus 1,
+     decrement |pointAIndex| by 1.
+
+     Note: This ensures we have a next [=linear spline easing point|point=] to compare to.
+
+1.   Let |pointA| be |points|[pointAIndex].
+
+1.   Let |pointB| be |points|[pointAIndex + 1].
+
+1.   If |pointA|'s [=linear spline easing point/input=] is equal to |pointB|'s [=linear spline easing point/input=],
+     return |pointB|'s [=linear spline easing point/output=].
+
+1.   Let |progressFromPointA| be |inputProgress| minus |pointA|'s [=linear spline easing point/input=].
+
+1.   Let |pointInputRange| be |pointB|'s [=linear spline easing point/input=] minus |pointA|'s [=linear spline easing point/input=].
+
+1.   Let |progressBetweenPoints| be |progressFromPointA| divided by |pointInputRange|.
+
+1.   Let |pointOutputRange| be |pointB|'s [=linear spline easing point/output=] minus |pointA|'s [=linear spline easing point/output=].
+
+1.   Let |outputFromLastPoint| be |progressBetweenPoints| multiplied by |pointOutputRange|.
+
+1.   Return |pointA|'s [=linear spline easing point/output=] plus |outputFromLastPoint|.
+
+</section>
 
 <h3 id=cubic-bezier-easing-functions oldids=cubic-bezier-timing-functions>Cubic
 B&eacute;zier easing functions: