lottie-ios 3.2.0 → 3.4.0

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

@@ -0,0 +1,305 @@
+// Created by Cal Stephens on 12/14/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - ShapeLayer
+
+/// The CALayer type responsible for rendering `ShapeLayerModel`s
+final class ShapeLayer: BaseCompositionLayer {
+
+  // MARK: Lifecycle
+
+  init(shapeLayer: ShapeLayerModel, context: LayerContext) throws {
+    self.shapeLayer = shapeLayer
+    super.init(layerModel: shapeLayer)
+    try setupGroups(from: shapeLayer.items, parentGroup: nil, 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))")
+    }
+
+    shapeLayer = typedLayer.shapeLayer
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Private
+
+  private let shapeLayer: ShapeLayerModel
+
+}
+
+// MARK: - GroupLayer
+
+/// The CALayer type responsible for rendering `Group`s
+final class GroupLayer: BaseAnimationLayer {
+
+  // MARK: Lifecycle
+
+  init(group: Group, inheritedItems: [ShapeItemLayer.Item], context: LayerContext) throws {
+    self.group = group
+    self.inheritedItems = inheritedItems
+    super.init()
+    try setupLayerHierarchy(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))")
+    }
+
+    group = typedLayer.group
+    inheritedItems = typedLayer.inheritedItems
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Internal
+
+  override func setupAnimations(context: LayerAnimationContext) throws {
+    try super.setupAnimations(context: context)
+
+    if let (shapeTransform, context) = nonGroupItems.first(ShapeTransform.self, context: context) {
+      try addTransformAnimations(for: shapeTransform, context: context)
+      try addOpacityAnimation(for: shapeTransform, context: context)
+    }
+  }
+
+  // MARK: Private
+
+  private let group: Group
+
+  /// `ShapeItem`s that were listed in the parent's `items: [ShapeItem]` array
+  ///   - This layer's parent is either the root `ShapeLayerModel` or some other `Group`
+  private let inheritedItems: [ShapeItemLayer.Item]
+
+  /// `ShapeItem`s (other than nested `Group`s) that are included in this group
+  private lazy var nonGroupItems = group.items
+    .filter { !($0 is Group) }
+    .map { ShapeItemLayer.Item(item: $0, parentGroup: group) }
+    + inheritedItems
+
+  private func setupLayerHierarchy(context: LayerContext) throws {
+    // Groups can contain other groups, so we may have to continue
+    // recursively creating more `GroupLayer`s
+    try setupGroups(from: group.items, parentGroup: group, context: context)
+
+    // Create `ShapeItemLayer`s for each subgroup of shapes that should be rendered as a single unit
+    //  - These groups are listed from front-to-back, so we have to add the sublayers in reverse order
+    for shapeRenderGroup in nonGroupItems.shapeRenderGroups.reversed() {
+      // If all of the path-drawing `ShapeItem`s have keyframes with the same timing information,
+      // we can combine the `[KeyframeGroup<BezierPath>]` (which have to animate in separate layers)
+      // into a single `KeyframeGroup<[BezierPath]>`, which can be combined into a single CGPath animation.
+      //
+      // This is how Groups with multiple path-drawing items are supposed to be rendered,
+      // because combining multiple paths into a single `CGPath` (instead of rendering them in separate layers)
+      // allows `CAShapeLayerFillRule.evenOdd` to be applied if the paths overlap. We just can't do this
+      // in all cases, due to limitations of Core Animation.
+      if
+        shapeRenderGroup.pathItems.count > 1,
+        let combinedShapeKeyframes = Keyframes.combinedIfPossible(
+          shapeRenderGroup.pathItems.map { ($0.item as? Shape)?.path }),
+        // `Trim`s are currently only applied correctly using individual `ShapeItemLayer`s,
+        // because each path has to be trimmed separately.
+        !shapeRenderGroup.otherItems.contains(where: { $0.item is Trim })
+      {
+        let combinedShape = CombinedShapeItem(
+          shapes: combinedShapeKeyframes,
+          name: group.name)
+
+        let sublayer = try ShapeItemLayer(
+          shape: ShapeItemLayer.Item(item: combinedShape, parentGroup: group),
+          otherItems: shapeRenderGroup.otherItems,
+          context: context)
+
+        addSublayer(sublayer)
+      }
+
+      // Otherwise, if each `ShapeItem` that draws a `GGPath` animates independently,
+      // we have to create a separate `ShapeItemLayer` for each one.
+      else {
+        for pathDrawingItem in shapeRenderGroup.pathItems {
+          let sublayer = try ShapeItemLayer(
+            shape: pathDrawingItem,
+            otherItems: shapeRenderGroup.otherItems,
+            context: context)
+
+          addSublayer(sublayer)
+        }
+      }
+    }
+  }
+
+}
+
+extension CALayer {
+  /// Sets up `GroupLayer`s for each `Group` in the given list of `ShapeItem`s
+  ///  - Each `Group` item becomes its own `GroupLayer` sublayer.
+  ///  - Other `ShapeItem` are applied to all sublayers
+  fileprivate func setupGroups(from items: [ShapeItem], parentGroup: Group?, context: LayerContext) throws {
+    let (groupItems, otherItems) = items.grouped(by: { $0 is Group })
+
+    // Groups are listed from front to back,
+    // but `CALayer.sublayers` are listed from back to front.
+    let groupsInZAxisOrder = groupItems.reversed()
+
+    for group in groupsInZAxisOrder {
+      guard let group = group as? Group else { continue }
+
+      // `ShapeItem`s either draw a path, or modify how a path is rendered.
+      //  - If this group doesn't have any items that draw a path, then its
+      //    items are applied to all of this groups children.
+      let inheritedItems: [ShapeItemLayer.Item]
+      if !otherItems.contains(where: { $0.drawsCGPath }) {
+        inheritedItems = otherItems.map {
+          ShapeItemLayer.Item(item: $0, parentGroup: parentGroup)
+        }
+      } else {
+        inheritedItems = []
+      }
+
+      let groupLayer = try GroupLayer(
+        group: group,
+        inheritedItems: inheritedItems,
+        context: context)
+
+      addSublayer(groupLayer)
+    }
+  }
+}
+
+extension ShapeItem {
+  /// Whether or not this `ShapeItem` is responsible for rendering a `CGPath`
+  var drawsCGPath: Bool {
+    switch type {
+    case .ellipse, .rectangle, .shape, .star:
+      return true
+
+    case .fill, .gradientFill, .group, .gradientStroke, .merge,
+         .repeater, .round, .stroke, .trim, .transform, .unknown:
+      return false
+    }
+  }
+
+  /// Whether or not this `ShapeItem` provides a fill for a set of shapes
+  var isFill: Bool {
+    switch type {
+    case .fill, .gradientFill:
+      return true
+
+    case .ellipse, .rectangle, .shape, .star, .group, .gradientStroke,
+         .merge, .repeater, .round, .stroke, .trim, .transform, .unknown:
+      return false
+    }
+  }
+
+  /// Whether or not this `ShapeItem` provides a stroke for a set of shapes
+  var isStroke: Bool {
+    switch type {
+    case .stroke, .gradientStroke:
+      return true
+
+    case .ellipse, .rectangle, .shape, .star, .group, .gradientFill,
+         .merge, .repeater, .round, .fill, .trim, .transform, .unknown:
+      return false
+    }
+  }
+}
+
+extension Collection {
+  /// Splits this collection into two groups, based on the given predicate
+  func grouped(by predicate: (Element) -> Bool) -> (trueElements: [Element], falseElements: [Element]) {
+    var trueElements = [Element]()
+    var falseElements = [Element]()
+
+    for element in self {
+      if predicate(element) {
+        trueElements.append(element)
+      } else {
+        falseElements.append(element)
+      }
+    }
+
+    return (trueElements, falseElements)
+  }
+}
+
+// MARK: - ShapeRenderGroup
+
+/// A group of `ShapeItem`s that should be rendered together as a single unit
+struct ShapeRenderGroup {
+  /// The items in this group that render `CGPath`s
+  var pathItems: [ShapeItemLayer.Item] = []
+  /// Shape items that modify the appearance of the shapes rendered by this group
+  var otherItems: [ShapeItemLayer.Item] = []
+}
+
+extension Array where Element == ShapeItemLayer.Item {
+  /// Splits this list of `ShapeItem`s into groups that should be rendered together as individual units
+  var shapeRenderGroups: [ShapeRenderGroup] {
+    var renderGroups = [ShapeRenderGroup()]
+
+    for item in self {
+      // `renderGroups` is non-empty, so is guaranteed to have a valid end index
+      let lastIndex = renderGroups.indices.last!
+
+      if item.item.drawsCGPath {
+        renderGroups[lastIndex].pathItems.append(item)
+      }
+
+      // `Fill` items are unique, because they specifically only apply to _previous_ shapes in a `Group`
+      //  - For example, with [Rectangle, Fill(Red), Circle, Fill(Blue)], the Rectangle should be Red
+      //    but the Circle should be Blue.
+      //  - To handle this, we create a new `ShapeRenderGroup` when we encounter a `Fill` item
+      else if item.item.isFill {
+        renderGroups[lastIndex].otherItems.append(item)
+        renderGroups.append(ShapeRenderGroup())
+      }
+
+      // Other items in the list are applied to all subgroups
+      else {
+        for index in renderGroups.indices {
+          renderGroups[index].otherItems.append(item)
+        }
+      }
+    }
+
+    // `Fill` and `Stroke` items have an `alpha` property that can be animated separately,
+    // but each layer only has a single `opacity` property, so we have to create
+    // separate layers / render groups for each of these if necessary.
+    return renderGroups.flatMap { group -> [ShapeRenderGroup] in
+      let (strokesAndFills, otherItems) = group.otherItems.grouped(by: { $0.item.isFill || $0.item.isStroke })
+
+      // However, if all of the strokes / fills have the exact same opacity animation configuration,
+      // then we can continue using a single layer / render group.
+      let allAlphaAnimationsAreIdentical = strokesAndFills.allSatisfy { item in
+        (item.item as? OpacityAnimationModel)?.opacity
+          == (strokesAndFills.first?.item as? OpacityAnimationModel)?.opacity
+      }
+
+      if allAlphaAnimationsAreIdentical {
+        return [group]
+      }
+
+      // Create a new group for each stroke / fill
+      return strokesAndFills.map { strokeOrFill in
+        ShapeRenderGroup(
+          pathItems: group.pathItems,
+          otherItems: [strokeOrFill] + otherItems)
+      }
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+// Created by Cal Stephens on 12/13/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - SolidLayer
+
+final class SolidLayer: BaseCompositionLayer {
+
+  // MARK: Lifecycle
+
+  init(_ solidLayer: SolidLayerModel) {
+    self.solidLayer = solidLayer
+    super.init(layerModel: solidLayer)
+    setupContentLayer()
+  }
+
+  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))")
+    }
+
+    solidLayer = typedLayer.solidLayer
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Private
+
+  private let solidLayer: SolidLayerModel
+
+  private func setupContentLayer() {
+    // Render the fill color in a child `CAShapeLayer`
+    //  - Using a `CAShapeLayer` specifically, instead of a `CALayer` with a `backgroundColor`,
+    //    allows the size of the fill shape to be different from `contentsLayer.size`.
+    let shapeLayer = CAShapeLayer()
+    shapeLayer.fillColor = solidLayer.colorHex.cgColor
+    shapeLayer.path = CGPath(rect: .init(x: 0, y: 0, width: solidLayer.width, height: solidLayer.height), transform: nil)
+    addSublayer(shapeLayer)
+  }
+
+}

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

@@ -0,0 +1,91 @@
+// Created by Cal Stephens on 2/9/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+/// The `CALayer` type responsible for rendering `TextLayer`s
+final class TextLayer: BaseCompositionLayer {
+
+  // MARK: Lifecycle
+
+  init(
+    textLayerModel: TextLayerModel,
+    context: LayerContext)
+    throws
+  {
+    self.textLayerModel = textLayerModel
+    super.init(layerModel: textLayerModel)
+    setupSublayers()
+    try configureRenderLayer(with: 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))")
+    }
+
+    textLayerModel = typedLayer.textLayerModel
+    super.init(layer: typedLayer)
+  }
+
+  // MARK: Internal
+
+  func configureRenderLayer(with context: LayerContext) throws {
+    // We can't use `CATextLayer`, because it doesn't support enough features we use.
+    // Instead, we use the same `CoreTextRenderLayer` (with a custom `draw` implementation)
+    // used by the Main Thread rendering engine. This means the Core Animation engine can't
+    // _animate_ text properties, but it can display static text without any issues.
+    let text = try textLayerModel.text.exactlyOneKeyframe(context: context, description: "text layer text").value
+
+    // The Core Animation engine doesn't currently support `TextAnimator`s.
+    //  - We could add support for animating the transform-related properties without much trouble.
+    //  - We may be able to support animating `fillColor` by getting clever with layer blend modes
+    //    or masks (e.g. use `CoreTextRenderLayer` to draw black glyphs, and then fill them in
+    //    using a `CAShapeLayer`).
+    if !textLayerModel.animators.isEmpty {
+      try context.logCompatibilityIssue("""
+        The Core Animation rendering engine currently doesn't support text animators.
+        """)
+    }
+
+    renderLayer.text = text.text
+    renderLayer.font = context.fontProvider.fontFor(family: text.fontFamily, size: CGFloat(text.fontSize))
+
+    renderLayer.alignment = text.justification.textAlignment
+    renderLayer.lineHeight = CGFloat(text.lineHeight)
+    renderLayer.tracking = (CGFloat(text.fontSize) * CGFloat(text.tracking)) / 1000
+
+    renderLayer.fillColor = text.fillColorData?.cgColorValue
+    renderLayer.strokeColor = text.strokeColorData?.cgColorValue
+    renderLayer.strokeWidth = CGFloat(text.strokeWidth ?? 0)
+    renderLayer.strokeOnTop = text.strokeOverFill ?? false
+
+    renderLayer.preferredSize = text.textFrameSize?.sizeValue
+    renderLayer.sizeToFit()
+
+    renderLayer.transform = CATransform3DIdentity
+    renderLayer.position = text.textFramePosition?.pointValue ?? .zero
+  }
+
+  // MARK: Private
+
+  private let textLayerModel: TextLayerModel
+  private let renderLayer = CoreTextRenderLayer()
+
+  private func setupSublayers() {
+    // Place the text render layer in an additional container
+    //  - Direct sublayers of a `BaseCompositionLayer` always fill the bounds
+    //    of their superlayer -- so this container will be the bounds of self,
+    //    and the text render layer can be positioned anywhere.
+    let textContainerLayer = CALayer()
+    textContainerLayer.addSublayer(renderLayer)
+    addSublayer(textContainerLayer)
+  }
+
+}

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

@@ -0,0 +1,11 @@
+// Created by Cal Stephens on 12/21/21.
+// Copyright © 2021 Airbnb Inc. All rights reserved.
+
+/// The CALayer type responsible for only rendering the `transform` of a `LayerModel`
+final class TransformLayer: BaseCompositionLayer {
+
+  /// `TransformLayer`s don't render any visible content,
+  /// they just `transform` their sublayers
+  override var renderLayerContents: Bool { false }
+
+}

package/Sources/Private/CoreAnimation/ValueProviderStore.swift

@@ -0,0 +1,139 @@
+// Created by Cal Stephens on 1/13/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import QuartzCore
+
+// MARK: - ValueProviderStore
+
+/// Registration and storage for `AnyValueProvider`s that can dynamically
+/// provide custom values for `AnimationKeypath`s within an `Animation`.
+final class ValueProviderStore {
+
+  // MARK: Lifecycle
+
+  init(logger: LottieLogger) {
+    self.logger = logger
+  }
+
+  // MARK: Internal
+
+  /// Registers an `AnyValueProvider` for the given `AnimationKeypath`
+  func setValueProvider(_ valueProvider: AnyValueProvider, keypath: AnimationKeypath) {
+    logger.assert(
+      valueProvider.typeErasedStorage.isSupportedByCoreAnimationRenderingEngine,
+      """
+      The Core Animation rendering engine doesn't support Value Providers that vend a closure,
+      because that would require calling the closure on the main thread once per frame.
+      """)
+
+    // TODO: Support more value types
+    logger.assert(
+      keypath.keys.last == PropertyName.color.rawValue,
+      "The Core Animation rendering engine currently only supports customizing color values")
+
+    valueProviders.append((keypath: keypath, valueProvider: valueProvider))
+  }
+
+  // Retrieves the custom value keyframes for the given property,
+  // if an `AnyValueProvider` was registered for the given keypath.
+  func customKeyframes<Value>(
+    of customizableProperty: CustomizableProperty<Value>,
+    for keypath: AnimationKeypath,
+    context: LayerAnimationContext)
+    throws
+    -> KeyframeGroup<Value>?
+  {
+    if context.logHierarchyKeypaths {
+      context.logger.info(keypath.fullPath)
+    }
+
+    guard let anyValueProvider = valueProvider(for: keypath) else {
+      return nil
+    }
+
+    // Retrieve the type-erased keyframes from the custom `ValueProvider`
+    let typeErasedKeyframes: [Keyframe<Any>]
+    switch anyValueProvider.typeErasedStorage {
+    case .singleValue(let typeErasedValue):
+      typeErasedKeyframes = [Keyframe(typeErasedValue)]
+
+    case .keyframes(let keyframes, _):
+      typeErasedKeyframes = keyframes
+
+    case .closure:
+      try context.logCompatibilityIssue("""
+        The Core Animation rendering engine doesn't support Value Providers that vend a closure,
+        because that would require calling the closure on the main thread once per frame.
+        """)
+      return nil
+    }
+
+    // Convert the type-erased keyframe values using this `CustomizableProperty`'s conversion closure
+    let typedKeyframes = typeErasedKeyframes.compactMap { typeErasedKeyframe -> Keyframe<Value>? in
+      guard let convertedValue = customizableProperty.conversion(typeErasedKeyframe.value) else {
+        logger.assertionFailure("""
+          Could not convert value of type \(type(of: typeErasedKeyframe.value)) to expected type \(Value.self)
+          """)
+        return nil
+      }
+
+      return typeErasedKeyframe.withValue(convertedValue)
+    }
+
+    // Verify that all of the keyframes were successfully converted to the expected type
+    guard typedKeyframes.count == typeErasedKeyframes.count else {
+      return nil
+    }
+
+    return KeyframeGroup(keyframes: ContiguousArray(typedKeyframes))
+  }
+
+  // MARK: Private
+
+  private let logger: LottieLogger
+
+  private var valueProviders = [(keypath: AnimationKeypath, valueProvider: AnyValueProvider)]()
+
+  /// Retrieves the most-recently-registered Value Provider that matches the given keypat
+  private func valueProvider(for keypath: AnimationKeypath) -> AnyValueProvider? {
+    // Find the last keypath matching the given keypath,
+    // so we return the value provider that was registered most-recently
+    valueProviders.last(where: { registeredKeypath, _ in
+      keypath.matches(registeredKeypath)
+    })?.valueProvider
+  }
+
+}
+
+extension AnyValueProviderStorage {
+  /// Whether or not this type of value provider is supported
+  /// by the new Core Animation rendering engine
+  var isSupportedByCoreAnimationRenderingEngine: Bool {
+    switch self {
+    case .singleValue, .keyframes:
+      return true
+    case .closure:
+      return false
+    }
+  }
+}
+
+extension AnimationKeypath {
+  /// Whether or not this keypath from the animation hierarchy
+  /// matches the given keypath (which may contain wildcards)
+  func matches(_ keypath: AnimationKeypath) -> Bool {
+    var regex = "^" // match the start of the string
+      + keypath.keys.joined(separator: "\\.") // match this keypath, escaping "." characters
+      + "$" // match the end of the string
+
+    // ** wildcards match anything
+    //  - "**.Color" matches both "Layer 1.Color" and "Layer 1.Layer 2.Color"
+    regex = regex.replacingOccurrences(of: "**", with: ".+")
+
+    // * wildcards match any individual path component
+    //  - "*.Color" matches "Layer 1.Color" but not "Layer 1.Layer 2.Color"
+    regex = regex.replacingOccurrences(of: "*", with: "[^.]+")
+
+    return fullPath.range(of: regex, options: .regularExpression) != nil
+  }
+}