document

Author: knopp

shell/platform/darwin/macos/framework/Source/FlutterCompositor.mm

@@ -51,7 +51,7 @@
     FlutterLayer* layer = (FlutterLayer*)layers[i];
     if (layer->type == kFlutterLayerContentTypeBackingStore) {
       FlutterSurface* surface =
-          [view.surfaceManager backBufferForMetalTexture:&layer->backing_store->metal.texture];
+          [view.surfaceManager lookupSurface:&layer->backing_store->metal.texture];
       if (surface) {
         FlutterSurfacePresentInfo* info = [[FlutterSurfacePresentInfo alloc] init];
         info.surface = surface;

shell/platform/darwin/macos/framework/Source/FlutterRenderer.mm

@@ -111,17 +111,15 @@ - (FlutterMetalTexture)createTextureForView:(uint64_t)viewId size:(CGSize)size {
 - (BOOL)present:(uint64_t)viewId texture:(const FlutterMetalTexture*)texture {
   FlutterView* view = [_viewProvider getView:viewId];
   if (view != nil) {
-    FlutterSurface* surface = [view.surfaceManager backBufferForMetalTexture:texture];
+    FlutterSurface* surface = [view.surfaceManager lookupSurface:texture];
     if (surface == nil) {
       return NO;
     }
     FlutterSurfacePresentInfo* info = [[FlutterSurfacePresentInfo alloc] init];
     info.offset = CGPointMake(0, 0);
     info.zIndex = 0;
     info.surface = surface;
-    [view.surfaceManager present:@[ info ]
-                          notify:^{
-                          }];
+    [view.surfaceManager present:@[ info ] notify:nil];
   }
   return YES;
 }

shell/platform/darwin/macos/framework/Source/FlutterSurfaceManager.h

@@ -14,6 +14,9 @@
 
 @end
 
+/**
+ * Surface with additional properties needed for presenting.
+ */
 @interface FlutterSurfacePresentInfo : NSObject
 
 @property(readwrite, strong, nonatomic, nonnull) FlutterSurface* surface;
@@ -22,40 +25,48 @@
 
 @end
 
+/**
+ * Owned by `FlutterView`.
+ * Responsible for providing surfaces for Flutter to render into and
+ * as well as subsequent presentation of these surfaces.
+ * The Presentation of surfaces includes management of core animation sublayers.
+ */
 @interface FlutterSurfaceManager : NSObject
 
 /**
  * Initializes and returns a surface manager that renders to a child layer (referred to as the
- * content layer) of the containing layer and applies the transform to the contents of the content
- * layer.
+ * content layer) of the containing layer.
  */
 - (nullable instancetype)initWithDevice:(nonnull id<MTLDevice>)device
                            commandQueue:(nonnull id<MTLCommandQueue>)commandQueue
                                   layer:(nonnull CALayer*)containingLayer
                      threadSynchronizer:(nonnull FlutterThreadSynchronizer*)synchronizer;
 
 /**
- * Looks up surface for given metal texture. Can be called for surfaces obtained
- * through backBufferForSize: until `present` is called.
+ * Returns back buffer surface for given size that Flutter can render content to.
+ * Will return cached surface  if one is available, or create new one otherwise.
+ *
+ * Must be called on raster thread.
  */
-- (nullable FlutterSurface*)backBufferForMetalTexture:(nonnull const FlutterMetalTexture*)texture;
+- (nonnull FlutterSurface*)backBufferForSize:(CGSize)size;
 
 /**
- * Returns back buffer surface for given size.
- *
- * Must be called on raster threads.
+ * Looks up surface for given metal texture. Can only be called for surfaces
+ * obtained through `backBufferForSize:` until `present:` is called.
  */
-- (nonnull FlutterSurface*)backBufferForSize:(CGSize)size;
+- (nullable FlutterSurface*)lookupSurface:(nonnull const FlutterMetalTexture*)texture;
 
 /**
- * Sets the provided surfaces as contents of views containing layer sublayers.
+ * Sets the provided surfaces as contents of FlutterView. Will create, update and
+ * remove sublayers as needed.
  *
  * Must be called on raster thread. This will schedule a commit on platform
  * thread and block raster thread until the commit is done.
  * `notify` block will be invoked on platform thread and can be used to perform
- * additional work after commit is done. It will be called in same CATransaction.
+ * additional work after commit is done, such as mutating platform views.
+ * It is guaranteed be called in same CATransaction.
  */
 - (void)present:(nonnull NSArray<FlutterSurfacePresentInfo*>*)surfaces
-         notify:(nonnull dispatch_block_t)notify;
+         notify:(nullable dispatch_block_t)notify;
 
 @end

shell/platform/darwin/macos/framework/Source/FlutterSurfaceManager.mm

@@ -100,9 +100,19 @@ @interface FlutterSurfaceManager () {
   CALayer* _containingLayer;
   FlutterThreadSynchronizer* _synchronizer;
 
+  // Available (cached) back buffer surfaces. These will be removed during
+  // present and replaced by current frong surfaces.
   NSMutableArray<FlutterSurface*>* _backBufferSurfaces;
+
+  // Surfaces that currently obtained through backBufferForSize waiting to be
+  // presented. This is used to keep the surface alive because the non compositor
+  // codepath doesn't properly retain the surface.
   NSMutableArray<FlutterSurface*>* _borrowedSurfaces;
+
+  // Surfaces currently used to back visible layers.
   NSMutableArray<FlutterSurface*>* _frontSurfaces;
+
+  // Currently visible layers.
   NSMutableArray<CALayer*>* _layers;
 }
 @end
@@ -127,7 +137,7 @@ - (instancetype)initWithDevice:(id<MTLDevice>)device
   return self;
 }
 
-- (FlutterSurface*)backBufferForMetalTexture:(nonnull const FlutterMetalTexture*)texture {
+- (FlutterSurface*)lookupSurface:(nonnull const FlutterMetalTexture*)texture {
   for (FlutterSurface* surface in _borrowedSurfaces) {
     if (surface.textureId == texture->texture_id) {
       return surface;
@@ -153,28 +163,34 @@ - (FlutterSurface*)backBufferForSize:(CGSize)size {
 }
 
 - (void)commit:(NSArray<FlutterSurfacePresentInfo*>*)surfaces {
+  assert([NSThread isMainThread]);
+
   [_borrowedSurfaces removeAllObjects];
 
-  // release all unused back buffer surfaces
+  // Release all unused back buffer surfaces and replace them with front surfaces.
   [_backBufferSurfaces removeAllObjects];
   [_backBufferSurfaces addObjectsFromArray:_frontSurfaces];
 
+  // Front surfaces will be replaced by currently presented surfaces.
   [_frontSurfaces removeAllObjects];
   for (FlutterSurfacePresentInfo* info in surfaces) {
     [_frontSurfaces addObject:info.surface];
   }
 
+  // Remove excess layers.
   while (_layers.count > _frontSurfaces.count) {
     [_layers.lastObject removeFromSuperlayer];
     [_layers removeLastObject];
   }
 
+  // Add missing layers.
   while (_layers.count < _frontSurfaces.count) {
     CALayer* layer = [CALayer layer];
     [_containingLayer addSublayer:layer];
     [_layers addObject:layer];
   }
 
+  // Update contents of surface.
   for (size_t i = 0; i < surfaces.count; ++i) {
     FlutterSurfacePresentInfo* info = surfaces[i];
     CALayer* layer = _layers[i];
@@ -190,15 +206,19 @@ - (void)present:(NSArray<FlutterSurfacePresentInfo*>*)surfaces notify:(dispatch_
   [commandBuffer commit];
   [commandBuffer waitUntilScheduled];
 
+  // Get the actual dimensions of the frame (relevant for resize synchronizer).
   CGSize size = CGSizeZero;
   for (FlutterSurfacePresentInfo* info in surfaces) {
     size = CGSizeMake(std::max(size.width, info.offset.x + info.surface.size.width),
                       std::max(size.height, info.offset.y + info.surface.size.height));
   }
+
   [_synchronizer performCommit:size
                         notify:^{
                           [self commit:surfaces];
-                          notify();
+                          if (notify != nil) {
+                            notify();
+                          }
                         }];
 }
 

shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.h

@@ -1,7 +1,7 @@
 #import <Cocoa/Cocoa.h>
 
 /**
- * Takes care of synchronizing raster and platform thread.
+ * Takes care of synchronization between raster and platform thread.
  */
 @interface FlutterThreadSynchronizer : NSObject
 
@@ -14,8 +14,11 @@
 /**
  * Called from raster thread. Schedules the given block on platform thread
  * and blocks until it is performed.
- * If platform thread is blocked in beginResize for given size (or size is empty),
+ *
+ * If platform thread is blocked in `beginResize:` for given size (or size is empty),
  * unblocks platform thread.
+ *
+ * The notify block is guaranteed to be called within a core animation transaction.
  */
 - (void)performCommit:(CGSize)size notify:(nonnull dispatch_block_t)notify;
 

shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.mm

@@ -38,8 +38,6 @@ void Wait() {
  private:
   std::condition_variable cv_;
   std::mutex mutex_;
-
-  // True if this event is in the signaled state.
   bool signaled_ = false;
 };
 }  // namespace

shell/platform/darwin/macos/framework/Source/FlutterView.h

@@ -48,6 +48,10 @@ constexpr uint64_t kFlutterDefaultViewId = 0;
 - (nullable instancetype)initWithCoder:(nonnull NSCoder*)coder NS_UNAVAILABLE;
 - (nonnull instancetype)init NS_UNAVAILABLE;
 
+/**
+ * Returns SurfaceManager for this view. SurfaceManager is responsible for
+ * providing and presenting render surfaces.
+ */
 - (nonnull FlutterSurfaceManager*)surfaceManager;
 
 /**