Document SMILAnimationSandwich

Bug: 998526
Change-Id: I719ef2eff9da643c94e848b1f885fd18028ea657
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1831809Reviewed-by: Philip Rogers <pdr@chromium.org>
Commit-Queue: Fredrik Söderquist <fs@opera.com>
Cr-Commit-Position: refs/heads/master@{#701945}

third_party/blink/renderer/core/svg/animation/smil_animation_sandwich.h

@@ -50,6 +50,70 @@ struct PriorityCompare {
 
 // This class implements/helps with implementing the "sandwich model" from SMIL.
 // https://www.w3.org/TR/SMIL3/smil-animation.html#animationNS-AnimationSandwichModel
+//
+// A "sandwich" contains all the animation elements (actually timed elements in
+// our case because of how we handle <discard>) that targets a specific
+// attribute (or property) on a certain element.
+//
+// Consider the following simple example:
+//
+// <svg>
+//   <rect id="foo" width="100" height="100" fill="yellow">
+//     <set id="s1" attributeName="fill" to="blue" begin="1s; 3s" dur="1s"/>
+//     <set id="s2" attributeName="fill" to="lightblue" begin="1.5s" dur="2s"/>
+//   </rect>
+// </svg>
+//
+// In this case there is only one sandwich: <#foo, "fill">
+//
+// The sandwich is priority-sorted with the priority being derived from when
+// the currently active interval began - later is higher. In the above example
+// there are three intervals: [1s 2s) and [3s 4s) for the first <set> element
+// (in tree-order) and [1.5s 3.5s) for the second <set> element. The animation
+// elements are only active within the intervals defined (no fill="freeze").
+//
+// When the first interval of the first <set> starts (at 1s), it is the only
+// active animation and thus the only one to apply. When the second interval
+// starts (at 1.5s) its animation gets a higher priority and replaces the lower
+// priority animation from the first <set>. The first <set> then ends at 2s,
+// leaving the second <set> as the only active animation. When the first <set>
+// then starts again at 3s it gets a higher priority because of the later begin
+// time and replaces the animation from the second <set>. When the second <set>
+// ends at 3.5s nothing changes because the first <set> is still active. When
+// the second <set> ends again at 4s, no animation apply and the target reverts
+// to the base value (yellow) again.
+//
+// Schematically (right hand side exclusive):
+//
+// 0s -> 1s:   No animations apply (fill=yellow)
+//             Sandwich order: (s1) (s2) [both inactive]
+// 1s -> 1.5s: The first <set> apply (fill=blue)
+//             Sandwich order: s1 (s2)   [only s1 active]
+// 1.5s -> 2s: The second <set> apply (fill=lightblue)
+//             Sandwich order: s1 s2
+// 2s -> 3s:   The second <set> apply (fill=lightblue)
+//             Sandwich order: (s1) s2
+// 3s -> 3.5s: The first <set> apply (fill=blue)
+//             Sandwich order: s2 s1
+// 3.5s -> 4s: The first <set> apply (fill=blue)
+//             Sandwich order: (s2) s1
+// 4s -> ...:  No animations apply (fill=yellow)
+//
+// -----
+//
+// Implementation details:
+//
+// UpdateTiming() handles updates to interval and transitions the active state.
+//
+// UpdateSyncBases() handles the sorting described above (as well notifying
+// about new intervals).
+//
+// UpdateActiveAnimationStack() constructs a vector containing only the active
+// elements.
+//
+// ApplyAnimationValues() computes the actual animation value based on the
+// vector of active elements and applies it to the target element.
+//
 class SMILAnimationSandwich : public GarbageCollected<SMILAnimationSandwich> {
  public:
   using ScheduledVector = HeapVector<Member<SVGSMILElement>>;