Skip to content

Commit ec6770a

Browse files
committed
[web-animations-1][editorial] Various clarifications and dfn improvements to timelines
* Shift high-level description of timing model from “Time Values” section to “Timing Model” intro. * Dfn “timing node” since it's used without definition, and cross-link it from relevant places. * Rephrase “time value” dfn to work better with future time value types, stealing wording from the definition of “timeline”. * Clarify the purpose of a timeline. * Improve dfn of “unresolved” time values. * Add proper dfn for “active timeline”. * Clarify why document timeline offsets are called “origin time”. * Improve cross-linking throughout.
1 parent ee23476 commit ec6770a

1 file changed

Lines changed: 31 additions & 17 deletions

File tree

web-animations-1/Overview.bs

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -530,6 +530,13 @@ Timing model {#timing-model}
530530
This section describes and defines the behavior
531531
of the <dfn>Web Animations [=timing model=]</dfn>.
532532

533+
Timing in the [=Web Animations model=] is represented through
534+
a hierarchy of relationships between <dfn>timing nodes</dfn>,
535+
in which parent nodes provide timing information to their child nodes
536+
in the form of [=time values=],
537+
ultimately resulting in an [=iteration progress=] and [=iteration index=]
538+
supplied to the [=animations model=]
539+
533540
Timing model characteristics {#timing-model-overview}
534541
----------------------------
535542

@@ -541,7 +548,8 @@ Timing model characteristics {#timing-model-overview}
541548

542549
### Stateless ### {#stateless}
543550

544-
The Web Animations [=timing model=] operates by taking an input time
551+
The Web Animations [=timing model=] operates
552+
by taking an input [=time value=]
545553
and producing an output [=iteration progress=].
546554
Since the output is based solely on the input time
547555
and is independent of previous inputs,
@@ -629,13 +637,11 @@ Timing model characteristics {#timing-model-overview}
629637
Time values {#time-value-section}
630638
-----------
631639

632-
Timing is based on a hierarchy of time relationships between timing nodes.
633-
Parent nodes provide timing information to their child nodes
634-
in the form of [=time values=].
635-
636-
A <dfn>time value</dfn> is a real number which nominally represents
640+
A <dfn>time value</dfn> in the [=Web Animations model=]
641+
is a value that serves the purpose of synchronization.
642+
[=Time values=] are real numbers that nominally represent
637643
a number of milliseconds from some moment.
638-
The connection between [=time values=] and wall-clock milliseconds
644+
However, the connection between [=time values=] and wall-clock milliseconds
639645
can be obscured by any number of transformations applied to the value
640646
as it passes through the time hierarchy.
641647

@@ -644,25 +650,30 @@ Time values {#time-value-section}
644650
in which case the connection between time values and milliseconds
645651
will be weakened even further.
646652

647-
A [=time value=] is <dfn>unresolved</dfn> if, for example,
648-
a timing node is not in a state to produce a [=time value=].
653+
A [=time value=] can be <dfn>unresolved</dfn>,
654+
i.e. represent the absence of a meaningful [=time value=].
655+
This can happen if
656+
a [=timing node=] is not in a state to produce a [=time value=].
649657

650658
Timelines {#timelines}
651659
---------
652660

653-
A <dfn export>timeline</dfn> provides a source of [=time values=]
654-
for the purpose of synchronization.
655-
661+
A <dfn export>timeline</dfn> is a [=timing node=]
662+
that provides a source of [=time values=].
656663
At any given moment, a [=timeline=] has a single current [=time value=]
657664
known simply as the timeline's <dfn export for=timeline>current time</dfn>.
665+
Changes in a [=timeline=]’s [=timeline/current time=]
666+
are ultimately what drive [=animations=] in the [=Web Animations model=].
658667

659668
A [=timeline=] might not always be able to return a meaningful [=time value=],
660669
but only an [=unresolved=] time value.
661-
For example, it might be defined relative to a moment that has yet to occur,
670+
For example, its [=timeline/current time=] might be defined relative to
671+
a moment that has yet to occur,
662672
such as the firing of a document's load event.
663673
A [=timeline=] is considered to be
664-
<dfn export lt="inactive timeline | active timeline">inactive</dfn>
665-
when its [=time value=] is [=unresolved=].
674+
<dfn export lt="inactive timeline">inactive</dfn>
675+
when its [=time value=] is [=unresolved=],
676+
and <dfn export lt="active timeline">active</dfn> otherwise.
666677

667678
A [=timeline=] is
668679
<dfn export lt="monotonically increasing timeline" local-lt="monotonically increasing">monotonically increasing</dfn>
@@ -757,7 +768,10 @@ Timelines {#timelines}
757768
and whose [=timeline/current time=] is calculated
758769
as a fixed offset from the |now| timestamp provided
759770
each time the [=update animations and send events=] procedure is run.
760-
This fixed offset is referred to as
771+
This fixed offset is equal to
772+
the [=timeline/current time=] of the [=default document timeline=]
773+
when this timeline’s [=timeline/current time=] was zero,
774+
and is thus referred to as
761775
the document timeline's <dfn>origin time</dfn>.
762776

763777
Issue(2079): There must be a better term than "origin time"&mdash;
@@ -793,7 +807,7 @@ Timelines {#timelines}
793807
<em>This section is non-normative</em>
794808

795809
Since no scaling is applied to
796-
the |now| timestamp values provided to [=document timelines=],
810+
the |now| timestamp values provided to a [=document timeline=],
797811
the [=time values=] it produces will be
798812
proportional to wall-clock milliseconds.
799813

0 commit comments

Comments
 (0)