diff --git a/web-animations-1/Overview.bs b/web-animations-1/Overview.bs index 7512553e1aa..375b5929327 100644 --- a/web-animations-1/Overview.bs +++ b/web-animations-1/Overview.bs @@ -2465,15 +2465,36 @@ Animation effects {#animation-effects} An animation effect is a [=timing node=] that provides a static description of some timed behavior. -### Relationship between animation effects and animations ### {#animation-effects-and-animations} + All [=animation effects=] have the following properties: + * an [=active interval=], + determined by its [=start delay=] and [=active duration=], + defining the time interval during which its behavior takes effect + * an [=iteration duration=], [=iteration count=], and [=iteration start=] + defining how its behavior repeats within that interval + * a [=playback direction=] applying to each iteration, + to allow reversing the timing of effects within an iteration + * a [=fill mode=] defining the application of effects + [=before phase|before=]/[=after phase|after=] its [=active interval=] + * optionally, an [=animation effect/associated animation=] + and through it, optionally, an [=associated with a timeline|associated timeline=], + which cause the [=animation effect=] to apply its behavior + by driving its [=local time|local time value=] - The [=associated effect=] of an [=animation=], if set, - is a type of [=animation effect=]. - The [=associated effect=] of an [=animation=] - is said to be associated - with that animation. +### Types of animation effects ### {#types-of-animation-effects} + + This specification defines a single type of [=animation effect=]: + [=keyframe effects=]. + Subsequent levels of this specification + will define further types of [=animation effects=]. + +### Associated animation and timeline ### {#animation-effects-and-animations} + + An [=animation effect=] is + associated with an animation + when the effect is that animation’s [=associated effect=]. At a given moment, - an [=animation effect=] can be [=associated with an animation|associated=] + an [=animation effect=] can be [=associated animation|associated=] with at most one [=animation=]. An [=animation effect=], |effect|, @@ -2481,107 +2502,186 @@ Animation effects {#animation-effects} if |effect| is [=associated with an animation=] which, in turn, is associated with |timeline|. -### Types of animation effects ### {#types-of-animation-effects} +### Local time ### {#local-time-section} - This specification defines a single type of [=animation effect=]: - [=keyframe effects=]. - Subsequent levels of this specification - will define further types of [=animation effects=]. + The local time of an [=animation effect=] + represents the [=animation/current time=] + provided by its [=associated animation=], + determining the progress of the [=animation effect=]. + At a given moment, + it is based on the first matching condition below: + +
- All types of [=animation effects=] - define a number of common properties - which are described in the following sections. + : If the [=animation effect=] is [=associated with an animation=], + :: + the [=local time=] is the [=animation/current time=] of the [=animation=]. -### The active interval ### {#the-active-interval} + : Otherwise, + :: + the [=local time=] is [=unresolved=]. + +
+ +### Time spaces ### {#effect-time-spaces}
+This section is non-normative - The period that an [=animation effect=] is scheduled to run - is called its [=active interval=]. - Each [=animation effect=] has only one such interval. + In Web Animations all times are relative to some point of reference. + These different points of reference produce different time spaces. - The lower bound of the [=active interval=] typically corresponds - to the [=start time=] of - the [=animation=] associated with this [=animation effect=], - but can be shifted by a [=start delay=] on the [=animation effect=]. + This can be compared to coordinate spaces + as used in computer graphics. + The zero time of a [=time space=] is analogous + to the origin of a coordinate space. - The upper bound of the interval is determined - by the [=active duration=]. + Within the [=Web Animations model=] + we define progress of an [=animation effect=] on the basis of its [=active time=], + which is a time relative to the beginning of its [=active interval=]-- + thus a time in the [=active time space=]. - The relationship between - the [=start time=], [=start delay=], and [=active duration=] - is illustrated below. + Note: This time space is internal to the model + and not exposed in the programming interface or in markup. + + We can further describe animations that repeat + as establishing a new [=time space=] + each time the animation repeats: + the [=iteration time space=]. + + The [=animation effect=] thus translates the [=animation/current time=] + provided by the [=associated animation=] + through a series of [=time spaces=]: + * the local time space, + relative to the [=start time=] of the [=associated animation=], + yielding the [=local time=] + * the active time space, + relative to the start of the [=active interval=], + yielding the [=active time=] + * the iteration time space, + relative to the start of the [=animation effect=]’s current iteration, + yielding the iteration time + + These time spaces are illustrated below.
- Examples of the effect of the start dela
-             on the endpoints of the active interval + A comparison of local time, active time, and iteration time.
+              Local time crosses zero at the start time of the animation,
+              and rises linearly.
+              Active time is zero until the start of the active interval,
+              at which point it rises linearly to the end time,
+              beyond which it remains at its maximum value.
+              Iteration time is likewise zero until the start of the active interval,
+              and rises linearly,
+              but restarts at zero at the start of every new iteration,
+              and remains at its halfway point from the end time onward.
- Examples of the effect of the [=start delay=] - on the endpoints of the [=active interval=].
- (a) An animation effect with no delay; - the [=start time=] and beginning of the [=active interval=] - are coincident.
- (b) An animation effect with a positive delay; - the beginning of the [=active interval=] - is deferred by the delay.
- (c) An animation effect with a negative delay; - the beginning of the [=active interval=] - is brought forward by the delay. + A comparison of [=local time=], [=active time=], and [=iteration time=] + for an animation with an [=iteration duration=] of 1s + and an [=iteration count=] of 2.5. + The [=animation/start time=] defined by the [=animation=] + and [=animation effect/end time=] defined by the [=animation effect=] + are also annotated.
- An [=end delay=] can also be specified - but is primarily only of use when sequencing animations. + In addition to these time spaces + we can also refer to the document time space, + which is time space of the [=time values=] + of the [=default document timeline=] of the {{Document}} + of the [=current global object=]. + Note: While the time spaces themselves are not bounded, + Web Animations defines [=active time=] and the [=iteration progress=] + such that they are clamped to a set range as shown in the diagram. + For example, whilst a time of -1 second + is a valid time in active time space, + the procedure for calculating the [=active time=] + defined in [[#calculating-the-active-time]] + will never return a negative value.
- [=Animation effects=] define an active interval +### The active interval ### {#the-active-interval} + + [=Animation effects=] define an active interval, which is the period of time during which the effect - is scheduled to produce its effect-- - with the exception of [=fill modes=], - which apply outside the [=active interval=]. + is scheduled to produce its effect + (excepting [=fill modes=], + which apply outside the [=active interval=]). + Each [=animation effect=] has only one such interval, + which is defined by its [=start delay=] and [=active duration=]. + +
+ + The relationship between + the [=start time=], [=start delay=], and [=active duration=] + is illustrated below. + +
+ Examples of the effect of the start dela
+               on the endpoints of the active interval +
+ Examples of the effect of the [=start delay=] + on the endpoints of the [=active interval=].
+ (a) An animation effect with no delay; + the [=start time=] and beginning of the [=active interval=] + are coincident.
+ (b) An animation effect with a positive delay; + the beginning of the [=active interval=] + is deferred by the delay.
+ (c) An animation effect with a negative delay; + the beginning of the [=active interval=] + is brought forward by the delay. +
+
+
+ +#### The start delay #### {#the-start-delay} The lower bound of the [=active interval=] - is defined by the [=start delay=]. + by default corresponds to the [=start time=] of the [=associated animation=], + but can be shifted by the start delay, + which is a signed offset from the [=start time=] of the [=animation=]. + +#### The active duration #### {#the-active-duration} + + The length of the [=active interval=] is called the active duration, + and is determined by the [=iteration duration=] and [=iteration count=] + as defined below. + Its length determines the upper bound of the [=active interval=]. + +
+ [=active duration=] = + iteration duration × iteration count +
+ + If either the [=iteration duration=] or [=iteration count=] are zero, + the [=active duration=] is zero. - The start delay of an [=animation effect=] - is a signed offset from the [=start time=] of the [=animation=] - with which the animation effect is associated. + Note: This clarification is needed + since the result of infinity multiplied by zero + is undefined according to IEEE 754-2008. - The length of the [=active interval=] is called the [=active duration=], - the calculation of which is defined in [[#calculating-the-active-duration]]. +#### The end delay and animation effect end time #### {#the-end-delay} Similar to the [=start delay=], an [=animation effect=] also has an end delay, - which is primarily of use when sequencing animations + which is primarily of use when sequencing one [=animation effect=] based on the [=end time=] of another [=animation effect=]. - Although this is typically only useful in combination with sequence effects - which are introduced in a subsequent level of this specification, - it is included here for the purpose of representing - the min - attribute in SVG ([[SVG11]], Chapter 19). - The end time of an [=animation effect=] + The end time, + of an [=animation effect=] is the result of evaluating max(start delay + active duration + end delay, 0). -### Local time ### {#local-time-section} - - The local time of an [=animation effect=] at a given moment - is based on the first matching condition from the following: - -
- - : If the [=animation effect=] is [=associated with an animation=], - :: - the [=local time=] is the [=animation/current time=] of the [=animation=]. - - : Otherwise, - :: - the [=local time=] is [=unresolved=]. - -
+ Note: Although the [=end delay=] is typically only useful + in combination with sequence effects + which are introduced in a subsequent level of this specification, + it is included here for the purpose of representing + the min + attribute in SVG ([[SVG11]], Chapter 19). ### Animation effect phases and states ### {#animation-effect-phases-and-states} @@ -2788,23 +2888,70 @@ Animation effects {#animation-effects} -Fill behavior {#fill-behavior} -------------- +### Fill behavior and fill modes ### {#fill-behavior} The effect of an [=animation effect=] when it is not [=in play=] is determined by its fill mode. + The effect of each [=fill mode=] is described below: + +
+ : none + :: + The animation effect has no effect when it is not [=in play=]. + + : forwards + :: + When the animation effect is in the [=animation effect/after phase=], + the animation effect will produce the same [=iteration progress=] value + as the last moment it is scheduled to be [=in play=]. + + For all other times that the animation effect is not [=in play=], + it will have no effect. + + : backwards + :: + When the animation effect is in the [=animation effect/before phase=], + the animation effect will produce the same [=iteration progress=] value + as the earliest moment that it is scheduled to be [=in play=]. - The possible [=fill modes=] are: + For all other times that the animation effect is not [=in play=], + it will have no effect. - * none, - * forwards, - * backwards, and - * both. + : both + :: + When the animation effect is in its [=animation effect/before phase=], + [=fill mode/backwards=] fill behavior is used. + + When the animation effect is in its [=animation effect/after phase=], + [=fill mode/forwards=] fill behavior is used. - The normative definition of these modes +
+ + The normative effect of these modes is incorporated in the calculation of the [=active time=] in [[#calculating-the-active-time]]. + Some examples of the these [=fill modes=] are illustrated below. + +
+ Examples of various fill modes and the states produced. +
+ Examples of various fill modes and the states produced.
+ (a) fill mode [=fill mode/none=]. + The animation effect has no effect outside its active phase.
+ (b) fill mode [=fill mode/forwards=]. + After the active phase has finished, + the [=iteration progress=] value continues to maintain a fill value.
+ (c) fill mode [=fill mode/backwards=]. + The animation effect produces a fill value + until the start of the active phase.
+ (d) fill mode [=fill mode/both=]. + Both before and after the active phase + the animation effect produces a fill value. +
+
+ Note: Authors are discouraged from using [=fill modes=] to produce animations whose effect is applied indefinitely. @@ -2872,65 +3019,7 @@ Fill behavior {#fill-behavior} -### Fill modes ### {#fill-modes} - -
-This section is non-normative - - The effect of each [=fill mode=] is as follows: - - : none - :: - The animation effect has no effect when it is not [=in play=]. - - : forwards - :: - When the animation effect is in the [=animation effect/after phase=], - the animation effect will produce the same [=iteration progress=] value - as the last moment it is scheduled to be [=in play=]. - - For all other times that the animation effect is not [=in play=], - it will have no effect. - - : backwards - :: - When the animation effect is in the [=animation effect/before phase=], - the animation effect will produce the same [=iteration progress=] value - as the earliest moment that it is scheduled to be [=in play=]. - - For all other times that the animation effect is not [=in play=], - it will have no effect. - - : both - :: - When the animation effect is in its [=animation effect/before phase=], - backwards fill behavior is used. - - When the animation effect is in its [=animation effect/after phase=], - forwards fill behavior is used. - - Some examples of the these fill modes are illustrated below. - -
- Examples of various fill modes and the states produced. -
- Examples of various fill modes and the states produced.
- (a) fill mode "none". - The animation effect has no effect outside its active phase.
- (b) fill mode "forwards". - After the active phase has finished, - the [=iteration progress=] value continues to maintain a fill value.
- (c) fill mode "backwards". - The animation effect produces a fill value - until the start of the active phase.
- (d) fill mode "both". - Both before and after the active phase - the animation effect produces a fill value. -
-
- - Note: Setting a fill mode has no bearing on + Note: Setting a [=fill mode=] has no bearing on the endpoints of the [=active interval=] or the boundaries between [[#animation-effect-phases-and-states|phases]] However, the fill mode does have an effect @@ -2940,12 +3029,9 @@ Fill behavior {#fill-behavior} inside the [=animation effect/active phase=] or when a fill is applied. -
+### Repeating ### {#repeating} -Repeating {#repeating} ---------- - -### Iteration intervals ### {#iteration-intervals} +#### Iteration intervals #### {#iteration-intervals} It is possible to specify that an animation effect should repeat a fixed number of times or indefinitely. @@ -2995,7 +3081,7 @@ Repeating {#repeating} -### Controlling iteration ### {#controlling-iteration} +#### Controlling iteration #### {#controlling-iteration} The number of times an [=animation effect=] repeats is called its iteration count. @@ -3046,62 +3132,7 @@ Repeating {#repeating} -### Iteration time space ### {#iteration-time-space} - -
-This section is non-normative - - In Web Animations all times are relative to some point of reference. - These different points of reference produce different time spaces. - - This can be compared to coordinate spaces - as used in computer graphics. - The zero time of a time space is analogous - to the origin of a coordinate space. - - We can describe animations that repeat - as establishing a new time space - each time the animation repeats: - the iteration time space. - - Iteration time space is a time space - whose zero time is the beginning - of an animation effect's current iteration. - - Within the Web Animations model we also refer to [=active time=], - which is a time relative to the beginning of the active interval. - This time space, however, is internal to the model - and not exposed in the programming interface or in markup. - - These time spaces are illustrated below. - -
- A comparison of local time, active time, and iteration time. -
- A comparison of [=local time=], [=active time=], and iteration time - for an animation with an [=iteration duration=] of 1s - and an [=iteration count=] of 2.5. -
-
- - Note: While the time spaces themselves are not bounded, - Web Animations defines [=active time=] and the [=iteration progress=] - such that they are clamped to a set range as shown in the diagram. - For example, whilst a time of -1 second - is a valid time in active time space, - the procedure for calculating the [=active time=] - defined in [[#calculating-the-active-time]] - will never return a negative value. - - In addition to these time spaces - we can also refer to the document time space, - which is time space of the [=time values=] - of the [=default document timeline=] of the {{Document}} - of the [=current global object=]. -
- -### Interval timing ### {#interval-timing} +#### Interval timing #### {#interval-timing}
This section is non-normative @@ -3154,8 +3185,72 @@ Repeating {#repeating}
-Core animation effect calculations {#core-animation-effect-calculations} ----------------------------------- +### Direction control ### {#direction-control} + + [=Animation effects=] can also be configured + to run iterations in alternative directions + using direction control. + For this purpose, [=animation effects=] have + a playback direction parameter + which takes one of the following values: + +
+ + : normal + :: + All iterations are played as specified. + + : reverse + :: + All iterations are played in the reverse direction + from the way they are specified. + + : alternate + :: + Even iterations are played as specified; + odd iterations are played in the reverse direction + from the way they are specified. + + : alternate-reverse + :: + Even iterations are played in the reverse direction + from the way they are specified; + odd iterations are played as specified. + +
+ + The semantics of these values are incorporated into + the calculation of the [=directed progress=] + in [[#calculating-the-directed-progress]]. + +### Easing (effect timing transformations) ### {#time-transformations} + + It is often desirable to control the rate + at which an [=animation effect=] progresses. + For example, easing the rate of animation + can create a sense of momentum and produce a more natural effect. + The CSS Easing Functions Module + defines [=timing functions=] for this purpose. + [[!CSS-EASING-1]] + + [=Animation effects=] each have + an effect timing function, + which is a [=timing function=] + used to transform progress across the entirety of each iteration. + See [[#calculating-the-transformed-progress]]. + + The default [=effect timing function=] + is the [=linear timing function=]. + + Note: Specific [[#types-of-animation-effects|types of animation effects]] + may provide additional time transformations. + For example, [=keyframe effects=] can provide + [=keyframe-specific timing functions=] + that can apply a [=timing function=] + specifically between two adjacent keyframes. + +Calculating progress {#core-animation-effect-calculations} +-------------------- ### Overview ### {#animation-effect-calculations-overview} @@ -3182,9 +3277,6 @@ Core animation effect calculations {#core-animation-effect-calculations} - The process for calculating the [=active duration=] - is normatively defined in [[#calculating-the-active-duration]]. - Having established the [=active duration=], the process for transforming an [=animation effect=]’s [=local time=] into its [=transformed progress=] ([=iteration progress=]) @@ -3214,32 +3306,11 @@ Core animation effect calculations {#core-animation-effect-calculations} The first step, calculating the [=local time=] is described in [[#local-time-section]]. - Steps 2 to 4 in the diagram are described in the following sections. - Steps 5 and 6 are described in [[#calculating-the-directed-progress]] - and [[#calculating-the-transformed-progress]] respectively. + Steps 2 to 6 in the diagram are described in the following sections. - -### Calculating the active duration ### {#calculating-the-active-duration} - - The [=active duration=] is calculated as follows: - -
- active duration = - iteration duration × iteration count -
- - If either the [=iteration duration=] or [=iteration count=] are zero, - the [=active duration=] is zero. - - Note: This clarification is needed - since the result of infinity multiplied by zero - is undefined according to IEEE 754-2008. - -### Transforming the local time ### {#transforming-the-local-time} - -#### Calculating the active time #### {#calculating-the-active-time} +### Calculating the active time ### {#calculating-the-active-time} The active time is based on the [=local time=] and [=start delay=]. However, it is only defined @@ -3254,8 +3325,7 @@ Core animation effect calculations {#core-animation-effect-calculations}
: If the [=fill mode=] is - backwards or - both, + [=fill mode/backwards=] or [=fill mode/both=], :: Return the result of evaluating max(local timestart delay, 0). @@ -3277,8 +3347,7 @@ Core animation effect calculations {#core-animation-effect-calculations}
: If the [=fill mode=] is - forwards or - both, + [=fill mode/forwards=] or [=fill mode/backwards=], :: Return the result of evaluating max(min(local timestart delay, @@ -3296,7 +3365,7 @@ Core animation effect calculations {#core-animation-effect-calculations}
-#### Calculating the overall progress #### {#calculating-the-overall-progress} +### Calculating the overall progress ### {#calculating-the-overall-progress} The overall progress describes the number of iterations that have completed (including partial iterations) @@ -3327,7 +3396,7 @@ Core animation effect calculations {#core-animation-effect-calculations} overall progress + iteration start. -#### Calculating the simple iteration progress #### {#calculating-the-simple-iteration-progress} +### Calculating the simple iteration progress ### {#calculating-the-simple-iteration-progress} The simple iteration progress is a fraction of the progress through the current iteration @@ -3393,52 +3462,6 @@ Core animation effect calculations {#core-animation-effect-calculations} 1. Otherwise, return floor(overall progress). -Direction control {#direction-control} ------------------ - - [=Animation effects=] can also be configured - to run iterations in alternative directions - using direction control. - For this purpose, [=animation effects=] have - a playback direction parameter - which takes one of the following values: - - * normal, - * reverse, - * alternate, or - * alternate-reverse. - - The semantics of these values are incorporated into - the calculation of the [=directed progress=] which follows. - -
-This section is non-normative - - A non-normative definition of these values is as follows: - - : normal - :: - All iterations are played as specified. - - : reverse - :: - All iterations are played in the reverse direction - from the way they are specified. - - : alternate - :: - Even iterations are played as specified; - odd iterations are played in the reverse direction - from the way they are specified. - - : alternate-reverse - :: - Even iterations are played in the reverse direction - from the way they are specified; - odd iterations are played as specified. - -
- ### Calculating the directed progress ### {#calculating-the-directed-progress} The directed progress is calculated @@ -3453,19 +3476,21 @@ Direction control {#direction-control}
- : If [=playback direction=] is normal, + : If [=playback direction=] is [=playback direction/normal=], :: Let the |current direction| be forwards. - : If [=playback direction=] is reverse, + : If [=playback direction=] is [=playback direction/reverse=], :: Let the |current direction| be reverse. - : Otherwise, + : Otherwise + (the [=playback direction=] is + [=playback direction/alternate=] or [=playback direction/alternate-reverse=])p, :: 1. Let |d| be the [=current iteration index=]. - 1. If [=playback direction=] is alternate-reverse + 1. If [=playback direction=] is [=playback direction/alternate-reverse=] increment |d| by 1. 1. If d % 2 == 0, @@ -3482,21 +3507,6 @@ Direction control {#direction-control} Otherwise, return 1.0 − simple iteration progress. -Time transformations {#time-transformations} --------------------- - - It is often desirable to control the rate - at which an [=animation effect=] progresses. - For example, easing the rate of animation - can create a sense of momentum and produce a more natural effect. - The CSS Easing Functions Module [[!CSS-EASING-1]] - defines [=timing functions=] for this purpose. - - [=Animation effects=] have - one [=timing function=] associated with them. - The default [=timing function=] - is the [=linear timing function=]. - ### Calculating the transformed progress ### {#calculating-the-transformed-progress} The transformed progress is calculated @@ -3518,14 +3528,13 @@ Time transformations {#time-transformations} and going forwards is false. 1. Return the result of evaluating - the [=animation effect=]’s [=timing function=] + the [=effect timing function=] passing [=directed progress=] as the input progress value and |before flag| as the before flag. -The iteration progress {#the-iteration-progress} ----------------------- +### Yielding the iteration progress ### {#the-iteration-progress} - The iteration progress of an [=animation effect=] + The final output iteration progress of an [=animation effect=] is simply its [=transformed progress=]. @@ -3747,11 +3756,13 @@ Keyframe effects {#keyframe-effects} or have unsupported values is defined in [[#the-effect-value-of-a-keyframe-animation-effect]]. - Each keyframe also has a [=timing function=] associated with it + Each keyframe also has a keyframe-specific timing function + associated with it, which is a [=timing function=] that is applied to the period of time between the keyframe on which it is specified and the next keyframe in the list. - The [=timing function=] specified on the last keyframe in the list + + Note: The [=timing function=] specified on the last keyframe in the list is never applied. Each [=keyframe=] may have a keyframe-specific composite operation @@ -4248,11 +4259,6 @@ Combining effects {#combining-effects} of any two [=keyframe effects=] |A| and |B| within an [=effect stack=] is established by comparing their properties as follows: - 1. Let the associated animation of an animation effect - be the [=animation=] [=associated with an animation|associated=] - with the [=animation effect=]. - 1. Sort |A| and |B| by applying the following conditions in turn until the order is resolved, @@ -4507,7 +4513,7 @@ Side effects of animation {#side-effects-section} a [=stacking context=] will be created for the [=effect target=] so long as the [=animation=] is in the [=animation effect/before phase=], the [=animation effect/active phase=] or, - if it has a [=fill mode=] of "forwards" or "both", + if it has a [=fill mode=] of [=fill mode/forwards=] or [=fill mode/both=], the [=animation effect/after phase=]. @@ -5191,10 +5197,10 @@ The {{AnimationEffect}} interface {#the-animationeffect-interface} : If the [=animation effect=] to which the fill mode is being applied is a [=keyframe effect=], :: - Use {{FillMode/none}} as the [=fill mode=]. + Use [=fill mode/none=] as the [=fill mode=]. : Otherwise, - :: Use {{FillMode/both}} as the [=fill mode=]. + :: Use [=fill mode/both=] as the [=fill mode=].
@@ -5289,16 +5295,18 @@ The {{AnimationEffect}} interface {#the-animationeffect-interface} enum FillMode { "none", "forwards", "backwards", "both", "auto" }; + Represents an [=animation effect=]’s [=fill mode=]. +
: none - :: No fill. + :: No fill. ([=Fill mode=] [=fill mode/none=].) : forwards - :: Fill forwards. + :: Fill [=fill mode/forwards=]. : backwards - :: Fill backwards. + :: Fill [=fill mode/backwards=]. : both - :: Fill backwards and forwards. + :: Fill [=fill mode/both=] backwards and forwards. : auto :: No fill. In a subsequent level of this specification, this may produce