FlutterMetalLayer Class Reference

#include <FlutterMetalLayer.h>

Inheritance diagram for FlutterMetalLayer:

Instance Methods
(nullable id< CAMetalDrawable >)	- nextDrawable
(instancetype)	- init [implementation]
(void)	- dealloc [implementation]
(void)	- setMaxRefreshRate:forceMax: [implementation]
(void)	- onDisplayLink: [implementation]
(BOOL)	- isKindOfClass: [implementation]
(void)	- setDrawableSize: [implementation]
(void)	- didEnterBackground: [implementation]
(IOSurface *)	- createIOSurface [implementation]
(FlutterTexture *)	- nextTexture [implementation]
(FlutterTexture *)	- tryNextTexture [implementation]
(void)	- presentOnMainThread: [implementation]
(void)	- presentTexture: [implementation]
(void)	- returnTexture: [implementation]

Class Methods
(BOOL)	+ enabled

Protected Attributes
id< MTLDevice >	_preferredDevice
CGSize	_drawableSize
NSUInteger	_nextDrawableId
NSMutableSet< FlutterTexture * > *	_availableTextures
NSUInteger	_totalTextures
FlutterTexture *	_front
CADisplayLink *	_displayLink
NSUInteger	_displayLinkPauseCountdown
BOOL	_didSetContentsDuringThisDisplayLinkPeriod
BOOL	_displayLinkForcedMaxRate

Properties
id< MTLDevice >	device
id< MTLDevice >	preferredDevice
MTLPixelFormat	pixelFormat
BOOL	framebufferOnly
CGSize	drawableSize
BOOL	presentsWithTransaction
CGColorSpaceRef	colorspace
BOOL	wantsExtendedDynamicRangeContent

Detailed Description

Drop-in replacement (as far as Flutter is concerned) for CAMetalLayer that can present with transaction from a background thread.

Definition at line 12 of file FlutterMetalLayer.h.

Method Documentation

createIOSurface

- (IOSurface *) createIOSurface

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                              {
  unsigned pixelFormat;
  unsigned bytesPerElement;
  if (self.pixelFormat == MTLPixelFormatRGBA16Float) {
    pixelFormat = kCVPixelFormatType_64RGBAHalf;
    bytesPerElement = 8;
  } else if (self.pixelFormat == MTLPixelFormatBGRA8Unorm) {
    pixelFormat = kCVPixelFormatType_32BGRA;
    bytesPerElement = 4;
  } else if (self.pixelFormat == MTLPixelFormatBGRA10_XR) {
    pixelFormat = kCVPixelFormatType_40ARGBLEWideGamut;
    bytesPerElement = 8;
  } else {
    FML_LOG(ERROR) << "Unsupported pixel format: " << self.pixelFormat;
    return nil;
  }
  size_t bytesPerRow =
      IOSurfaceAlignProperty(kIOSurfaceBytesPerRow, _drawableSize.width * bytesPerElement);
  size_t totalBytes =
      IOSurfaceAlignProperty(kIOSurfaceAllocSize, _drawableSize.height * bytesPerRow);
  NSDictionary* options = @{
    (id)kIOSurfaceWidth : @(_drawableSize.width),
    (id)kIOSurfaceHeight : @(_drawableSize.height),
    (id)kIOSurfacePixelFormat : @(pixelFormat),
    (id)kIOSurfaceBytesPerElement : @(bytesPerElement),
    (id)kIOSurfaceBytesPerRow : @(bytesPerRow),
    (id)kIOSurfaceAllocSize : @(totalBytes),
  };
 
  IOSurfaceRef res = IOSurfaceCreate((CFDictionaryRef)options);
  if (res == nil) {
    FML_LOG(ERROR) << "Failed to create IOSurface with options "
                   << options.debugDescription.UTF8String;
    return nil;
  }
 
  if (self.colorspace != nil) {
    CFStringRef name = CGColorSpaceGetName(self.colorspace);
    IOSurfaceSetValue(res, CFSTR("IOSurfaceColorSpace"), name);
  } else {
    IOSurfaceSetValue(res, CFSTR("IOSurfaceColorSpace"), kCGColorSpaceSRGB);
  }
  return (__bridge_transfer IOSurface*)res;
}

dealloc

- (void) dealloc

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
}

didEnterBackground:

- (void) didEnterBackground: (id)  notification

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                          :(id)notification {
  [_availableTextures removeAllObjects];
  _totalTextures = _front != nil ? 1 : 0;
  _displayLink.paused = YES;
}

enabled

+ (BOOL) enabled

Returns whether the Metal layer is enabled. This is controlled by FLTUseFlutterMetalLayer value in Info.plist.

Definition at line 88 of file FlutterMetalLayer.mm.

                {
  static BOOL enabled = NO;
  static BOOL didCheckInfoPlist = NO;
  if (!didCheckInfoPlist) {
    didCheckInfoPlist = YES;
    NSNumber* use_flutter_metal_layer =
        [[NSBundle mainBundle] objectForInfoDictionaryKey:@"FLTUseFlutterMetalLayer"];
    if (use_flutter_metal_layer != nil && [use_flutter_metal_layer boolValue]) {
      enabled = YES;
      FML_LOG(WARNING) << "Using FlutterMetalLayer. This is an experimental feature.";
    }
  }
  return enabled;
}

init

- (instancetype) init

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                     {
  if (self = [super init]) {
    _preferredDevice = MTLCreateSystemDefaultDevice();
    self.device = self.preferredDevice;
    self.pixelFormat = MTLPixelFormatBGRA8Unorm;
    _availableTextures = [[NSMutableSet alloc] init];
 
    _displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(onDisplayLink:)];
    [self setMaxRefreshRate:DisplayLinkManager.displayRefreshRate forceMax:NO];
    [_displayLink addToRunLoop:[NSRunLoop currentRunLoop] forMode:NSRunLoopCommonModes];
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(didEnterBackground:)
                                                 name:UIApplicationDidEnterBackgroundNotification
                                               object:nil];
  }
  return self;
}

isKindOfClass:

- (BOOL) isKindOfClass: (Class)  aClass

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                     :(Class)aClass {
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wunguarded-availability-new"
  // Pretend that we're a CAMetalLayer so that the rest of Flutter plays along
  if ([aClass isEqual:[CAMetalLayer class]]) {
    return YES;
  }
#pragma clang diagnostic pop
  return [super isKindOfClass:aClass];
}

nextDrawable

- (id< CAMetalDrawable >) nextDrawable

Definition at line 88 of file FlutterMetalLayer.mm.

                                    {
  FlutterTexture* texture = [self nextTexture];
  if (texture == nil) {
    return nil;
  }
  FlutterDrawable* drawable = [[FlutterDrawable alloc] initWithTexture:texture
                                                                 layer:self
                                                            drawableId:_nextDrawableId++];
  return drawable;
}

nextTexture

- (FlutterTexture *) nextTexture

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                               {
  CFTimeInterval start = CACurrentMediaTime();
  while (true) {
    FlutterTexture* texture = [self tryNextTexture];
    if (texture != nil) {
      return texture;
    }
    CFTimeInterval elapsed = CACurrentMediaTime() - start;
    if (elapsed > 1.0) {
      NSLog(@"Waited %f seconds for a drawable, giving up.", elapsed);
      return nil;
    }
  }
}

onDisplayLink:

- (void) onDisplayLink: (CADisplayLink*)  link

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                     :(CADisplayLink*)link {
  _didSetContentsDuringThisDisplayLinkPeriod = NO;
  // Do not pause immediately, this seems to prevent 120hz while touching.
  if (_displayLinkPauseCountdown == 3) {
    _displayLink.paused = YES;
    if (_displayLinkForcedMaxRate) {
      [self setMaxRefreshRate:DisplayLinkManager.displayRefreshRate forceMax:NO];
      _displayLinkForcedMaxRate = NO;
    }
  } else {
    ++_displayLinkPauseCountdown;
  }
}

presentOnMainThread:

- (void) presentOnMainThread: (FlutterTexture*)  texture

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                           :(FlutterTexture*)texture {
  // This is needed otherwise frame gets skipped on touch begin / end. Go figure.
  // Might also be placebo
  [self setNeedsDisplay];
 
  [CATransaction begin];
  [CATransaction setDisableActions:YES];
  self.contents = texture.surface;
  [CATransaction commit];
  _displayLink.paused = NO;
  _displayLinkPauseCountdown = 0;
  if (!_didSetContentsDuringThisDisplayLinkPeriod) {
    _didSetContentsDuringThisDisplayLinkPeriod = YES;
  } else if (!_displayLinkForcedMaxRate) {
    _displayLinkForcedMaxRate = YES;
    [self setMaxRefreshRate:DisplayLinkManager.displayRefreshRate forceMax:YES];
  }
}

presentTexture:

- (void) presentTexture: (FlutterTexture*)  texture

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                      :(FlutterTexture*)texture {
  @synchronized(self) {
    if (_front != nil) {
      [_availableTextures addObject:_front];
    }
    _front = texture;
    texture.presentedTime = CACurrentMediaTime();
    if ([NSThread isMainThread]) {
      [self presentOnMainThread:texture];
    } else {
      // Core animation layers can only be updated on main thread.
      dispatch_async(dispatch_get_main_queue(), ^{
        [self presentOnMainThread:texture];
      });
    }
  }
}

returnTexture:

- (void) returnTexture: (FlutterTexture*)  texture

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                     :(FlutterTexture*)texture {
  @synchronized(self) {
    [_availableTextures addObject:texture];
  }
}

setDrawableSize:

- (void) setDrawableSize: (CGSize)  drawableSize

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                       :(CGSize)drawableSize {
  [_availableTextures removeAllObjects];
  _front = nil;
  _totalTextures = 0;
  _drawableSize = drawableSize;
}

setMaxRefreshRate:forceMax:

- (void) setMaxRefreshRate: (double)  refreshRate forceMax: (BOOL)  forceMax

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                         :(double)refreshRate forceMax:(BOOL)forceMax {
  // This is copied from vsync_waiter_ios.mm. The vsync waiter has display link scheduled on UI
  // thread which does not trigger actual core animation frame. As a workaround FlutterMetalLayer
  // has it's own displaylink scheduled on main thread, which is used to trigger core animation
  // frame allowing for 120hz updates.
  if (!DisplayLinkManager.maxRefreshRateEnabledOnIPhone) {
    return;
  }
  double maxFrameRate = fmax(refreshRate, 60);
  double minFrameRate = fmax(maxFrameRate / 2, 60);
  if (@available(iOS 15.0, *)) {
    _displayLink.preferredFrameRateRange =
        CAFrameRateRangeMake(forceMax ? maxFrameRate : minFrameRate, maxFrameRate, maxFrameRate);
  } else {
    _displayLink.preferredFramesPerSecond = maxFrameRate;
  }
}

tryNextTexture

- (FlutterTexture *) tryNextTexture

implementation

Definition at line 88 of file FlutterMetalLayer.mm.

                                  {
  @synchronized(self) {
    if (_front != nil && _front.waitingForCompletion) {
      return nil;
    }
    if (_totalTextures < 3) {
      ++_totalTextures;
      IOSurface* surface = [self createIOSurface];
      if (surface == nil) {
        return nil;
      }
      MTLTextureDescriptor* textureDescriptor =
          [MTLTextureDescriptor texture2DDescriptorWithPixelFormat:_pixelFormat
                                                             width:_drawableSize.width
                                                            height:_drawableSize.height
                                                         mipmapped:NO];
 
      if (_framebufferOnly) {
        textureDescriptor.usage = MTLTextureUsageRenderTarget;
      } else {
        textureDescriptor.usage =
            MTLTextureUsageRenderTarget | MTLTextureUsageShaderRead | MTLTextureUsageShaderWrite;
      }
      id<MTLTexture> texture = [self.device newTextureWithDescriptor:textureDescriptor
                                                           iosurface:(__bridge IOSurfaceRef)surface
                                                               plane:0];
      FlutterTexture* flutterTexture = [[FlutterTexture alloc] initWithTexture:texture
                                                                       surface:surface];
      return flutterTexture;
    } else {
      // Prefer surface that is not in use and has been presented the longest
      // time ago.
      // When isInUse is false, the surface is definitely not used by the compositor.
      // When isInUse is true, the surface may be used by the compositor.
      // When both surfaces are in use, the one presented earlier will be returned.
      // The assumption here is that the compositor is already aware of the
      // newer texture and is unlikely to read from the older one, even though it
      // has not decreased the use count yet (there seems to be certain latency).
      FlutterTexture* res = nil;
      for (FlutterTexture* texture in _availableTextures) {
        if (res == nil) {
          res = texture;
        } else if (res.surface.isInUse && !texture.surface.isInUse) {
          // prefer texture that is not in use.
          res = texture;
        } else if (res.surface.isInUse == texture.surface.isInUse &&
                   texture.presentedTime < res.presentedTime) {
          // prefer texture with older presented time.
          res = texture;
        }
      }
      if (res != nil) {
        [_availableTextures removeObject:res];
      }
      return res;
    }
  }
}

Member Data Documentation

_availableTextures

- (NSMutableSet<FlutterTexture*>*) _availableTextures

protected

Provided by category FlutterMetalLayer().

Definition at line 28 of file FlutterMetalLayer.mm.

_didSetContentsDuringThisDisplayLinkPeriod

- (BOOL) _didSetContentsDuringThisDisplayLinkPeriod

protected

Provided by category FlutterMetalLayer().

Definition at line 43 of file FlutterMetalLayer.mm.

_displayLink

- (CADisplayLink*) _displayLink

protected

Provided by category FlutterMetalLayer().

Definition at line 35 of file FlutterMetalLayer.mm.

_displayLinkForcedMaxRate

- (BOOL) _displayLinkForcedMaxRate

protected

Provided by category FlutterMetalLayer().

Definition at line 46 of file FlutterMetalLayer.mm.

_displayLinkPauseCountdown

- (NSUInteger) _displayLinkPauseCountdown

protected

Provided by category FlutterMetalLayer().

Definition at line 36 of file FlutterMetalLayer.mm.

_drawableSize

- (CGSize) _drawableSize

protected

Provided by category FlutterMetalLayer().

Definition at line 24 of file FlutterMetalLayer.mm.

_front

- (FlutterTexture*) _front

protected

Provided by category FlutterMetalLayer().

Definition at line 31 of file FlutterMetalLayer.mm.

_nextDrawableId

- (NSUInteger) _nextDrawableId

protected

Provided by category FlutterMetalLayer().

Definition at line 26 of file FlutterMetalLayer.mm.

_preferredDevice

- (id<MTLDevice>) _preferredDevice

protected

Provided by category FlutterMetalLayer().

Definition at line 23 of file FlutterMetalLayer.mm.

_totalTextures

- (NSUInteger) _totalTextures

protected

Provided by category FlutterMetalLayer().

Definition at line 29 of file FlutterMetalLayer.mm.

Property Documentation

colorspace

- (CGColorSpaceRef) colorspace

readwriteatomicassign

Definition at line 20 of file FlutterMetalLayer.h.

device

- (id<MTLDevice>) device

readwriteatomicretain

Definition at line 14 of file FlutterMetalLayer.h.

drawableSize

- (CGSize) drawableSize

readwriteatomic

Definition at line 18 of file FlutterMetalLayer.h.

framebufferOnly

- (BOOL) framebufferOnly

readwriteatomic

Definition at line 17 of file FlutterMetalLayer.h.

pixelFormat

- (MTLPixelFormat) pixelFormat

readwriteatomic

Definition at line 16 of file FlutterMetalLayer.h.

preferredDevice

- (id<MTLDevice>) preferredDevice

readatomicassign

Definition at line 15 of file FlutterMetalLayer.h.

presentsWithTransaction

- (BOOL) presentsWithTransaction

readwriteatomic

Definition at line 19 of file FlutterMetalLayer.h.

wantsExtendedDynamicRangeContent

- (BOOL) wantsExtendedDynamicRangeContent

readwriteatomic

Definition at line 21 of file FlutterMetalLayer.h.

---

The documentation for this class was generated from the following files:

• shell/platform/darwin/ios/framework/Source/FlutterMetalLayer.h
• shell/platform/darwin/ios/framework/Source/FlutterMetalLayer.mm