Add README.md for cc/animation

Initial version of the README.md covers how cc/animation itself works
(with some TODOs for trickier details), and dips briefly into the
clients of cc/animation. Future CLs will expand on the details of how
clients interact with cc/animation.

Bug: 740070
Cq-Include-Trybots: master.tryserver.blink:linux_trusty_blink_rel
Change-Id: Ib89a29a77630e46abcd1bd0f90e4158e9ffc0f23
Reviewed-on: https://chromium-review.googlesource.com/579587
Commit-Queue: Stephen McGruer <smcgruer@chromium.org>
Reviewed-by: Walter Korman <wkorman@chromium.org>
Reviewed-by: Ali Juma <ajuma@chromium.org>
Cr-Commit-Position: refs/heads/master@{#491783}

cc/animation/README.md

+# cc/animation
+
+[TOC]
+
+## Overview
+
+cc/animation provides animation support - generating output values (usually
+visual properties) based on a predefined function and changing input values.
+Currently the main clients of cc/animation are Blink and ui/, targeting
+composited layers, but the code is intended to be agnostic of the client it is
+supporting. Aspirationally we could eventually merge cc/animation and Blink
+animation and have only a single animation system for all of Chromium.
+
+This document covers two main topics. The first section explains how
+cc/animation actually works: how animations are ticked, what animation curves
+are, what the ownership model is, etc. Later sections document how other parts
+of Chromium interact with cc/animation, most prominently Blink and ui/.
+
+## How cc/animation works
+
+The root concept in cc/animation is an
+[animation](https://codesearch.chromium.org/chromium/src/cc/animation/animation.h).
+Animations contain the state necessary to 'play' (interpolate values from) an
+[animation curve](https://codesearch.chromium.org/chromium/src/cc/animation/animation_curve.h),
+which is a function that returns a value given an input time. Aside from the
+animation curve itself, an animation's state includes the run state (playing,
+paused, etc), the start time, the current direction (forwards, reverse), etc.
+An animation does not know or care what property is being animated, and holds
+only an opaque identifier for the property to allow clients to map output values
+to the correct properties.
+
+Targeting only a single property means that cc animations are distinct from the
+Blink concept of an animation, which wraps the animation of multiple properties.
+To coordinate the playback of multiple cc/animations (e.g. those that are
+animating multiple properties on the same target), animations have the concept
+of a group identifier. Animations that have the same group identifier and the
+same target are started together, and animation-finished notifications are only
+sent when all animations in the group have finished.
+
+Animations are grouped together based on their
+[animation target](https://codesearch.chromium.org/chromium/src/cc/animation/animation_target.h)
+(the entity whose property is being animated) and each such group is owned by an
+[animation player](https://codesearch.chromium.org/chromium/src/cc/animation/animation_player.h).
+Note that there may be multiple animation players with the same target (each
+with a set of animations for that target); the
+[ElementAnimations](https://codesearch.chromium.org/chromium/src/cc/animation/element_animations.h)
+class wraps the multiple animation players and has a 1:1 relationship with
+target entities.
+
+`TODO(smcgruer): Why are ElementAnimations and AnimationPlayers separate?`
+
+In order to play an animation, input time values must be provided to the
+animation curve and output values fed back into the animating entity. This is
+called 'ticking' an animation and is the responsibility of the
+[animation host](https://codesearch.chromium.org/chromium/src/cc/animation/animation_host.h).
+The animation host has a list of currently ticking players (i.e. those that have
+any non-deleted animations), which it iterates through whenever it receives a
+tick call from the client (along with a corresponding input time).  The
+animation players then call into their non-deleted animations, retrieving the
+value from the animation curve.  As they are computed, output values are sent to
+the target which is responsible for passing them to the client entity that is
+being animated.
+
+### Types of Animation Curve
+
+As noted above, an animation curve is simply a function which converts an input
+time value into some output value. Animation curves are categorized based on
+their output type, and each such category can have multiple implementations that
+provide different conversion functions. There are many categories of animation
+curve, but some common ones are `FloatAnimationCurve`, `ColorAnimationCurve`,
+and `TransformAnimationCurve`.
+
+The most common implementation of the various animation curve categories are the
+[keyframed animation curves](https://codesearch.chromium.org/chromium/src/cc/animation/keyframed_animation_curve.h).
+These curves each have a set of keyframes which map a specific time to a
+specific output value. Producing an output value for a given input time is then
+a matter of identifying the two keyframes the time lies between, and
+interpolating between the keyframe output values. (Or simply using a keyframe
+output value directly, if the input time happens to line up exactly.) Exact
+details of how each animation curve category is interpolated can be found in the
+implementations.
+
+There is one category of animation curve that stands somewhat apart, the
+[scroll offset animation curve](https://codesearch.chromium.org/chromium/src/cc/animation/scroll_offset_animation_curve.h).
+This curve converts the input time into a scroll offset, interpolating between
+an initial scroll offset and an updateable target scroll offset. It has logic to
+handle different types of scrolling such as programmatic, keyboard, and mouse
+wheel scrolls.
+
+### Animation Timelines
+
+cc/animation has a concept of an
+[animation timeline](https://codesearch.chromium.org/chromium/src/cc/animation/animation_timeline.h).
+This should not be confused with the identically named Blink concept. In
+cc/animation, animation timelines are an implementation detail - they hold the
+animation players and are responsible for syncing them to the impl thread (see
+below), but do not participate in the ticking process in any way.
+
+### Main/Impl Threads
+
+One part of cc/animation that is not client agnostic is its support for the
+[Chromium compositor thread](https://codesearch.chromium.org/chromium/src/cc/README.md).
+Most of the cc/animation classes have a `PushPropertiesTo` method, in which they
+synchronize necessary state from the main thread to the impl thread. It is
+feasible that such support could be abstracted if necessary, but so far it has
+not been required.
+
+## Current cc/animation Clients
+
+As noted above, the main clients of cc/animation are currently Blink for
+accelerated web animations, and ui/ for accelerated user interface animations.
+Both of these clients utilize
+[cc::Layer](https://codesearch.chromium.org/chromium/src/cc/layers/layer.h)
+as their animation entity and interact with cc/animation via the
+[MutatorHostClient](https://codesearch.chromium.org/chromium/src/cc/trees/mutator_host_client.h)
+interface (which is implemented by cc::LayerTreeHost and cc::LayerTreeHostImpl).
+Recently a third client, chrome/browser/vr/, has started using cc/animations as
+well. The vr/ client does not use cc::Layer as its animation entity.
+
+`TODO(smcgruer): Summarize how vr/ uses cc/animation.`
+
+### Supported Animatable Properties
+
+As cc::Layers are just textures which are reused for performance, clients that
+use composited layers as their animation entities are limited to animating
+properties that do not cause content to be redrawn. For example, a composited
+layer's opacity can be animated as promoted layers are aware of the content
+behind them.  On the other hand we cannot animate layer width as changing the
+width could modify layout - which then requires redrawing.
+
+### Interaction between cc/animation and Blink
+
+Blink is able to move compatible animations off the main thread, by promoting
+the animating element into a layer. This section gives an overview of the
+machinery to move animations to the compositor from Blink. It does not go into
+details on the Blink-side of animations.
+
+`TODO(smcgruer): Write this.`
+
+### Interaction between cc/animation and ui/
+
+`TODO(smcgruer): Write this.`