lottie-ios 4.1.2 → 4.2.0

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

@@ -60,8 +60,12 @@ struct CustomizableProperty<ValueRepresentation> {
 /// The name of a customizable property that can be used in an `AnimationKeypath`
 ///  - These values should be shared between the two rendering engines,
 ///    since they form the public API of the `AnimationKeypath` system.
-enum PropertyName: String {
+enum PropertyName: String, CaseIterable {
   case color = "Color"
+  case opacity = "Opacity"
+  case scale = "Scale"
+  case position = "Position"
+  case rotation = "Rotation"
 }
 
 // MARK: CALayer properties
@@ -71,7 +75,7 @@ extension LayerProperty {
     .init(
       caLayerKeypath: "transform.translation",
       defaultValue: CGPoint(x: 0, y: 0),
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .position)
   }
 
   static var positionX: LayerProperty<CGFloat> {
@@ -99,19 +103,19 @@ extension LayerProperty {
     .init(
       caLayerKeypath: "transform.scale.x",
       defaultValue: 1,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .scaleX)
   }
 
   static var scaleY: LayerProperty<CGFloat> {
     .init(
       caLayerKeypath: "transform.scale.y",
       defaultValue: 1,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .scaleY)
   }
 
-  static var rotation: LayerProperty<CGFloat> {
+  static var rotationX: LayerProperty<CGFloat> {
     .init(
-      caLayerKeypath: "transform.rotation",
+      caLayerKeypath: "transform.rotation.x",
       defaultValue: 0,
       customizableProperty: nil /* currently unsupported */ )
   }
@@ -123,6 +127,13 @@ extension LayerProperty {
       customizableProperty: nil /* currently unsupported */ )
   }
 
+  static var rotationZ: LayerProperty<CGFloat> {
+    .init(
+      caLayerKeypath: "transform.rotation.z",
+      defaultValue: 0,
+      customizableProperty: .rotation)
+  }
+
   static var anchorPoint: LayerProperty<CGPoint> {
     .init(
       caLayerKeypath: #keyPath(CALayer.anchorPoint),
@@ -136,7 +147,7 @@ extension LayerProperty {
     .init(
       caLayerKeypath: #keyPath(CALayer.opacity),
       defaultValue: 1,
-      customizableProperty: nil /* currently unsupported */ )
+      customizableProperty: .opacity)
   }
 
   static var transform: LayerProperty<CATransform3D> {
@@ -249,4 +260,62 @@ extension CustomizableProperty {
         return .rgba(CGFloat(color.r), CGFloat(color.g), CGFloat(color.b), CGFloat(color.a))
       })
   }
+
+  static var opacity: CustomizableProperty<CGFloat> {
+    .init(
+      name: [.opacity],
+      conversion: { typeErasedValue in
+        guard let vector = typeErasedValue as? LottieVector1D else { return nil }
+
+        // Lottie animation files express opacity 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).
+        return vector.cgFloatValue / 100
+      })
+  }
+
+  static var scaleX: CustomizableProperty<CGFloat> {
+    .init(
+      name: [.scale],
+      conversion: { typeErasedValue in
+        guard let vector = typeErasedValue as? LottieVector3D else { return nil }
+
+        // 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).
+        return vector.pointValue.x / 100
+      })
+  }
+
+  static var scaleY: CustomizableProperty<CGFloat> {
+    .init(
+      name: [.scale],
+      conversion: { typeErasedValue in
+        guard let vector = typeErasedValue as? LottieVector3D else { return nil }
+
+        // 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).
+        return vector.pointValue.y / 100
+      })
+  }
+
+  static var rotation: CustomizableProperty<CGFloat> {
+    .init(
+      name: [.rotation],
+      conversion: { typeErasedValue in
+        guard let vector = typeErasedValue as? LottieVector1D else { return nil }
+
+        // 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π)
+        return vector.cgFloatValue * .pi / 180
+      })
+  }
+
+  static var position: CustomizableProperty<CGPoint> {
+    .init(
+      name: [.position],
+      conversion: { ($0 as? LottieVector3D)?.pointValue })
+  }
 }

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

@@ -40,7 +40,7 @@ extension CALayer {
   func addOpacityAnimation(for opacity: OpacityAnimationModel, context: LayerAnimationContext) throws {
     try addAnimation(
       for: .opacity,
-      keyframes: opacity.opacity.keyframes,
+      keyframes: opacity.opacity,
       value: {
         // Lottie animation files express opacity as a numerical percentage value
         // (e.g. 0%, 50%, 100%) so we divide by 100 to get the decimal values

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

@@ -15,7 +15,7 @@ extension CAShapeLayer {
   {
     try addAnimation(
       for: .path,
-      keyframes: try rectangle.combinedKeyframes(roundedCorners: roundedCorners).keyframes,
+      keyframes: try rectangle.combinedKeyframes(roundedCorners: roundedCorners),
       value: { keyframe in
         BezierPath.rectangle(
           position: keyframe.position.pointValue,

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

@@ -57,7 +57,7 @@ extension CAShapeLayer {
 
     try addAnimation(
       for: .fillColor,
-      keyframes: fill.color.keyframes,
+      keyframes: fill.color,
       value: \.cgColorValue,
       context: context)
 
@@ -71,7 +71,7 @@ extension CAShapeLayer {
 
     try addAnimation(
       for: .strokeStart,
-      keyframes: strokeStartKeyframes.keyframes,
+      keyframes: strokeStartKeyframes,
       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
@@ -81,7 +81,7 @@ extension CAShapeLayer {
 
     try addAnimation(
       for: .strokeEnd,
-      keyframes: strokeEndKeyframes.keyframes,
+      keyframes: strokeEndKeyframes,
       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
@@ -112,14 +112,24 @@ extension Trim {
 
     // 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 and strokeEnd flipped.
+    if startValueIsAlwaysLessOrEqualToThanEndValue() {
+      // If the start value is always _less than_ or equal to the end value
+      // then we can use the given values without any modifications
+      strokeStart = start
+      strokeEnd = end
+    } else if startValueIsAlwaysGreaterThanOrEqualToEndValue() {
+      // If the start value is always _greater than_ or equal to the end value,
+      // then we can just swap the start / end keyframes. This lets us avoid
+      // manually interpolating the keyframes values at each frame, which
+      // would be more expensive.
       strokeStart = end
       strokeEnd = start
     } else {
-      strokeStart = start
-      strokeEnd = end
+      // Otherwise if the start / end values ever swap places we have to
+      // fix the order on a per-keyframe basis, which may require manually
+      // interpolating the keyframe values at each frame.
+      (strokeStart, strokeEnd) = interpolatedAtEachFrame()
     }
 
     // If there are no offsets, then the stroke values can be used as-is
@@ -130,22 +140,20 @@ extension Trim {
       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()
-
-    var adjustedStrokeStart = KeyframeGroup(
-      keyframes: try adjustKeyframesForTrimOffsets(
-        strokeKeyframes: interpolatedStrokeStart,
-        offsetKeyframes: interpolatedStrokeOffset))
-
-    var adjustedStrokeEnd = KeyframeGroup(
-      keyframes: try adjustKeyframesForTrimOffsets(
-        strokeKeyframes: interpolatedStrokeEnd,
-        offsetKeyframes: interpolatedStrokeOffset))
+    // Apply the offset to the start / end values at each frame
+    let offsetStrokeKeyframes = Keyframes.combined(
+      strokeStart,
+      strokeEnd,
+      offset,
+      makeCombinedResult: { start, end, offset -> (start: LottieVector1D, end: LottieVector1D) in
+        // Compute the adjusted value by converting the offset value to a stroke value
+        let offsetStart = start.cgFloatValue + (offset.cgFloatValue / 360 * 100)
+        let offsetEnd = end.cgFloatValue + (offset.cgFloatValue / 360 * 100)
+        return (start: LottieVector1D(offsetStart), end: LottieVector1D(offsetEnd))
+      })
+
+    var adjustedStrokeStart = offsetStrokeKeyframes.map { $0.start }
+    var adjustedStrokeEnd = offsetStrokeKeyframes.map { $0.end }
 
     // 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
@@ -169,9 +177,23 @@ extension Trim {
 
   // 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 {
+  /// Checks whether or not the value for `trim.start` is less than
+  /// or equal to the value for every `trim.end` at every frame.
+  private func startValueIsAlwaysLessOrEqualToThanEndValue() -> Bool {
+    startAndEndValuesAllSatisfy { startValue, endValue in
+      startValue <= endValue
+    }
+  }
+
+  /// Checks whether or not the value for `trim.start` is greater than
+  /// or equal to the value for every `trim.end` at every frame.
+  private func startValueIsAlwaysGreaterThanOrEqualToEndValue() -> Bool {
+    startAndEndValuesAllSatisfy { startValue, endValue in
+      startValue >= endValue
+    }
+  }
+
+  private func startAndEndValuesAllSatisfy(_ condition: (_ start: CGFloat, _ end: CGFloat) -> Bool) -> Bool {
     let keyframeTimes = Set(start.keyframes.map { $0.time } + end.keyframes.map { $0.time })
 
     let startInterpolator = KeyframeInterpolator(keyframes: start.keyframes)
@@ -183,7 +205,7 @@ extension Trim {
         let endAtTime = endInterpolator.value(frame: keyframeTime) as? LottieVector1D
       else { continue }
 
-      if startAtTime.cgFloatValue < endAtTime.cgFloatValue {
+      if !condition(startAtTime.cgFloatValue, endAtTime.cgFloatValue) {
         return false
       }
     }
@@ -191,82 +213,24 @@ extension Trim {
     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<LottieVector1D>>,
-    offsetKeyframes: ContiguousArray<Keyframe<LottieVector1D>>)
-    throws -> ContiguousArray<Keyframe<LottieVector1D>>
+  /// Interpolates the start and end keyframes, at each frame if necessary,
+  /// so that the value of `strokeStart` is always less than `strokeEnd`.
+  private func interpolatedAtEachFrame()
+    -> (strokeStart: KeyframeGroup<LottieVector1D>, strokeEnd: KeyframeGroup<LottieVector1D>)
   {
-    guard
-      !strokeKeyframes.isEmpty,
-      !offsetKeyframes.isEmpty
-    else {
-      return strokeKeyframes
-    }
-
-    // Map each time to its corresponding stroke/offset keyframe
-    var timeMap = [AnimationFrameTime: [Keyframe<LottieVector1D>?]]()
-    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<LottieVector1D>>()
-    var lastKeyframe: Keyframe<LottieVector1D>?
-    var lastOffset: Keyframe<LottieVector1D>?
-
-    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)
+    let combinedKeyframes = Keyframes.combined(
+      start,
+      end,
+      makeCombinedResult: { startValue, endValue -> (start: LottieVector1D, end: LottieVector1D) in
+        if startValue.cgFloatValue < endValue.cgFloatValue {
+          return (start: startValue, end: endValue)
+        } else {
+          return (start: endValue, end: startValue)
         }
-        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<LottieVector1D>(
-        value: LottieVector1D(adjustedValue),
-        time: time,
-        isHold: currentKeyframe.isHold,
-        inTangent: nil,
-        outTangent: nil,
-        spatialInTangent: nil,
-        spatialOutTangent: nil)
-
-      output.append(adjustedKeyframe)
-    }
-
-    return output
+    return (
+      strokeStart: combinedKeyframes.map { $0.start },
+      strokeEnd: combinedKeyframes.map { $0.end })
   }
 }

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

@@ -36,7 +36,7 @@ extension CAShapeLayer {
   {
     try addAnimation(
       for: .path,
-      keyframes: try star.combinedKeyframes().keyframes,
+      keyframes: try star.combinedKeyframes(),
       value: { keyframe in
         BezierPath.star(
           position: keyframe.position.pointValue,
@@ -62,7 +62,7 @@ extension CAShapeLayer {
   {
     try addAnimation(
       for: .path,
-      keyframes: try star.combinedKeyframes().keyframes,
+      keyframes: try star.combinedKeyframes(),
       value: { keyframe in
         BezierPath.polygon(
           position: keyframe.position.pointValue,

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

@@ -54,14 +54,14 @@ extension CAShapeLayer {
     if let strokeColor = stroke.strokeColor {
       try addAnimation(
         for: .strokeColor,
-        keyframes: strokeColor.keyframes,
+        keyframes: strokeColor,
         value: \.cgColorValue,
         context: context)
     }
 
     try addAnimation(
       for: .lineWidth,
-      keyframes: stroke.width.keyframes,
+      keyframes: stroke.width,
       value: \.cgFloatValue,
       context: context)
 
@@ -79,7 +79,7 @@ extension CAShapeLayer {
 
       try addAnimation(
         for: .lineDashPhase,
-        keyframes: dashPhase,
+        keyframes: KeyframeGroup(keyframes: dashPhase),
         value: \.cgFloatValue,
         context: context)
     }

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

@@ -24,8 +24,14 @@ protocol TransformModel {
   /// The scale of the transform
   var scale: KeyframeGroup<LottieVector3D> { get }
 
-  /// The rotation of the transform. Note: This is single dimensional rotation.
-  var rotation: KeyframeGroup<LottieVector1D> { get }
+  /// The rotation of the transform on X axis.
+  var rotationX: KeyframeGroup<LottieVector1D> { get }
+
+  /// The rotation of the transform on Y axis.
+  var rotationY: KeyframeGroup<LottieVector1D> { get }
+
+  /// The rotation of the transform on Z axis.
+  var rotationZ: KeyframeGroup<LottieVector1D> { get }
 }
 
 // MARK: - Transform + TransformModel
@@ -75,7 +81,7 @@ extension CALayer {
       try addPositionAnimations(from: transformModel, context: context)
       try addAnchorPointAnimation(from: transformModel, context: context)
       try addScaleAnimations(from: transformModel, context: context)
-      try addRotationAnimation(from: transformModel, context: context)
+      try addRotationAnimations(from: transformModel, context: context)
     }
   }
 
@@ -87,15 +93,15 @@ extension CALayer {
     context: LayerAnimationContext)
     throws
   {
-    if let positionKeyframes = transformModel._position?.keyframes {
+    if let positionKeyframes = transformModel._position {
       try addAnimation(
         for: .position,
         keyframes: positionKeyframes,
         value: \.pointValue,
         context: context)
     } else if
-      let xKeyframes = transformModel._positionX?.keyframes,
-      let yKeyframes = transformModel._positionY?.keyframes
+      let xKeyframes = transformModel._positionX,
+      let yKeyframes = transformModel._positionY
     {
       try addAnimation(
         for: .positionX,
@@ -123,7 +129,7 @@ extension CALayer {
   {
     try addAnimation(
       for: .anchorPoint,
-      keyframes: transformModel.anchorPoint.keyframes,
+      keyframes: transformModel.anchorPoint,
       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")
@@ -148,7 +154,7 @@ extension CALayer {
   {
     try addAnimation(
       for: .scaleX,
-      keyframes: transformModel.scale.keyframes,
+      keyframes: transformModel.scale,
       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
@@ -201,7 +207,7 @@ extension CALayer {
 
       try addAnimation(
         for: .rotationY,
-        keyframes: transformModel.scale.keyframes,
+        keyframes: transformModel.scale,
         value: { scale in
           if scale.x < 0 {
             return .pi
@@ -214,7 +220,7 @@ extension CALayer {
 
     try addAnimation(
       for: .scaleY,
-      keyframes: transformModel.scale.keyframes,
+      keyframes: transformModel.scale,
       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
@@ -227,14 +233,53 @@ extension CALayer {
       context: context)
   }
 
-  private func addRotationAnimation(
+  private func addRotationAnimations(
     from transformModel: TransformModel,
     context: LayerAnimationContext)
     throws
   {
+    let containsXRotationValues = transformModel.rotationX.keyframes.contains(where: { $0.value.cgFloatValue != 0 })
+    let containsYRotationValues = transformModel.rotationY.keyframes.contains(where: { $0.value.cgFloatValue != 0 })
+
+    // When `rotation.x` or `rotation.y` is used, it doesn't render property in test snapshots
+    // but do renders correctly on the simulator / device
+    if TestHelpers.snapshotTestsAreRunning {
+      if containsXRotationValues {
+        context.logger.warn("""
+          `rotation.x` values are not displayed correctly in snapshot tests
+          """)
+      }
+
+      if containsYRotationValues {
+        context.logger.warn("""
+          `rotation.y` values are not displayed correctly in snapshot tests
+          """)
+      }
+    }
+
+    // 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π)
+
+    try addAnimation(
+      for: .rotationX,
+      keyframes: transformModel.rotationX,
+      value: { rotationDegrees in
+        rotationDegrees.cgFloatValue * .pi / 180
+      },
+      context: context)
+
+    try addAnimation(
+      for: .rotationY,
+      keyframes: transformModel.rotationY,
+      value: { rotationDegrees in
+        rotationDegrees.cgFloatValue * .pi / 180
+      },
+      context: context)
+
     try addAnimation(
-      for: .rotation,
-      keyframes: transformModel.rotation.keyframes,
+      for: .rotationZ,
+      keyframes: transformModel.rotationZ,
       value: { rotationDegrees in
         // Lottie animation files express rotation in degrees
         // (e.g. 90º, 180º, 360º) so we covert to radians to get the
@@ -257,22 +302,26 @@ extension CALayer {
       transformModel.anchor,
       transformModel.position,
       transformModel.scale,
-      transformModel.rotation,
+      transformModel.rotationX,
+      transformModel.rotationY,
+      transformModel.rotationZ,
       transformModel.skew,
       transformModel.skewAxis,
-      makeCombinedResult: { anchor, position, scale, rotation, skew, skewAxis in
+      makeCombinedResult: { anchor, position, scale, rotationX, rotationY, rotationZ, skew, skewAxis in
         CATransform3D.makeTransform(
           anchor: anchor.pointValue,
           position: position.pointValue,
           scale: scale.sizeValue,
-          rotation: rotation.cgFloatValue,
+          rotationX: rotationX.cgFloatValue,
+          rotationY: rotationY.cgFloatValue,
+          rotationZ: rotationZ.cgFloatValue,
           skew: skew.cgFloatValue,
           skewAxis: skewAxis.cgFloatValue)
       })
 
     try addAnimation(
       for: .transform,
-      keyframes: combinedTransformKeyframes.keyframes,
+      keyframes: combinedTransformKeyframes,
       value: { $0 },
       context: context)
   }