lottie-ios 3.2.3 → 3.4.0

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

@@ -0,0 +1,61 @@
+// Created by Cal Stephens on 1/28/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+// MARK: - Keyframes
+
+enum Keyframes {
+  /// Combines the given `[KeyframeGroup]` of `Keyframe<T>`s
+  /// into a single `KeyframeGroup` of `Keyframe<[T]>`s
+  /// if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T>(_ groups: [KeyframeGroup<T>]) -> KeyframeGroup<[T]>? {
+    guard
+      !groups.isEmpty,
+      groups.allSatisfy({ $0.hasSameTimingParameters(as: groups[0]) })
+    else { return nil }
+
+    var combinedKeyframes = ContiguousArray<Keyframe<[T]>>()
+
+    for index in groups[0].keyframes.indices {
+      let baseKeyframe = groups[0].keyframes[index]
+      let combinedValues = groups.map { $0.keyframes[index].value }
+      combinedKeyframes.append(baseKeyframe.withValue(combinedValues))
+    }
+
+    return KeyframeGroup(keyframes: combinedKeyframes)
+  }
+
+  /// Combines the given `[KeyframeGroup?]` of `Keyframe<T>`s
+  /// into a single `KeyframeGroup` of `Keyframe<[T]>`s
+  /// if all of the `KeyframeGroup`s have the exact same animation timing
+  static func combinedIfPossible<T>(_ groups: [KeyframeGroup<T>?]) -> KeyframeGroup<[T]>? {
+    let nonOptionalGroups = groups.compactMap { $0 }
+    guard nonOptionalGroups.count == groups.count else { return nil }
+    return combinedIfPossible(nonOptionalGroups)
+  }
+}
+
+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
+  func hasSameTimingParameters<T>(as other: Keyframe<T>) -> Bool {
+    time == other.time
+      && isHold == other.isHold
+      && inTangent == other.inTangent
+      && outTangent == other.outTangent
+      && spatialInTangent == other.spatialInTangent
+      && spatialOutTangent == other.spatialOutTangent
+  }
+}

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

@@ -0,0 +1,77 @@
+// 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)
+  }
+
+  /// 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,87 @@
+// 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
+    {
+      mask = MaskCompositionLayer(masks: masks)
+    }
+  }
+
+}

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

@@ -0,0 +1,131 @@
+// Created by Cal Stephens on 1/11/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+extension CALayer {
+  /// 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, maskLayerModel) 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 maskLayerModel = maskLayerModel,
+        let maskLayer = try maskLayerModel.makeAnimationLayer(context: context)
+      {
+        let maskParentTransformLayer = makeParentTransformLayer(
+          childLayerModel: maskLayerModel,
+          childLayer: maskLayer,
+          name: { parentLayerModel in
+            "\(maskLayerModel.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)
+      }
+    }
+  }
+
+}
+
+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: LayerModel?)] {
+    var layersAndMasks = [(layer: LayerModel, mask: LayerModel?)]()
+    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()
+      {
+        try context.compatibilityAssert(
+          matteType == .add,
+          "The Core Animation rendering engine currently only supports `MatteMode.add`.")
+
+        layersAndMasks.append((layer: layer, mask: maskLayer))
+      }
+
+      else {
+        layersAndMasks.append((layer: layer, mask: nil))
+      }
+    }
+
+    return layersAndMasks
+  }
+}

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

@@ -0,0 +1,87 @@
+// 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 = 2_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)
+
+    transform = CATransform3DMakeTranslation(
+      -gradientPadding,
+      -gradientPadding,
+      0)
+  }
+
+}
+
+// MARK: CustomLayoutLayer
+
+extension GradientRenderLayer: CustomLayoutLayer {
+  func layout(superlayerBounds: CGRect) {
+    gradientReferenceBounds = superlayerBounds
+  }
+}

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

@@ -0,0 +1,79 @@
+// Created by Cal Stephens on 1/10/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - ImageLayer
+
+/// The `CALayer` type responsible for rendering `ImageLayerModel`s
+final class ImageLayer: BaseCompositionLayer {
+
+  // MARK: Lifecycle
+
+  init(
+    imageLayer: ImageLayerModel,
+    context: LayerContext)
+  {
+    self.imageLayer = imageLayer
+    super.init(layerModel: imageLayer)
+    setupImage(context: context)
+  }
+
+  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))")
+    }
+
+    imageLayer = typedLayer.imageLayer
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Internal
+
+  func setupImage(context: LayerContext) {
+    guard
+      let imageAsset = context.animation.assetLibrary?.imageAssets[imageLayer.referenceID],
+      let image = context.imageProvider.imageForAsset(asset: imageAsset)
+    else {
+      self.imageAsset = nil
+      contents = nil
+      return
+    }
+
+    self.imageAsset = imageAsset
+    contents = image
+    setNeedsLayout()
+  }
+
+  // MARK: Private
+
+  private let imageLayer: ImageLayerModel
+  private var imageAsset: ImageAsset?
+
+}
+
+// MARK: CustomLayoutLayer
+
+extension ImageLayer: CustomLayoutLayer {
+  func layout(superlayerBounds: CGRect) {
+    anchorPoint = .zero
+
+    guard let imageAsset = imageAsset else {
+      bounds = superlayerBounds
+      return
+    }
+
+    // Image layers specifically need to use the size of the image itself
+    bounds = CGRect(
+      x: superlayerBounds.origin.x,
+      y: superlayerBounds.origin.y,
+      width: CGFloat(imageAsset.width),
+      height: CGFloat(imageAsset.height))
+  }
+}

package/Sources/Private/CoreAnimation/Layers/LayerModel+makeAnimationLayer.swift

@@ -0,0 +1,60 @@
+// Created by Cal Stephens on 12/20/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - LayerContext
+
+/// Context available when constructing an `AnimationLayer`
+struct LayerContext {
+  let animation: Animation
+  let imageProvider: AnimationImageProvider
+  let fontProvider: AnimationFontProvider
+  let compatibilityTracker: CompatibilityTracker
+  var layerName: String
+
+  func forLayer(_ layer: LayerModel) -> LayerContext {
+    var context = self
+    context.layerName = layer.name
+    return context
+  }
+}
+
+// MARK: - LayerModel + makeAnimationLayer
+
+extension LayerModel {
+  /// Constructs an `AnimationLayer` / `CALayer` that represents this `LayerModel`
+  func makeAnimationLayer(context: LayerContext) throws -> BaseCompositionLayer? {
+    let context = context.forLayer(self)
+
+    switch (type, self) {
+    case (.precomp, let preCompLayerModel as PreCompLayerModel):
+      let preCompLayer = PreCompLayer(preCompLayer: preCompLayerModel)
+      try preCompLayer.setup(context: context)
+      return preCompLayer
+
+    case (.solid, let solidLayerModel as SolidLayerModel):
+      return SolidLayer(solidLayerModel)
+
+    case (.shape, let shapeLayerModel as ShapeLayerModel):
+      return try ShapeLayer(shapeLayer: shapeLayerModel, context: context)
+
+    case (.image, let imageLayerModel as ImageLayerModel):
+      return ImageLayer(imageLayer: imageLayerModel, context: context)
+
+    case (.text, let textLayerModel as TextLayerModel):
+      return try TextLayer(textLayerModel: textLayerModel, context: context)
+
+    case (.null, _):
+      return TransformLayer(layerModel: self)
+
+    default:
+      try context.logCompatibilityIssue("""
+        Unexpected layer type combination ("\(type)" and "\(Swift.type(of: self))")
+        """)
+
+      return nil
+    }
+  }
+
+}