lottie-ios 3.2.3 → 3.4.0

package/Sources/Private/CoreAnimation/Animations/ShapeAnimation.swift

@@ -0,0 +1,246 @@
+// Created by Cal Stephens on 1/7/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+  /// Adds a `path` animation for the given `ShapeItem`
+  @nonobjc
+  func addAnimations(
+    for shape: ShapeItem,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier) throws
+  {
+    switch shape {
+    case let customShape as Shape:
+      try addAnimations(for: customShape.path, context: context, pathMultiplier: pathMultiplier)
+
+    case let combinedShape as CombinedShapeItem:
+      try addAnimations(for: combinedShape, context: context, pathMultiplier: pathMultiplier)
+
+    case let ellipse as Ellipse:
+      try addAnimations(for: ellipse, context: context, pathMultiplier: pathMultiplier)
+
+    case let rectangle as Rectangle:
+      try addAnimations(for: rectangle, context: context, pathMultiplier: pathMultiplier)
+
+    case let star as Star:
+      try addAnimations(for: star, context: context, pathMultiplier: pathMultiplier)
+
+    default:
+      // None of the other `ShapeItem` subclasses draw a `path`
+      try context.logCompatibilityIssue("Unexpected shape type \(type(of: shape))")
+      return
+    }
+  }
+
+  /// Adds a `fillColor` animation for the given `Fill` object
+  @nonobjc
+  func addAnimations(for fill: Fill, context: LayerAnimationContext) throws {
+    fillRule = fill.fillRule.caFillRule
+
+    try addAnimation(
+      for: .fillColor,
+      keyframes: fill.color.keyframes,
+      value: \.cgColorValue,
+      context: context)
+
+    try addOpacityAnimation(for: fill, context: context)
+  }
+
+  /// Adds animations for `strokeStart` and `strokeEnd` from the given `Trim` object
+  @nonobjc
+  func addAnimations(for trim: Trim, context: LayerAnimationContext) throws -> PathMultiplier {
+    let (strokeStartKeyframes, strokeEndKeyframes, pathMultiplier) = try trim.caShapeLayerKeyframes(context: context)
+
+    try addAnimation(
+      for: .strokeStart,
+      keyframes: strokeStartKeyframes.keyframes,
+      value: { strokeStart in
+        // Lottie animation files express stoke trims as a numerical percentage value
+        // (e.g. 25%, 50%, 100%) so we divide by 100 to get the decimal values
+        // expected by Core Animation (e.g. 0.25, 0.5, 1.0).
+        CGFloat(strokeStart.cgFloatValue) / CGFloat(pathMultiplier) / 100
+      }, context: context)
+
+    try addAnimation(
+      for: .strokeEnd,
+      keyframes: strokeEndKeyframes.keyframes,
+      value: { strokeEnd in
+        // Lottie animation files express stoke trims as a numerical percentage value
+        // (e.g. 25%, 50%, 100%) so we divide by 100 to get the decimal values
+        // expected by Core Animation (e.g. 0.25, 0.5, 1.0).
+        CGFloat(strokeEnd.cgFloatValue) / CGFloat(pathMultiplier) / 100
+      }, context: context)
+
+    return pathMultiplier
+  }
+}
+
+/// The number of times that a `CGPath` needs to be duplicated in order to support the animation's `Trim` keyframes
+typealias PathMultiplier = Int
+
+extension Trim {
+
+  // MARK: Fileprivate
+
+  /// The `strokeStart` and `strokeEnd` keyframes to apply to a `CAShapeLayer`,
+  /// plus a `pathMultiplier` that should be applied to the layer's `path` so that
+  /// trim values larger than 100% can be displayed properly.
+  fileprivate func caShapeLayerKeyframes(context: LayerAnimationContext) throws
+    -> (strokeStart: KeyframeGroup<Vector1D>, strokeEnd: KeyframeGroup<Vector1D>, pathMultiplier: PathMultiplier)
+  {
+    let strokeStart: KeyframeGroup<Vector1D>
+    let strokeEnd: KeyframeGroup<Vector1D>
+
+    // CAShapeLayer requires strokeStart to be less than strokeEnd. This
+    // isn't required by the Lottie schema, so some animations may have
+    // strokeStart and strokeEnd flipped. If we detect this is the case,
+    // then swap them.
+    if startValueIsAlwaysGreaterThanEndValue() {
+      strokeStart = end
+      strokeEnd = start
+    } else {
+      strokeStart = start
+      strokeEnd = end
+    }
+
+    // If there are no offsets, then the stroke values can be used as-is
+    guard
+      !offset.keyframes.isEmpty,
+      offset.keyframes.contains(where: { $0.value.cgFloatValue != 0 })
+    else {
+      return (strokeStart, strokeEnd, 1)
+    }
+
+    // Otherwise, adjust the stroke values to account for the offsets
+    // 1. Interpolate the keyframes so they are all on a linear timing function
+    // 2. Merge by summing the stroke values with the offset values
+    let interpolatedStrokeStart = strokeStart.manuallyInterpolateKeyframes()
+    let interpolatedStrokeEnd = strokeEnd.manuallyInterpolateKeyframes()
+    let interpolatedStrokeOffset = offset.manuallyInterpolateKeyframes()
+
+    let adjustedStrokeStart = try adjustKeyframesForTrimOffsets(
+      strokeKeyframes: interpolatedStrokeStart,
+      offsetKeyframes: interpolatedStrokeOffset,
+      context: context)
+
+    let adjustedStrokeEnd = try adjustKeyframesForTrimOffsets(
+      strokeKeyframes: interpolatedStrokeEnd,
+      offsetKeyframes: interpolatedStrokeOffset,
+      context: context)
+
+    // If maximum stroke value is larger than 100%, then we have to create copies of the path
+    // so the total path length includes the maximum stroke
+    let maximumStroke = adjustedStrokeEnd.map { $0.value.cgFloatValue }.max() ?? 100
+    let pathMultiplier = Int(ceil(maximumStroke / 100.0))
+
+    return (
+      strokeStart: KeyframeGroup<Vector1D>(keyframes: adjustedStrokeStart),
+      strokeEnd: KeyframeGroup<Vector1D>(keyframes: adjustedStrokeEnd),
+      pathMultiplier: pathMultiplier)
+  }
+
+  // MARK: Private
+
+  /// Checks whether or not the value for `trim.start` is greater
+  /// than the value for every `trim.end` at every keyframe.
+  private func startValueIsAlwaysGreaterThanEndValue() -> Bool {
+    let keyframeTimes = Set(start.keyframes.map { $0.time } + end.keyframes.map { $0.time })
+
+    let startInterpolator = KeyframeInterpolator(keyframes: start.keyframes)
+    let endInterpolator = KeyframeInterpolator(keyframes: end.keyframes)
+
+    for keyframeTime in keyframeTimes {
+      guard
+        let startAtTime = startInterpolator.value(frame: keyframeTime) as? Vector1D,
+        let endAtTime = endInterpolator.value(frame: keyframeTime) as? Vector1D
+      else { continue }
+
+      if startAtTime.cgFloatValue < endAtTime.cgFloatValue {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /// Adjusted stroke keyframes to account for offset keyframes by merging them into a single keyframe collection
+  ///
+  /// Since stroke keyframes and offset keyframes can be defined on different animation curves, they must be
+  /// manually interpolated prior to invoking this method. Manually interpolating the keyframes will redefine both
+  /// keyframe groups such that they can be interpolated linearly.
+  ///
+  /// - Precondition: The keyframes must be interpolated using `KeyframeGroup.manuallyInterpolateKeyframes()`
+  private func adjustKeyframesForTrimOffsets(
+    strokeKeyframes: ContiguousArray<Keyframe<Vector1D>>,
+    offsetKeyframes: ContiguousArray<Keyframe<Vector1D>>,
+    context _: LayerAnimationContext) throws -> ContiguousArray<Keyframe<Vector1D>>
+  {
+    guard
+      !strokeKeyframes.isEmpty,
+      !offsetKeyframes.isEmpty
+    else {
+      return strokeKeyframes
+    }
+
+    // Map each time to its corresponding stroke/offset keyframe
+    var timeMap = [AnimationFrameTime: [Keyframe<Vector1D>?]]()
+    for stroke in strokeKeyframes {
+      timeMap[stroke.time] = [stroke, nil]
+    }
+    for offset in offsetKeyframes {
+      if var existing = timeMap[offset.time] {
+        existing[1] = offset
+        timeMap[offset.time] = existing
+      } else {
+        timeMap[offset.time] = [nil, offset]
+      }
+    }
+
+    // Each time will be mapped to a new, adjusted keyframe
+    var output = ContiguousArray<Keyframe<Vector1D>>()
+    var lastKeyframe: Keyframe<Vector1D>?
+    var lastOffset: Keyframe<Vector1D>?
+
+    for (time, values) in timeMap.sorted(by: { $0.0 < $1.0 }) {
+      // Extract keyframe/offset associated with this timestamp
+      let keyframe = values[0]
+      let offset = values[1]
+      lastKeyframe = keyframe ?? lastKeyframe
+      lastOffset = offset ?? lastOffset
+
+      guard let currentKeyframe = lastKeyframe else {
+        // No keyframes are output until the first keyframe occurs
+        continue
+      }
+
+      guard let currentOffset = lastOffset else {
+        // Scalar isHold keyframes are not output as they offset the offset keyframes
+        if !(strokeKeyframes.count == 1 && currentKeyframe.isHold) {
+          output.append(currentKeyframe)
+        }
+        continue
+      }
+
+      // Compute the adjusted value by converting the offset value to a stroke value
+      let strokeValue = currentKeyframe.value.value
+      let offsetValue = currentOffset.value.value
+      let adjustedValue = strokeValue + (offsetValue / 360 * 100)
+
+      // The tangent values are all `nil` as the keyframes should have been manually interpolated
+      let adjustedKeyframe = Keyframe<Vector1D>(
+        value: Vector1D(adjustedValue),
+        time: time,
+        isHold: currentKeyframe.isHold,
+        inTangent: nil,
+        outTangent: nil,
+        spatialInTangent: nil,
+        spatialOutTangent: nil)
+
+      output.append(adjustedKeyframe)
+    }
+
+    return output
+  }
+}

package/Sources/Private/CoreAnimation/Animations/StarAnimation.swift

@@ -0,0 +1,95 @@
+// Created by Cal Stephens on 1/10/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CAShapeLayer {
+
+  // MARK: Internal
+
+  /// Adds animations for the given `Rectangle` to this `CALayer`
+  @nonobjc
+  func addAnimations(
+    for star: Star,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    switch star.starType {
+    case .star:
+      try addStarAnimation(for: star, context: context, pathMultiplier: pathMultiplier)
+    case .polygon:
+      try addPolygonAnimation(for: star, context: context, pathMultiplier: pathMultiplier)
+    case .none:
+      break
+    }
+  }
+
+  // MARK: Private
+
+  @nonobjc
+  private func addStarAnimation(
+    for star: Star,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: star.position.keyframes,
+      value: { position in
+        // We can only use one set of keyframes to animate a given CALayer keypath,
+        // so we currently animate `position` and ignore any other keyframes.
+        // TODO: Is there a way to support this properly?
+        BezierPath.star(
+          position: position.pointValue,
+          outerRadius: try star.outerRadius
+            .exactlyOneKeyframe(context: context, description: "outerRadius").value.cgFloatValue,
+          innerRadius: try star.innerRadius?
+            .exactlyOneKeyframe(context: context, description: "innerRadius").value.cgFloatValue ?? 0,
+          outerRoundedness: try star.outerRoundness
+            .exactlyOneKeyframe(context: context, description: "outerRoundness").value.cgFloatValue,
+          innerRoundedness: try star.innerRoundness?
+            .exactlyOneKeyframe(context: context, description: "innerRoundness").value.cgFloatValue ?? 0,
+          numberOfPoints: try star.points
+            .exactlyOneKeyframe(context: context, description: "points").value.cgFloatValue,
+          rotation: try star.rotation
+            .exactlyOneKeyframe(context: context, description: "rotation").value.cgFloatValue,
+          direction: star.direction)
+          .cgPath()
+          .duplicated(times: pathMultiplier)
+      },
+      context: context)
+  }
+
+  @nonobjc
+  private func addPolygonAnimation(
+    for star: Star,
+    context: LayerAnimationContext,
+    pathMultiplier: PathMultiplier)
+    throws
+  {
+    try addAnimation(
+      for: .path,
+      keyframes: star.position.keyframes,
+      value: { position in
+        // We can only use one set of keyframes to animate a given CALayer keypath,
+        // so we currently animate `position` and ignore any other keyframes.
+        // TODO: Is there a way to support this properly?
+        BezierPath.polygon(
+          position: position.pointValue,
+          numberOfPoints: try star.points
+            .exactlyOneKeyframe(context: context, description: "numberOfPoints").value.cgFloatValue,
+          outerRadius: try star.outerRadius
+            .exactlyOneKeyframe(context: context, description: "outerRadius").value.cgFloatValue,
+          outerRoundedness: try star.outerRoundness
+            .exactlyOneKeyframe(context: context, description: "outerRoundedness").value.cgFloatValue,
+          rotation: try star.rotation
+            .exactlyOneKeyframe(context: context, description: "rotation").value.cgFloatValue,
+          direction: star.direction)
+          .cgPath()
+          .duplicated(times: pathMultiplier)
+      },
+      context: context)
+  }
+}

package/Sources/Private/CoreAnimation/Animations/StrokeAnimation.swift

@@ -0,0 +1,70 @@
+// Created by Cal Stephens on 2/10/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import Foundation
+import QuartzCore
+
+// MARK: - StrokeShapeItem
+
+/// A `ShapeItem` that represents a stroke
+protocol StrokeShapeItem: OpacityAnimationModel {
+  var strokeColor: KeyframeGroup<Color>? { get }
+  var width: KeyframeGroup<Vector1D> { get }
+  var lineCap: LineCap { get }
+  var lineJoin: LineJoin { get }
+  var miterLimit: Double { get }
+  var dashPattern: [DashElement]? { get }
+}
+
+// MARK: - Stroke + StrokeShapeItem
+
+extension Stroke: StrokeShapeItem {
+  var strokeColor: KeyframeGroup<Color>? { color }
+}
+
+// MARK: - GradientStroke + StrokeShapeItem
+
+extension GradientStroke: StrokeShapeItem {
+  var strokeColor: KeyframeGroup<Color>? { nil }
+}
+
+// MARK: - CAShapeLayer + StrokeShapeItem
+
+extension CAShapeLayer {
+  /// Adds animations for properties related to the given `Stroke` object (`strokeColor`, `lineWidth`, etc)
+  @nonobjc
+  func addStrokeAnimations(for stroke: StrokeShapeItem, context: LayerAnimationContext) throws {
+    lineJoin = stroke.lineJoin.caLineJoin
+    lineCap = stroke.lineCap.caLineCap
+    miterLimit = CGFloat(stroke.miterLimit)
+
+    if let strokeColor = stroke.strokeColor {
+      try addAnimation(
+        for: .strokeColor,
+        keyframes: strokeColor.keyframes,
+        value: \.cgColorValue,
+        context: context)
+    }
+
+    try addAnimation(
+      for: .lineWidth,
+      keyframes: stroke.width.keyframes,
+      value: \.cgFloatValue,
+      context: context)
+
+    try addOpacityAnimation(for: stroke, context: context)
+
+    if let (dashPattern, dashPhase) = stroke.dashPattern?.shapeLayerConfiguration {
+      lineDashPattern = try dashPattern.map {
+        try KeyframeGroup(keyframes: $0)
+          .exactlyOneKeyframe(context: context, description: "stroke dashPattern").value.cgFloatValue as NSNumber
+      }
+
+      try addAnimation(
+        for: .lineDashPhase,
+        keyframes: dashPhase,
+        value: \.cgFloatValue,
+        context: context)
+    }
+  }
+}

package/Sources/Private/CoreAnimation/Animations/TransformAnimations.swift

@@ -0,0 +1,205 @@
+// Created by Cal Stephens on 12/17/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - TransformModel
+
+/// This protocol mirrors the interface of `Transform`,
+/// but it also implemented by `ShapeTransform` to allow
+/// both transform types to share the same animation implementation.
+protocol TransformModel {
+  /// The anchor point of the transform.
+  var anchorPoint: KeyframeGroup<Vector3D> { get }
+
+  /// The position of the transform. This is nil if the position data was split.
+  var _position: KeyframeGroup<Vector3D>? { get }
+
+  /// The positionX of the transform. This is nil if the position property is set.
+  var _positionX: KeyframeGroup<Vector1D>? { get }
+
+  /// The positionY of the transform. This is nil if the position property is set.
+  var _positionY: KeyframeGroup<Vector1D>? { get }
+
+  /// The scale of the transform
+  var scale: KeyframeGroup<Vector3D> { get }
+
+  /// The rotation of the transform. Note: This is single dimensional rotation.
+  var rotation: KeyframeGroup<Vector1D> { get }
+}
+
+// MARK: - Transform + TransformModel
+
+extension Transform: TransformModel {
+  var _position: KeyframeGroup<Vector3D>? { position }
+  var _positionX: KeyframeGroup<Vector1D>? { positionX }
+  var _positionY: KeyframeGroup<Vector1D>? { positionY }
+}
+
+// MARK: - ShapeTransform + TransformModel
+
+extension ShapeTransform: TransformModel {
+  var anchorPoint: KeyframeGroup<Vector3D> { anchor }
+  var _position: KeyframeGroup<Vector3D>? { position }
+  var _positionX: KeyframeGroup<Vector1D>? { nil }
+  var _positionY: KeyframeGroup<Vector1D>? { nil }
+}
+
+// MARK: - CALayer + TransformModel
+
+extension CALayer {
+
+  // MARK: Internal
+
+  /// Adds transform-related animations from the given `TransformModel` to this layer
+  ///  - This _doesn't_ apply `transform.opacity`, which has to be handled separately
+  ///    since child layers don't inherit the `opacity` of their parent.
+  @nonobjc
+  func addTransformAnimations(for transformModel: TransformModel, context: LayerAnimationContext) throws {
+    try addPositionAnimations(from: transformModel, context: context)
+    try addAnchorPointAnimation(from: transformModel, context: context)
+    try addScaleAnimations(from: transformModel, context: context)
+    try addRotationAnimation(from: transformModel, context: context)
+  }
+
+  // MARK: Private
+
+  @nonobjc
+  private func addPositionAnimations(
+    from transformModel: TransformModel,
+    context: LayerAnimationContext)
+    throws
+  {
+    if let positionKeyframes = transformModel._position?.keyframes {
+      try addAnimation(
+        for: .position,
+        keyframes: positionKeyframes,
+        value: \.pointValue,
+        context: context)
+    } else if
+      let xKeyframes = transformModel._positionX?.keyframes,
+      let yKeyframes = transformModel._positionY?.keyframes
+    {
+      try addAnimation(
+        for: .positionX,
+        keyframes: xKeyframes,
+        value: \.cgFloatValue,
+        context: context)
+
+      try addAnimation(
+        for: .positionY,
+        keyframes: yKeyframes,
+        value: \.cgFloatValue,
+        context: context)
+    } else {
+      try context.logCompatibilityIssue("""
+        `Transform` values must provide either `position` or `positionX` / `positionY` keyframes
+        """)
+    }
+  }
+
+  @nonobjc
+  private func addAnchorPointAnimation(
+    from transformModel: TransformModel,
+    context: LayerAnimationContext)
+    throws
+  {
+    try addAnimation(
+      for: .anchorPoint,
+      keyframes: transformModel.anchorPoint.keyframes,
+      value: { absoluteAnchorPoint in
+        guard bounds.width > 0, bounds.height > 0 else {
+          context.logger.assertionFailure("Size must be non-zero before an animation can be played")
+          return .zero
+        }
+
+        // Lottie animation files express anchorPoint as an absolute point value,
+        // so we have to divide by the width/height of this layer to get the
+        // relative decimal values expected by Core Animation.
+        return CGPoint(
+          x: CGFloat(absoluteAnchorPoint.x) / bounds.width,
+          y: CGFloat(absoluteAnchorPoint.y) / bounds.height)
+      },
+      context: context)
+  }
+
+  @nonobjc
+  private func addScaleAnimations(
+    from transformModel: TransformModel,
+    context: LayerAnimationContext)
+    throws
+  {
+    try addAnimation(
+      for: .scaleX,
+      keyframes: transformModel.scale.keyframes,
+      value: { scale in
+        // Lottie animation files express scale as a numerical percentage value
+        // (e.g. 50%, 100%, 200%) so we divide by 100 to get the decimal values
+        // expected by Core Animation (e.g. 0.5, 1.0, 2.0).
+        //  - Negative `scale.x` values aren't applied correctly by Core Animation.
+        //    This appears to be because we animate `transform.scale.x` and `transform.scale.y`
+        //    as separate `CAKeyframeAnimation`s instead of using a single animation of `transform` itself.
+        //    https://openradar.appspot.com/FB9862872
+        //  - To work around this, we set up a `rotationY` animation below
+        //    to flip the view horizontally, which gives us the desired effect.
+        abs(CGFloat(scale.x) / 100)
+      },
+      context: context)
+
+    // When `scale.x` is negative, we have to rotate the view
+    // half way around the y axis to flip it horizontally.
+    //  - We don't do this in snapshot tests because it breaks the tests
+    //    in surprising ways that don't happen at runtime. Definitely not ideal.
+    if TestHelpers.snapshotTestsAreRunning {
+      if transformModel.scale.keyframes.contains(where: { $0.value.x < 0 }) {
+        context.logger.warn("""
+          Negative `scale.x` values are not displayed correctly in snapshot tests
+          """)
+      }
+    } else {
+      try addAnimation(
+        for: .rotationY,
+        keyframes: transformModel.scale.keyframes,
+        value: { scale in
+          if scale.x < 0 {
+            return .pi
+          } else {
+            return 0
+          }
+        },
+        context: context)
+    }
+
+    try addAnimation(
+      for: .scaleY,
+      keyframes: transformModel.scale.keyframes,
+      value: { scale in
+        // Lottie animation files express scale as a numerical percentage value
+        // (e.g. 50%, 100%, 200%) so we divide by 100 to get the decimal values
+        // expected by Core Animation (e.g. 0.5, 1.0, 2.0).
+        //  - Negative `scaleY` values are correctly applied (they flip the view
+        //    vertically), so we don't have to apply an additional rotation animation
+        //    like we do for `scaleX`.
+        CGFloat(scale.y) / 100
+      },
+      context: context)
+  }
+
+  private func addRotationAnimation(
+    from transformModel: TransformModel,
+    context: LayerAnimationContext)
+    throws
+  {
+    try addAnimation(
+      for: .rotation,
+      keyframes: transformModel.rotation.keyframes,
+      value: { rotationDegrees in
+        // Lottie animation files express rotation in degrees
+        // (e.g. 90º, 180º, 360º) so we covert to radians to get the
+        // values expected by Core Animation (e.g. π/2, π, 2π)
+        rotationDegrees.cgFloatValue * .pi / 180
+      },
+      context: context)
+  }
+
+}

package/Sources/Private/CoreAnimation/Animations/VisibilityAnimation.swift

@@ -0,0 +1,37 @@
+// Created by Cal Stephens on 12/21/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CALayer {
+  /// Adds an animation for the given `inTime` and `outTime` to this `CALayer`
+  @nonobjc
+  func addVisibilityAnimation(
+    inFrame: AnimationFrameTime,
+    outFrame: AnimationFrameTime,
+    context: LayerAnimationContext)
+  {
+    let animation = CAKeyframeAnimation(keyPath: #keyPath(isHidden))
+    animation.calculationMode = .discrete
+
+    animation.values = [
+      true, // hidden, before `inFrame`
+      false, // visible
+      true, // hidden, after `outFrame`
+    ]
+
+    // From the documentation of `keyTimes`:
+    //  - If the calculationMode is set to discrete, the first value in the array
+    //    must be 0.0 and the last value must be 1.0. The array should have one more
+    //    entry than appears in the values array. For example, if there are two values,
+    //    there should be three key times.
+    animation.keyTimes = [
+      NSNumber(value: 0.0),
+      NSNumber(value: max(Double(context.progressTime(for: inFrame)), 0)),
+      NSNumber(value: min(Double(context.progressTime(for: outFrame)), 1)),
+      NSNumber(value: 1.0),
+    ]
+
+    add(animation, timedWith: context)
+  }
+}