lottie-ios 3.2.3 → 3.4.2

package/Sources/Private/CoreAnimation/Extensions/Keyframes+combinedIfPossible.swift

@@ -0,0 +1,154 @@
+// Created by Cal Stephens on 1/28/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+// MARK: - Keyframes
+
+enum Keyframes {
+
+  // MARK: Internal
+
+  /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of
+  /// of `Keyframe<[T]>`s if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T>(_ allGroups: [KeyframeGroup<T>]) -> KeyframeGroup<[T]>? {
+    combinedIfPossible(allGroups, makeCombinedResult: { index in
+      allGroups.map { $0.valueForCombinedKeyframes(at: index) }
+    })
+  }
+
+  /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of
+  /// of `Keyframe<[T]>`s if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T1, T2, CombinedResult>(
+    _ k1: KeyframeGroup<T1>,
+    _ k2: KeyframeGroup<T2>,
+    makeCombinedResult: (T1, T2) -> CombinedResult)
+    -> KeyframeGroup<CombinedResult>?
+  {
+    combinedIfPossible(
+      [k1, k2],
+      makeCombinedResult: { index in
+        makeCombinedResult(
+          k1.valueForCombinedKeyframes(at: index),
+          k2.valueForCombinedKeyframes(at: index))
+      })
+  }
+
+  /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of
+  /// of `Keyframe<[T]>`s if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T1, T2, T3, CombinedResult>(
+    _ k1: KeyframeGroup<T1>,
+    _ k2: KeyframeGroup<T2>,
+    _ k3: KeyframeGroup<T3>,
+    makeCombinedResult: (T1, T2, T3) -> CombinedResult)
+    -> KeyframeGroup<CombinedResult>?
+  {
+    combinedIfPossible(
+      [k1, k2, k3],
+      makeCombinedResult: { index in
+        makeCombinedResult(
+          k1.valueForCombinedKeyframes(at: index),
+          k2.valueForCombinedKeyframes(at: index),
+          k3.valueForCombinedKeyframes(at: index))
+      })
+  }
+
+  /// Combines the given keyframe groups of `Keyframe<T>`s into a single keyframe group of
+  /// of `Keyframe<[T]>`s if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T1, T2, T3, T4, T5, T6, T7, CombinedResult>(
+    _ k1: KeyframeGroup<T1>,
+    _ k2: KeyframeGroup<T2>,
+    _ k3: KeyframeGroup<T3>,
+    _ k4: KeyframeGroup<T4>,
+    _ k5: KeyframeGroup<T5>,
+    _ k6: KeyframeGroup<T6>,
+    _ k7: KeyframeGroup<T7>,
+    makeCombinedResult: (T1, T2, T3, T4, T5, T6, T7) -> CombinedResult)
+    -> KeyframeGroup<CombinedResult>?
+  {
+    combinedIfPossible(
+      [k1, k2, k3, k4, k5, k6, k7],
+      makeCombinedResult: { index in
+        makeCombinedResult(
+          k1.valueForCombinedKeyframes(at: index),
+          k2.valueForCombinedKeyframes(at: index),
+          k3.valueForCombinedKeyframes(at: index),
+          k4.valueForCombinedKeyframes(at: index),
+          k5.valueForCombinedKeyframes(at: index),
+          k6.valueForCombinedKeyframes(at: index),
+          k7.valueForCombinedKeyframes(at: index))
+      })
+  }
+
+  // MARK: Private
+
+  /// Combines the given `[KeyframeGroup]` of `Keyframe<T>`s into a single `KeyframeGroup`
+  /// of `Keyframe<CombinedResult>`s if all of the `KeyframeGroup`s have the exact same animation timing
+  private static func combinedIfPossible<CombinedResult>(
+    _ allGroups: [AnyKeyframeGroup],
+    makeCombinedResult: (_ index: Int) -> CombinedResult)
+    -> KeyframeGroup<CombinedResult>?
+  {
+    let untypedGroups = allGroups.map { $0.untyped }
+
+    // Animations with no timing information (e.g. with just a single keyframe)
+    // can be trivially combined with any other set of keyframes, so we don't need
+    // to check those.
+    let animatingKeyframes = untypedGroups.filter { $0.keyframes.count > 1 }
+
+    guard
+      !allGroups.isEmpty,
+      animatingKeyframes.allSatisfy({ $0.hasSameTimingParameters(as: animatingKeyframes[0]) })
+    else { return nil }
+
+    var combinedKeyframes = ContiguousArray<Keyframe<CombinedResult>>()
+    let baseKeyframes = (animatingKeyframes.first ?? untypedGroups[0]).keyframes
+
+    for index in baseKeyframes.indices {
+      let baseKeyframe = baseKeyframes[index]
+      let combinedValue = makeCombinedResult(index)
+      combinedKeyframes.append(baseKeyframe.withValue(combinedValue))
+    }
+
+    return KeyframeGroup(keyframes: combinedKeyframes)
+  }
+
+}
+
+extension KeyframeGroup {
+  /// Whether or not all of the keyframes in this `KeyframeGroup` have the same
+  /// timing parameters as the corresponding keyframe in the other given `KeyframeGroup`
+  func hasSameTimingParameters<T>(as other: KeyframeGroup<T>) -> Bool {
+    guard keyframes.count == other.keyframes.count else {
+      return false
+    }
+
+    return zip(keyframes, other.keyframes).allSatisfy {
+      $0.hasSameTimingParameters(as: $1)
+    }
+  }
+}
+
+extension Keyframe {
+  /// Whether or not this keyframe has the same timing parameters as the given keyframe,
+  /// excluding `spatialInTangent` and `spatialOutTangent`.
+  fileprivate func hasSameTimingParameters<T>(as other: Keyframe<T>) -> Bool {
+    time == other.time
+      && isHold == other.isHold
+      && inTangent == other.inTangent
+      && outTangent == other.outTangent
+    // We intentionally don't compare spatial in/out tangents,
+    // since those values are only used in very specific cases
+    // (animating the x/y position of a layer), which aren't ever
+    // combined in this way.
+  }
+}
+
+extension KeyframeGroup {
+  /// The value to use for a combined set of keyframes, for the given index
+  fileprivate func valueForCombinedKeyframes(at index: Int) -> T {
+    if keyframes.count == 1 {
+      return keyframes[0].value
+    } else {
+      return keyframes[index].value
+    }
+  }
+}

package/Sources/Private/CoreAnimation/Layers/AnimationLayer.swift

@@ -0,0 +1,83 @@
+// Created by Cal Stephens on 12/14/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - AnimationLayer
+
+/// A type of `CALayer` that can be used in a Lottie animation
+///  - Layers backed by a `LayerModel` subclass should subclass `BaseCompositionLayer`
+protocol AnimationLayer: CALayer {
+  /// Instructs this layer to setup its `CAAnimation`s
+  /// using the given `LayerAnimationContext`
+  func setupAnimations(context: LayerAnimationContext) throws
+}
+
+// MARK: - LayerAnimationContext
+
+// Context describing the timing parameters of the current animation
+struct LayerAnimationContext {
+  /// The animation being played
+  let animation: Animation
+
+  /// The timing configuration that should be applied to `CAAnimation`s
+  let timingConfiguration: CoreAnimationLayer.CAMediaTimingConfiguration
+
+  /// The absolute frame number that this animation begins at
+  let startFrame: AnimationFrameTime
+
+  /// The absolute frame number that this animation ends at
+  let endFrame: AnimationFrameTime
+
+  /// The set of custom Value Providers applied to this animation
+  let valueProviderStore: ValueProviderStore
+
+  /// Information about whether or not an animation is compatible with the Core Animation engine
+  let compatibilityTracker: CompatibilityTracker
+
+  /// The logger that should be used for assertions and warnings
+  let logger: LottieLogger
+
+  /// The AnimationKeypath represented by the current layer
+  var currentKeypath: AnimationKeypath
+
+  /// Whether or not to log `AnimationKeypath`s for all of the animation's layers
+  ///  - Used for `CoreAnimationLayer.logHierarchyKeypaths()`
+  var logHierarchyKeypaths: Bool
+
+  /// A closure that remaps the given frame in the child layer's local time to a frame
+  /// in the animation's overall global time
+  private(set) var timeRemapping: ((AnimationFrameTime) -> AnimationFrameTime) = { $0 }
+
+  /// Adds the given component string to the `AnimationKeypath` stored
+  /// that describes the current path being configured by this context value
+  func addingKeypathComponent(_ component: String) -> LayerAnimationContext {
+    var context = self
+    context.currentKeypath.keys.append(component)
+    return context
+  }
+
+  /// The `AnimationProgressTime` for the given `AnimationFrameTime` within this layer,
+  /// accounting for the `timeRemapping` applied to this layer
+  func progressTime(for frame: AnimationFrameTime) -> AnimationProgressTime {
+    animation.progressTime(forFrame: timeRemapping(frame), clamped: false)
+  }
+
+  /// The real-time `TimeInterval` for the given `AnimationFrameTime` within this layer,
+  /// accounting for the `timeRemapping` applied to this layer
+  func time(for frame: AnimationFrameTime) -> TimeInterval {
+    animation.time(forFrame: timeRemapping(frame))
+  }
+
+  /// Chains an additional `timeRemapping` closure onto this layer context
+  func withTimeRemapping(
+    _ additionalTimeRemapping: @escaping (AnimationFrameTime) -> AnimationFrameTime)
+    -> LayerAnimationContext
+  {
+    var copy = self
+    copy.timeRemapping = { [existingTimeRemapping = timeRemapping] time in
+      existingTimeRemapping(additionalTimeRemapping(time))
+    }
+    return copy
+  }
+}

package/Sources/Private/CoreAnimation/Layers/BaseAnimationLayer.swift

@@ -0,0 +1,33 @@
+// Created by Cal Stephens on 1/27/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+/// A base `CALayer` that manages the frame and animations
+/// of its `sublayers` and `mask`
+class BaseAnimationLayer: CALayer, AnimationLayer {
+
+  // MARK: Internal
+
+  override func layoutSublayers() {
+    super.layoutSublayers()
+
+    for sublayer in managedSublayers {
+      sublayer.fillBoundsOfSuperlayer()
+    }
+  }
+
+  func setupAnimations(context: LayerAnimationContext) throws {
+    for childAnimationLayer in managedSublayers {
+      try (childAnimationLayer as? AnimationLayer)?.setupAnimations(context: context)
+    }
+  }
+
+  // MARK: Private
+
+  /// All of the sublayers managed by this container
+  private var managedSublayers: [CALayer] {
+    (sublayers ?? []) + [mask].compactMap { $0 }
+  }
+
+}

package/Sources/Private/CoreAnimation/Layers/BaseCompositionLayer.swift

@@ -0,0 +1,88 @@
+// Created by Cal Stephens on 12/20/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - BaseCompositionLayer
+
+/// The base type of `AnimationLayer` that can contain other `AnimationLayer`s
+class BaseCompositionLayer: BaseAnimationLayer {
+
+  // MARK: Lifecycle
+
+  init(layerModel: LayerModel) {
+    baseLayerModel = layerModel
+    super.init()
+
+    setupSublayers()
+    compositingFilter = layerModel.blendMode.filterName
+    name = layerModel.name
+  }
+
+  required init?(coder _: NSCoder) {
+    fatalError("init(coder:) has not been implemented")
+  }
+
+  /// Called by CoreAnimation to create a shadow copy of this layer
+  /// More details: https://developer.apple.com/documentation/quartzcore/calayer/1410842-init
+  override init(layer: Any) {
+    guard let typedLayer = layer as? Self else {
+      fatalError("\(Self.self).init(layer:) incorrectly called with \(type(of: layer))")
+    }
+
+    baseLayerModel = typedLayer.baseLayerModel
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Internal
+
+  /// Whether or not this layer render should render any visible content
+  var renderLayerContents: Bool { true }
+
+  /// Sets up the base `LayerModel` animations for this layer,
+  /// and all child `AnimationLayer`s.
+  ///  - Can be overridden by subclasses, which much call `super`.
+  override func setupAnimations(context: LayerAnimationContext) throws {
+    var context = context
+    if renderLayerContents {
+      context = context.addingKeypathComponent(baseLayerModel.name)
+    }
+
+    try setupLayerAnimations(context: context)
+    try setupChildAnimations(context: context)
+  }
+
+  func setupLayerAnimations(context: LayerAnimationContext) throws {
+    let context = context.addingKeypathComponent(baseLayerModel.name)
+
+    try addTransformAnimations(for: baseLayerModel.transform, context: context)
+
+    if renderLayerContents {
+      try addOpacityAnimation(for: baseLayerModel.transform, context: context)
+
+      addVisibilityAnimation(
+        inFrame: CGFloat(baseLayerModel.inFrame),
+        outFrame: CGFloat(baseLayerModel.outFrame),
+        context: context)
+    }
+  }
+
+  func setupChildAnimations(context: LayerAnimationContext) throws {
+    try super.setupAnimations(context: context)
+  }
+
+  // MARK: Private
+
+  private let baseLayerModel: LayerModel
+
+  private func setupSublayers() {
+    if
+      renderLayerContents,
+      let masks = baseLayerModel.masks?.filter({ $0.mode != .none }),
+      !masks.isEmpty
+    {
+      mask = MaskCompositionLayer(masks: masks)
+    }
+  }
+
+}

package/Sources/Private/CoreAnimation/Layers/CALayer+setupLayerHierarchy.swift

@@ -0,0 +1,167 @@
+// Created by Cal Stephens on 1/11/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CALayer {
+
+  // MARK: Internal
+
+  /// Sets up an `AnimationLayer` / `CALayer` hierarchy in this layer,
+  /// using the given list of layers.
+  @nonobjc
+  func setupLayerHierarchy(
+    for layers: [LayerModel],
+    context: LayerContext)
+    throws
+  {
+    // An `Animation`'s `LayerModel`s are listed from front to back,
+    // but `CALayer.sublayers` are listed from back to front.
+    // We reverse the layer ordering to match what Core Animation expects.
+    // The final view hierarchy must display the layers in this exact order.
+    let layersInZAxisOrder = layers.reversed()
+
+    let layersByIndex = Dictionary(grouping: layersInZAxisOrder, by: \.index)
+      .compactMapValues(\.first)
+
+    /// Layers specify a `parent` layer. Child layers inherit the `transform` of their parent.
+    ///  - We can't add the child as a sublayer of the parent `CALayer`, since that would
+    ///    break the ordering specified in `layersInZAxisOrder`.
+    ///  - Instead, we create an invisible `TransformLayer` to handle the parent
+    ///    transform animations, and add the child layer to that `TransformLayer`.
+    func makeParentTransformLayer(
+      childLayerModel: LayerModel,
+      childLayer: CALayer,
+      name: (LayerModel) -> String)
+      -> CALayer
+    {
+      guard
+        let parentIndex = childLayerModel.parent,
+        let parentLayerModel = layersByIndex[parentIndex]
+      else { return childLayer }
+
+      let parentLayer = TransformLayer(layerModel: parentLayerModel)
+      parentLayer.name = name(parentLayerModel)
+      parentLayer.addSublayer(childLayer)
+
+      return makeParentTransformLayer(
+        childLayerModel: parentLayerModel,
+        childLayer: parentLayer,
+        name: name)
+    }
+
+    // Create an `AnimationLayer` for each `LayerModel`
+    for (layerModel, mask) in try layersInZAxisOrder.pairedLayersAndMasks(context: context) {
+      guard let layer = try layerModel.makeAnimationLayer(context: context) else {
+        continue
+      }
+
+      // If this layer has a `parent`, we create an invisible `TransformLayer`
+      // to handle displaying / animating the parent transform.
+      let parentTransformLayer = makeParentTransformLayer(
+        childLayerModel: layerModel,
+        childLayer: layer,
+        name: { parentLayerModel in
+          "\(layerModel.name) (parent, \(parentLayerModel.name))"
+        })
+
+      // Create the `mask` layer for this layer, if it has a `MatteType`
+      if
+        let mask = mask,
+        let maskLayer = try maskLayer(for: mask.model, type: mask.matteType, context: context)
+      {
+        let maskParentTransformLayer = makeParentTransformLayer(
+          childLayerModel: mask.model,
+          childLayer: maskLayer,
+          name: { parentLayerModel in
+            "\(mask.model.name) (mask of \(layerModel.name)) (parent, \(parentLayerModel.name))"
+          })
+
+        // Set up a parent container to host both the layer
+        // and its mask in the same coordinate space
+        let maskContainer = BaseAnimationLayer()
+        maskContainer.name = "\(layerModel.name) (parent, masked)"
+        maskContainer.addSublayer(parentTransformLayer)
+
+        // Core Animation will silently fail to apply a mask if a `mask` layer
+        // itself _also_ has a `mask`. As a workaround, we can wrap this layer's
+        // mask in an additional container layer which never has its own `mask`.
+        let additionalMaskParent = BaseAnimationLayer()
+        additionalMaskParent.addSublayer(maskParentTransformLayer)
+        maskContainer.mask = additionalMaskParent
+
+        addSublayer(maskContainer)
+      }
+
+      else {
+        addSublayer(parentTransformLayer)
+      }
+    }
+  }
+
+  // MARK: Fileprivate
+
+  /// Creates a mask `CALayer` from the given matte layer model, using the `MatteType`
+  /// from the layer that is being masked.
+  fileprivate func maskLayer(
+    for matteLayerModel: LayerModel,
+    type: MatteType,
+    context: LayerContext) throws
+    -> CALayer?
+  {
+    switch type {
+    case .add:
+      return try matteLayerModel.makeAnimationLayer(context: context)
+
+    case .invert:
+      guard let maskLayer = try matteLayerModel.makeAnimationLayer(context: context) else {
+        return nil
+      }
+
+      // We can invert the mask layer by having a large solid black layer with the
+      // given mask layer subtracted out using the `xor` blend mode. When applied to the
+      // layer being masked, this creates an inverted mask where only areas _outside_
+      // of the mask layer are visible.
+      // https://developer.apple.com/documentation/coregraphics/cgblendmode/xor
+      let base = BaseAnimationLayer()
+      base.backgroundColor = .rgb(0, 0, 0)
+      base.addSublayer(maskLayer)
+      maskLayer.compositingFilter = "xor"
+      return base
+
+    case .none, .unknown:
+      return nil
+    }
+  }
+
+}
+
+extension Collection where Element == LayerModel {
+  /// Pairs each `LayerModel` within this array with
+  /// a `LayerModel` to use as its mask, if applicable
+  /// based on the layer's `MatteType` configuration.
+  ///  - Assumes the layers are sorted in z-axis order.
+  fileprivate func pairedLayersAndMasks(context _: LayerContext) throws
+    -> [(layer: LayerModel, mask: (model: LayerModel, matteType: MatteType)?)]
+  {
+    var layersAndMasks = [(layer: LayerModel, mask: (model: LayerModel, matteType: MatteType)?)]()
+    var unprocessedLayers = reversed()
+
+    while let layer = unprocessedLayers.popLast() {
+      /// If a layer has a `MatteType`, then the next layer will be used as its `mask`
+      if
+        let matteType = layer.matte,
+        matteType != .none,
+        let maskLayer = unprocessedLayers.popLast()
+      {
+        layersAndMasks.append((layer: layer, mask: (model: maskLayer, matteType: matteType)))
+      }
+
+      else {
+        layersAndMasks.append((layer: layer, mask: nil))
+      }
+    }
+
+    return layersAndMasks
+  }
+}

package/Sources/Private/CoreAnimation/Layers/GradientRenderLayer.swift

@@ -0,0 +1,94 @@
+// Created by Cal Stephens on 1/10/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - GradientRenderLayer
+
+/// A `CAGradientLayer` subclass used to render a gradient _outside_ the normal layer bounds
+///
+///  - `GradientFill.startPoint` and `GradientFill.endPoint` are expressed
+///    with respect to the `bounds` of the `ShapeItemLayer`.
+///
+///  - The gradient itself is supposed to be rendered infinitely in all directions
+///    (e.g. including outside of `bounds`). This is because `ShapeItemLayer` paths
+///    don't necessarily sit within the layer's `bounds`.
+///
+///  - To support this, `GradientRenderLayer` tracks a `gradientReferenceBounds`
+///    that `startPoint` / `endPoint` are calculated relative to.
+///    The _actual_ `bounds` of this layer is padded by a large amount so that
+///    the gradient can be drawn outside of the `gradientReferenceBounds`.
+///
+final class GradientRenderLayer: CAGradientLayer {
+
+  // MARK: Internal
+
+  /// The reference bounds within this layer that the gradient's
+  /// `startPoint` and `endPoint` should be calculated relative to
+  var gradientReferenceBounds: CGRect = .zero {
+    didSet {
+      if oldValue != gradientReferenceBounds {
+        updateLayout()
+      }
+    }
+  }
+
+  /// Converts the given `CGPoint` within `gradientReferenceBounds`
+  /// to a percentage value relative to the full `bounds` of this layer
+  ///  - This converts absolute `startPoint` and `endPoint` values into
+  ///    the percent-based values expected by Core Animation,
+  ///    with respect to the custom bounds geometry used by this layer type.
+  func percentBasedPointInBounds(from referencePoint: CGPoint) -> CGPoint {
+    guard bounds.width > 0, bounds.height > 0 else {
+      LottieLogger.shared.assertionFailure("Size must be non-zero before an animation can be played")
+      return .zero
+    }
+
+    let pointInBounds = CGPoint(
+      x: referencePoint.x + gradientPadding,
+      y: referencePoint.y + gradientPadding)
+
+    return CGPoint(
+      x: CGFloat(pointInBounds.x) / bounds.width,
+      y: CGFloat(pointInBounds.y) / bounds.height)
+  }
+
+  // MARK: Private
+
+  /// Extra padding around the `gradientReferenceBounds` where the gradient is also rendered
+  ///  - This specific value is arbitrary and can be increased if necessary.
+  ///    Theoretically this should be "infinite", to match the behavior of
+  ///    `CGContext.drawLinearGradient` with `[.drawsAfterEndLocation, .drawsBeforeStartLocation]`.
+  private let gradientPadding: CGFloat = 10_000
+
+  private func updateLayout() {
+    anchorPoint = .zero
+
+    bounds = CGRect(
+      x: gradientReferenceBounds.origin.x,
+      y: gradientReferenceBounds.origin.y,
+      width: gradientPadding + gradientReferenceBounds.width + gradientPadding,
+      height: gradientPadding + gradientReferenceBounds.height + gradientPadding)
+
+    // Align the center of this layer to be at the center point of its parent layer
+    let superlayerSize = superlayer?.frame.size ?? gradientReferenceBounds.size
+
+    transform = CATransform3DMakeTranslation(
+      (superlayerSize.width - bounds.width) / 2,
+      (superlayerSize.height - bounds.height) / 2,
+      0)
+  }
+
+}
+
+// MARK: CustomLayoutLayer
+
+extension GradientRenderLayer: CustomLayoutLayer {
+  func layout(superlayerBounds: CGRect) {
+    gradientReferenceBounds = superlayerBounds
+
+    if let gradientMask = mask as? GradientRenderLayer {
+      gradientMask.layout(superlayerBounds: superlayerBounds)
+    }
+  }
+}