Rename ExperimentalAnimationLayer to CoreAnimationLayer (#1555)

Example/iOS/Configuration.swift

@@ -8,7 +8,7 @@ import Lottie
 
 final class Configuration {
 
-  /// Whether or not to use the new, experimental rendering engine
+  /// The rendering engine to use
   static var renderingEngineOption: RenderingEngineOption {
     get {
       RenderingEngineOption(rawValue: UserDefaults.standard.string(forKey: #function) ?? "Automatic") ?? .automatic

Sources/Private/Experimental/ExperimentalAnimationLayer.swift → Sources/Private/CoreAnimation/CoreAnimationLayer.swift

@@ -4,12 +4,10 @@
 import Foundation
 import QuartzCore
 
-// MARK: - ExperimentalAnimationLayer
+// MARK: - CoreAnimationLayer
 
-/// The root `CALayer` of the new rendering engine,
-/// which leverages the Core Animation render server to
-/// animate without executing on the main thread every frame.
-final class ExperimentalAnimationLayer: BaseAnimationLayer {
+/// The root `CALayer` of the Core Animation rendering engine
+final class CoreAnimationLayer: BaseAnimationLayer {
 
   // MARK: Lifecycle
 
@@ -285,7 +283,7 @@ final class ExperimentalAnimationLayer: BaseAnimationLayer {
 
 // MARK: RootAnimationLayer
 
-extension ExperimentalAnimationLayer: RootAnimationLayer {
+extension CoreAnimationLayer: RootAnimationLayer {
 
   var primaryAnimationKey: AnimationKey {
     .specific(#keyPath(animationProgress))
@@ -392,7 +390,7 @@ extension ExperimentalAnimationLayer: RootAnimationLayer {
 
   func getValue(for _: AnimationKeypath, atFrame _: AnimationFrameTime?) -> Any? {
     LottieLogger.shared.assertionFailure("""
-      The new rendering engine doesn't support querying values for individual frames
+      The Core Animation rendering engine doesn't support querying values for individual frames
       """)
     return nil
   }

Sources/Private/Experimental/Layers/AnimationLayer.swift → Sources/Private/CoreAnimation/Layers/AnimationLayer.swift

@@ -21,7 +21,7 @@ struct LayerAnimationContext {
   let animation: Animation
 
   /// The timing configuration that should be applied to `CAAnimation`s
-  let timingConfiguration: ExperimentalAnimationLayer.CAMediaTimingConfiguration
+  let timingConfiguration: CoreAnimationLayer.CAMediaTimingConfiguration
 
   /// The absolute frame number that this animation begins at
   let startFrame: AnimationFrameTime

Sources/Private/Experimental/ValueProviderStore.swift → Sources/Private/CoreAnimation/ValueProviderStore.swift

@@ -23,7 +23,7 @@ final class ValueProviderStore {
     // TODO: Support more value types
     LottieLogger.shared.assert(
       keypath.keys.last == PropertyName.color.rawValue,
-      "The new rendering engine currently only supports customizing color values")
+      "The Core Animation rendering engine currently only supports customizing color values")
 
     valueProviders.append((keypath: keypath, valueProvider: valueProvider))
   }

Sources/Private/LayerContainers/AnimationContainer.swift → Sources/Private/MainThread/LayerContainers/MainThreadAnimationLayer.swift

@@ -1,5 +1,5 @@
 //
-//  AnimationContainer.swift
+//  MainThreadAnimationLayer.swift
 //  lottie-swift
 //
 //  Created by Brandon Withrow on 1/24/19.
@@ -8,13 +8,13 @@
 import Foundation
 import QuartzCore
 
-// MARK: - AnimationContainer
+// MARK: - MainThreadAnimationLayer
 
-/// The base animation container.
+/// The base `CALayer` for the Main Thread rendering engine
 ///
 /// This layer holds a single composition container and allows for animation of
 /// the currentFrame property.
-final class AnimationContainer: CALayer, RootAnimationLayer {
+final class MainThreadAnimationLayer: CALayer, RootAnimationLayer {
 
   // MARK: Lifecycle
 
@@ -84,7 +84,7 @@ final class AnimationContainer: CALayer, RootAnimationLayer {
     layerFontProvider = LayerFontProvider(fontProvider: DefaultFontProvider())
     super.init(layer: layer)
 
-    guard let animationLayer = layer as? AnimationContainer else { return }
+    guard let animationLayer = layer as? MainThreadAnimationLayer else { return }
 
     currentFrame = animationLayer.currentFrame
 

Sources/Private/Utility/Debugging/LayerDebugging.swift

@@ -117,9 +117,9 @@ extension CALayer {
   }
 }
 
-// MARK: - AnimationContainer + LayerDebugging
+// MARK: - MainThreadAnimationLayer + LayerDebugging
 
-extension AnimationContainer: LayerDebugging {
+extension MainThreadAnimationLayer: LayerDebugging {
   var debugStyle: LayerDebugStyle {
     LayerDebugStyle.topLayerStyle()
   }

Sources/Public/Animation/AnimationView.swift

@@ -907,7 +907,7 @@ final public class AnimationView: AnimationViewBase {
     switch renderingEngine {
     case .coreAnimation:
       // TODO: Support `RenderingEngineOption.automatic`, using `CompatibilityTracker.Mode.abort`
-      animationLayer = ExperimentalAnimationLayer(
+      animationLayer = CoreAnimationLayer(
         animation: animation,
         imageProvider: imageProvider,
         fontProvider: fontProvider,
@@ -922,7 +922,7 @@ final public class AnimationView: AnimationViewBase {
         })
 
     case .mainThread:
-      animationLayer = AnimationContainer(
+      animationLayer = MainThreadAnimationLayer(
         animation: animation,
         imageProvider: imageProvider,
         textProvider: textProvider,
@@ -1048,9 +1048,9 @@ final public class AnimationView: AnimationViewBase {
     animationID = animationID + 1
     _activeAnimationName = AnimationView.animationName + String(animationID)
 
-    if let experimentalAnimationLayer = animationlayer as? ExperimentalAnimationLayer {
+    if let coreAnimationLayer = animationlayer as? CoreAnimationLayer {
       var animationContext = animationContext
-      var timingConfiguration = ExperimentalAnimationLayer.CAMediaTimingConfiguration(
+      var timingConfiguration = CoreAnimationLayer.CAMediaTimingConfiguration(
         autoreverses: loopMode.caAnimationConfiguration.autoreverses,
         repeatCount: loopMode.caAnimationConfiguration.repeatCount,
         speed: Float(animationSpeed))
@@ -1078,7 +1078,7 @@ final public class AnimationView: AnimationViewBase {
         }
       }
 
-      experimentalAnimationLayer.playAnimation(
+      coreAnimationLayer.playAnimation(
         context: animationContext,
         timingConfiguration: timingConfiguration)
 

Sources/Public/LottieConfiguration.swift

@@ -30,24 +30,28 @@ public enum RenderingEngineOption: Hashable {
   /// Uses the specified rendering engine
   case specific(RenderingEngine)
 
-  /// The original / default rendering engine, which supports all Lottie features
-  /// but runs on the main thread, which comes with some CPU overhead.
+  /// The Main Thread rendering engine, which supports all Lottie features
+  /// but runs on the main thread, which comes with some CPU overhead and
+  /// can cause the animation to play at a low framerate when the CPU is busy.
   public static var mainThread: RenderingEngineOption { .specific(.mainThread) }
 
-  /// The new rendering engine, that animates using Core Animation
-  /// and has no CPU overhead but doesn't support all Lottie features.
+  /// The Core Animation rendering engine, that animates using Core Animation
+  /// and has better performance characteristics than the Main Thread engine,
+  /// but doesn't support all Lottie features.
   public static var coreAnimation: RenderingEngineOption { .specific(.coreAnimation) }
 }
 
 // MARK: - RenderingEngine
 
 /// The rendering engine implementation to use when displaying an animation
 public enum RenderingEngine: Hashable {
-  /// The original / default rendering engine, which supports all Lottie features
-  /// but runs on the main thread, which comes with some CPU overhead.
+  /// The Main Thread rendering engine, which supports all Lottie features
+  /// but runs on the main thread, which comes with some CPU overhead and
+  /// can cause the animation to play at a low framerate when the CPU is busy.
   case mainThread
 
-  /// The new rendering engine, that animates using Core Animation
-  /// and has no CPU overhead but doesn't support all Lottie features.
+  /// The Core Animation rendering engine, that animates using Core Animation
+  /// and has better performance characteristics than the Main Thread engine,
+  /// but doesn't support all Lottie features.
   case coreAnimation
 }

Sources/Public/iOS/AnimatedSwitch.swift

@@ -168,9 +168,9 @@ open class AnimatedSwitch: AnimatedControl {
       completion: { [weak self] finished in
         guard let self = self else { return }
 
-        // For the legacy rendering engine, we freeze the animation at the expected final progress
-        // once the animation is complete. This isn't necessary on the new / experimental engine.
-        if finished, !(self.animationView.animationLayer is ExperimentalAnimationLayer) {
+        // For the Main Thread rendering engine, we freeze the animation at the expected final progress
+        // once the animation is complete. This isn't necessary on the Core Animation engine.
+        if finished, !(self.animationView.animationLayer is CoreAnimationLayer) {
           self.animationView.currentProgress = finalProgress
         }
       })

Tests/AutomaticEngineTests.swift

@@ -16,7 +16,7 @@ final class AutomaticEngineTests: XCTestCase {
 
       var compatibilityIssues = [CompatibilityIssue]()
 
-      let animationLayer = ExperimentalAnimationLayer(
+      let animationLayer = CoreAnimationLayer(
         animation: animation,
         imageProvider: BundleImageProvider(bundle: Bundle.main, searchPath: nil),
         fontProvider: DefaultFontProvider(),

Tests/SnapshotTests.swift

@@ -21,7 +21,7 @@ class SnapshotTests: XCTestCase {
     try compareSampleSnapshots(configuration: LottieConfiguration(renderingEngine: .mainThread))
   }
 
-  /// Snapshots sample animation files using the experimental rendering engine
+  /// Snapshots sample animation files using the Core Animation rendering engine
   func testCoreAnimationRenderingEngine() throws {
     try compareSampleSnapshots(configuration: LottieConfiguration(renderingEngine: .coreAnimation))
   }