From @majido on July 11, 2017 20:52

Background

During last houdini F2F meeting it was decided that we should attempt to make animation worklet
API fit better within web animation model.

One of the key features of worklet animations is that they can have multiple effects which are
driven by the animate function in worklet scope. Our initial plan was to make a new Animation base
class that does not assume "a single effect" (see below for a initial API sketch). Since then I
realized that web animations level 2 spec has a GroupEffect construct which I believe worklet
animations can use to the same effect.

interface AnimationBase :  EventTarget{...};
interface Animation :  AnimationBase {
  attribute AnimationEffectReadOnly? effect;
  attribute AnimationTimeline? timeline;
};
interface WorkletAnimation : AnimationBase {
  attribute AnimationEffectReadOnly? effects;
  attribute array<AnimationTimeline> timelines;
}

Using GroupEffect with WorkletAnimations

The idea is to pass in a GroupEffect to WorkletAnimations for usecases that require controlling
multiple effects. However, In WorkletAnimation we want to provide a more flexible API where the
animation script has the option to set the local time for each individual child effects.

Here is a hypothetical API that can enable this:

// In Document scope
animationWorklet.addModule('my-custom-animator.js').then( _ => {
  const workletAnim = new WorkletAnimation(
    'my-custom-animation',
    new WorkletGroupEffect([new KeyframeEffect(), new KeyframeEffect()]),
    document.timeline);
});

// In Animation Worklet scope
registerAnimator('my-custom-animation', class {
  animate(timelines, groupEffect) {
    const time = timelines[0].currentTime;
    // Drive the output by setting group effect's children local times.
    groupEffect.children[0].localTime = time;
    groupEffect.children[1].localTime = time * 3.14;
  }
});

The current GroupEffect design only allows for two different scheduling models (i.e.,
parallel, sequence). These models govern how the group effect local time is translated to its
children effects local times by controlling the child effect start time. In parallel mode children
start times are the same as parent, and in sequence mode children start times form a sequence.

Setting local time directly on child effects does not fit in either of these models. One way to
think about it is that this model allows arbitrary per-child start time. Below is a set of proposed
changes to GroupEffect that allow this.

Proposal

Keep GroupEffect as is but introduce a new subclass WorkletGroupEffect (or CustomGroupEffect).
Unlike normal group effects where parent time dictates the child time the above will allow its
children local time to be mutated individually as well.

partial interface AnimationEffectReadOnly {
    // Intended for use inside Animation Worklet scope to drive the effect.
    [Exposed=AnimationWorklet]
    attribute localTime;
};
interface WorkletGroupEffectReadOnly :  GroupEffectReadOnly {}
interface WorkletGroupEffect :  WorkletGroupEffectReadOnly {}
WorkletGroupEffect implements AnimationEffectMutable;
WorkletGroupEffect implements GroupEffectMutable;

Setting localTime property on an effect to value t does the following:

• If the animation effect does not have a parent group, then set the effect local time to t.
• If the animation effect has a parent group
  • If the parent group is a WorkletGroupEffect, then
    set the effect local time to t, and the effect start time to (parent's transformed time - t).
  • Otherwise throw an exception indicating that the child effect time can only be controlled by
    its parent group.

Notes

• Initially we don't want to expose WorkletGroupEffect directly, rather only allow it to be created
  if a sequence of effects are passed into WorkletAnimation.
• Clone() method on WorkletGroupEffect needs to not only close timing and children but also the
  start time values.
• Not clear to me what should happen if a child local time is set but its parent local time is
  still unresolved.

Copied from original issue: w3c/web-animations#191