comments and documents

Author: Chris Yang

shell/platform/darwin/ios/framework/Source/FlutterPlatformViews_Internal.h

@@ -66,7 +66,7 @@
 // Reuse a maskView from the pool, or allocate a new one.
 - (FlutterClippingMaskView*)getMaskViewWithFrame:(CGRect)frame;
 
-// Mark all the maskViews available.
+// Insert the `maskView` into the pool.
 - (void)insertViewToPool:(FlutterClippingMaskView*)maskView;
 
 @end
@@ -291,27 +291,30 @@ class FlutterPlatformViewsController {
   int CountClips(const MutatorsStack& mutators_stack);
 
   void ClipViewSetMaskView(UIView* clipView);
+
   // Applies the mutators in the mutators_stack to the UIView chain that was constructed by
   // `ReconstructClipViewsChain`
   //
-  // Clips are applied to the super view with a CALayer mask. Transforms are applied to the
-  // current view that's at the head of the chain. For example the following mutators stack [T_1,
-  // C_2, T_3, T_4, C_5, T_6] where T denotes a transform and C denotes a clip, will result in the
-  // following UIView tree:
-  //
-  // C_2 -> C_5 -> PLATFORM_VIEW
-  // (PLATFORM_VIEW is a subview of C_5 which is a subview of C_2)
-  //
-  // T_1 is applied to C_2, T_3 and T_4 are applied to C_5, and T_6 is applied to PLATFORM_VIEW.
-  //
-  // After each clip operation, we update the head to the super view of the current head.
+  // Clips are applied to the `embedded_view`'s super view(|ChildClippingView|) using a
+  // |FlutterClippingMaskView|. Transforms are applied to `embedded_view`
   //
   // The `bounding_rect` is the final bounding rect of the PlatformView
   // (EmbeddedViewParams::finalBoundingRect). If a clip mutator's rect contains the final bounding
   // rect of the PlatformView, the clip mutator is not applied for performance optimization.
+  //
+  // This method is only called when thew `embedded_view` needs to be re-composited at the current
+  // frame. See: `CompositeWithParams` for details.
   void ApplyMutators(const MutatorsStack& mutators_stack,
                      UIView* embedded_view,
                      const SkRect& bounding_rect);
+
+  // Composite the PlatformView with `view_id`.
+  // Every frame, during the paint traversal of the layer tree, this method is called for all
+  // the PlatformViews in `views_to_recomposite_`.
+  //
+  // Note that `views_to_recomposite_` does not represent all the views in the view hierarchy,
+  // if a PlatformView does not change its composition parameter from last frame, it is not
+  // included in the `views_to_recomposite_`.
   void CompositeWithParams(int64_t view_id, const EmbeddedViewParams& params);
 
   // Allocates a new FlutterPlatformViewLayer if needed, draws the pixels within the rect from

shell/platform/darwin/ios/framework/Source/FlutterPlatformViews_Internal.mm

@@ -463,6 +463,8 @@ @interface FlutterClippingMaskViewPool ()
 // This prevents the pool to grow infinately and limits the maximum memory a pool can use.
 @property(assign, nonatomic) NSUInteger capacity;
 
+// The pool contains the views that are available to use.
+// The number of items in the pool must not excceds `capacity`.
 @property(retain, nonatomic) NSMutableSet<FlutterClippingMaskView*>* pool;
 
 @end
@@ -496,6 +498,10 @@ - (FlutterClippingMaskView*)getMaskViewWithFrame:(CGRect)frame {
 
 - (void)insertViewToPool:(FlutterClippingMaskView*)maskView {
   FML_DCHECK(![self.pool containsObject:maskView]);
+  FML_DCHECK([self.pool.count <= self.capacity]);
+  if (self.pool.count == self.capacity) {
+    return;
+  }
   [self.pool addObject:maskView];
 }