Overview.bs

<h1>CSS Timing Functions Level 1</h1>

<pre class=metadata>
Status: ED
Work Status: Refining
Shortname: css-timing
Level: 1
Group: csswg
ED: https://drafts.csswg.org/css-timing/
Editor: Brian Birtles 43194, Mozilla https://www.mozilla.org, bbirtles@mozilla.com
Editor: Dean Jackson, Apple Inc https://www.apple.com/, dino@apple.com
Editor: Matt Rakow, Microsoft
Editor: Shane Stephens 47691, Google Inc, shans@google.com
Repository: w3c/csswg-drafts
!Issue Tracking: <a href="https://github.com/w3c/csswg-drafts/labels/css-timing-1">GitHub</a>

Abstract: This CSS module describes a way for authors to define a transformation
    to be applied to the time of an animation. This can be used to produce
    animations that mimic physical phenomena such as momentum or to
    cause the animation to move in discrete steps producing robot-like
    movement.
</pre>

<pre class=biblio>
{
  "FUND-COMP-GRAPHICS": {
    "title": "Fundamentals of Computer Graphics",
    "authors": [
      "Peter Shirley",
      "Michael Ashikhmin",
      "Steve Marschner"
    ],
    "date": "2009",
    "publisher": "A K Peters Limited"
  }
}
</pre>

Introduction {#introduction}
============================

<em>This section is not normative.</em>

It is often desirable to control the rate at which an animation progresses.
For example, gradually increasing the speed at which an element moves can
give the element a sense of weight as it appears to gather momentum.
This can be used to produce user intuitive interface elements or convincing
cartoon props that behave like their physical counterparts.
Alternatively, it is sometimes desirable for animation to move forwards in
distinct steps such as a segmented wheel that rotates such that the segments
always appear in the same position.

[=Timing functions=] provide a means to transform animation time by taking an
input progress value and producing a corresponding transformed output progress
value.

<figure>
  <img src="timing-function-example.svg" width="350"
    alt="Example of a timing function that produces an ease-in effect.">
  <figcaption>
    Example of a timing function that produces an ease-in effect.
    Given an input progress of 0.7, the timing function scales the
    value to produce an output progress of 0.52.
    By applying this timing function, the animation will progress more
    slowly at first but then gradually progress more quickly.
  </figcaption>
</figure>

Timing functions {#timing-functions}
====================================

A <dfn export>timing function</dfn> takes an [=input progress value=] and
produces an [=output progress value=].

A [=timing function=] must be a pure function meaning that for a given set of
inputs, it always produces the same [=output progress value=].

The <dfn>input progress value</dfn> is a real number in the range [-&infin;,
&infin;].
Typically, the [=input progress value=] is in the range [0, 1] but this may
not be the case when [=timing functions=] are chained together.

The <dfn>output progress value</dfn> is a real number in the
range [-&infin;, &infin;].

Some types of timing function also take an additional boolean [=before flag=]
input which is defined subsequently.

This specification defines three types of timing functions whose definitions
follow.


The linear timing function {#linear-timing-function-section}
--------------------------

The <dfn export>linear timing function</dfn> is an identity function
meaning that its [=output progress value=] is equal to the
[=input progress value=] for all inputs.

The syntax for the [=linear timing function=] is simply the
<dfn for=single-timing-function>''linear''</dfn> keyword.


Cubic B&eacute;zier timing functions {#cubic-bezier-timing-functions}
---------------------------------------------------------------------

A <dfn export>cubic B&eacute;zier timing function</dfn> is a type of [=timing
function=] defined by four real numbers that specify the two control
points, <var>P1</var> and <var>P2</var>, of a cubic B&eacute;zier curve whose
end points <var ignore>P0</var> and <var ignore>P3</var> are fixed at (0, 0) and
(1, 1) respectively.
The <var>x</var> coordinates of <var>P1</var> and <var>P2</var> are
restricted to the range [0, 1].

The mapping from input progress to output progress is performed by
determining the corresponding <var>y</var> value ([=output progress value=]) for
a given <var>x</var> value ([=input progress value=]).
The evaluation of this curve is covered in many sources such as
[[FUND-COMP-GRAPHICS]].

<figure>
  <img src="cubic-bezier-timing-curve.svg" width="500"
      alt="A cubic Bezier curve used as a timing function.">
  <figcaption>
    A cubic B&eacute;zier curve used as a timing function.<br>
    The shape of the curve is determined by the location of the control
    points <var>P1</var> and <var>P2</var>.<br>
    Input progress values serve as <var>x</var> values of the curve,
    whilst the <var>y</var> values are the output progress values.
  </figcaption>
</figure>

For [=input progress values=] outside the range [0, 1], the curve is extended
infinitely using tangent of the curve at the closest endpoint as follows:

*   For [=input progress values=] less than zero,

    1.   If the <var>x</var> value of P1 is greater than zero, use
         a straight line that passes through P1 and P0 as the tangent.

    1.   Otherwise, if the <var>x</var> value of P2 is greater than
         zero, use a straight line that passes through P2 and P0 as the tangent.

    1.   Otherwise, let the [=output progress value=] be zero for all
         [=input progress values=] in the range [-&infin;, 0).

*   For [=input progress values=] greater than one,

    1.   If the <var>x</var> value of P2 is less than one, use
         a straight line that passes through P2 and P3 as the tangent.

    1.   Otherwise, if the <var>x</var> value of P1 is less than
         one, use a straight line that passes through P1 and P3 as the tangent.

    1.   Otherwise, let the [=output progress value=] be one for all
         [=input progress values=] in the range (1, &infin;].

A <a>cubic B&eacute;zier timing function</a> may be specified as a string
using the following syntax (using notation from [[!CSS3VAL]]):

<div class="prod"><dfn type>&lt;cubic-bezier-timing-function&gt;</dfn> =
  ''ease'' | ''ease-in'' | ''ease-out'' | ''ease-in-out'' |
  <span class="atom"><a lt="cubic-bezier()"
  function>cubic-bezier</a>(<<number>>, <<number>>, <<number>>,
  <<number>>)</span></div>

The meaning of each value is as follows:

<dl dfn-type="value" dfn-for="cubic-bezier-timing-function, <cubic-bezier-timing-function>">

:   <dfn>ease</dfn>
::  Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).
:   <dfn>ease-in</dfn>
::  Equivalent to cubic-bezier(0.42, 0, 1, 1).
:   <dfn>ease-out</dfn>
::  Equivalent to cubic-bezier(0, 0, 0.58, 1).
:   <dfn>ease-in-out</dfn>
::  Equivalent to cubic-bezier(0.42, 0, 0.58, 1).
:   <dt><dfn function lt="cubic-bezier()">cubic-bezier(<<number>>, <<number>>, <<number>>, <<number>>)</dfn></dt>
::  Specifies a <a>cubic B&eacute;zier timing function</a>.
    The four numbers specify points <var>P1</var> and <var>P2</var> of
    the curve as (<var ignore>x1</var>, <var ignore>y1</var>, <var
    ignore>x2</var>, <var ignore>y2</var>).
    Both <var>x</var> values must be in the range [0, 1] or the definition is
    invalid.

</dl>

The keyword values listed above are illustrated below.

<figure>
  <img src="curve-keywords.svg" width="500"
      alt="The timing functions produced by keyword values.">
  <figcaption>
    The timing functions produced by each of cubic B&eacute;zier timing
    function keyword values.
  </figcaption>
</figure>


Step timing functions {#step-timing-functions}
---------------------

A <dfn>step timing function</dfn> is a type of <a>timing function</a>
that divides the input time into a specified number of intervals that
are equal in duration.

Some example step timing functions are illustrated below.

<figure>
  <img src="step-timing-func-examples.svg" width="500"
      alt="Example step timing functions.">
  <figcaption>
    Example step timing functions.
    In each case the domain is the input progress whilst the range
    represents the output progress produced by the step function.<br>
    The first row shows the function for each transition point when only
    one step is specified whilst the second row shows the same for three
    steps.
  </figcaption>
</figure>

A [=step timing function=] is defined by a non-zero positive number of
<dfn>steps</dfn>, and a <dfn>step position</dfn> property that may be either
<a value for="steps()">start</a> or <a value for="steps()">end</a>.

At the exact point where a step occurs the result of the function is
conceptually the top of the step. However, an additional <dfn>before flag</dfn>
passed as input to the [=step timing function=], if true, will cause the
result of the function to correspond to the bottom of the step at the step
point.

The [=output progress value=] is calculated from the [=input progress value=]
and [=before flag=] as follows:

1.   Calculate the <var>current step</var> as <code>floor([=input progress
     value=] &times; [=steps=])</code>.

1.   If the [=step position=] property is <a value for="steps()">start</a>,
     increment <var>current step</var> by one.

1.   If <em>both</em> of the following conditions are true:

     *   the [=before flag=] is set, <em>and</em>
     *   [=input progress value=] &times; [=steps=] mod 1 equals zero
         (that is, if [=input progress value=] &times; [=steps=] is
         integral), then

     decrement <var>current step</var> by one.

1.   The [=output progress value=] is <code><var>current step</var>
     / [=steps=]</code>.

<div class=example>

As an example of how the [=before flag=] affects the behavior of this function,
consider an animation with a [=step timing function=] whose [=step
position=] is <a value for="steps()">start</a> and which has a positive
delay and backwards fill.

For example, using CSS animation:

<pre class='lang-css'>
animation: moveRight 5s 1s steps(5, start);
</pre>

During the delay phase, the [=input progress value=] will be zero but if the
[=before flag=] is set to indicate that the animation has yet to reach its
animation interval, the timing function will produce zero as its [=output
progress value=], i.e. the bottom of the first step.

At the exact moment when the animation interval begins, the [=input progress
value=] will still be zero, but the [=before flag=] will not be set and hence
the result of the timing function will correspond to the top of the first step.

</div>

The syntax for specifying a step timing function is as follows:

<div class="prod"><dfn type>&lt;step-timing-function&gt;</dfn> =
  ''step-start'' | ''step-end'' |
  <span class="atom"><a lt="steps()" function>steps</a>(<<integer>>[,
                          [ ''start'' | ''end'' ] ]?)</span></div>

The meaning of each value is as follows:

<dl dfn-type=value dfn-for="step-timing-function, <step-timing-function>">

:   <dfn>step-start</dfn>
::  Equivalent to steps(1, start);
:   <dfn>step-end</dfn>
::  Equivalent to steps(1, end);
:   <dfn function lt="steps()">steps(&lt;integer&gt;[, [ start | end ] ]?)</dfn>
::  Specifies a <a>step timing function</a>.
    The first parameter specifies the number of intervals in the function.
    It must be a positive integer greater than 0.
    The second parameter, which is optional, is
    either the value <dfn value for="steps()">start</dfn> or <dfn value
    for="steps()">end</dfn>, and specifies the [=step position=].
    If the second parameter is omitted, it is given the value ''end''.

</dl>

The &lt;single-timing-function&gt; production {#single-timing-function-production}
=============================================

The syntax for specifying a [=timing function=] is as follows:

<div class="prod"><dfn type>&lt;single-timing-function&gt;</dfn> =
  ''linear'' |
  <<cubic-bezier-timing-function>> |
  <<step-timing-function>></div>

Serialization {#serializing-a-timing-function}
-------------

Timing functions are serialized using the common serialization patterns
defined in [[CSSOM]] with the following additional requirements:

*   The keyword values ''ease'', ''linear'', ''ease-in'', ''ease-out'',
    and ''ease-in-out'' are serialized as-is, that is, they are
    <em>not</em> converted to the equivalent ''cubic-bezier()''
    function before serializing.

*   Step timing functions, whether they are specified using the
    ''steps()'' function or either of the ''step-start'' or ''step-end''
    keywords, are serialized as follows:

    1.   If the [=step position=] is ''end'', serialize
         as <a lt="steps()" function>steps(&lt;integer&gt;)</a>.

    2.   Otherwise, serialize as <a lt="steps()"
         function>steps(&lt;integer&gt;, start)</a>.