[macOS] Implement unobstructed platform views

[knopp]

Fixes flutter/flutter#129073

Changes to Embedder API

Introduced FlutterRegion to represent arbitrary region:

typedef struct {
  /// The size of this struct. Must be sizeof(FlutterRegion).
  size_t struct_size;
  /// Number of rectangles in the region.
  size_t rects_count;
  /// The rectangles that make up the region.
  FlutterRect* rects;
} FlutterRegion;

Note that this is identical to struct FlutterDamage with more generic naming. Maybe down the line we could deprecate FlutterDamage and use FlutterRegion instead.

Introduced FlutterBackingStorePresentInfo:

typedef struct {
  size_t struct_size;

  /// The area of the backing store that contains Flutter contents. Pixels
  /// outside of this area are transparent and the embedder may choose not
  /// to render them. Coordinates are in physical pixels.
  FlutterRegion* paint_region;
} FlutterBackingStorePresentInfo;

In future this struct may also contain more precise hit test region (when framework supports it) and/or information relevant to partial repaint (buffer damage, frame damage).

Added a backing_store_present_info field to FlutterLayer:

typedef struct {
  ...
  /// Extra information for the backing store that the embedder may
  /// use during presentation.
  FlutterBackingStorePresentInfo* backing_store_present_info;
} FlutterLayer;

Changes to the macOS embedder

This PR adds support for FLTEnableSurfaceDebugInfo flag in main bundle Info.plist that enables visual indicators of overlay layers.

Example of unobstructed platform views

surface-debug.mov

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide and the C++, Objective-C, Java style guides.
• I listed at least one issue that this PR fixes in the description above.
• I added new tests to check the change I am making or feature I am adding, or Hixie said the PR is test-exempt. See testing the engine for instructions on writing and running engine tests.
• I updated/added relevant documentation (doc comments with ///).
• I signed the CLA.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[chinmaygarde]

The ABI remains stable but the API breaks. I'd rather not break. You could use typedefs.

…

On Wed, Jun 21, 2023 at 11:16 AM Loïc Sharma ***@***.***> wrote: Note that this is identical to struct FlutterDamage with more generic naming... Are we allowed to rename structs in the embedder API? The embedder API allows renaming members <https://github.com/flutter/engine/blob/08aaa88bf67fcd5a18d4309d89c1e940a544e49a/shell/platform/embedder/embedder.h#L39-L41>, I *think* renaming a struct wouldn't break ABI. — Reply to this email directly, view it on GitHub <#42960 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAKYNJBPH3QUX5CYYXR7PDXMM26ZANCNFSM6AAAAAAZKOXYUM> . You are receiving this because your review was requested.Message ID: ***@***.***>

[loic-sharma]

We've been inconsistent, but I believe the preferred naming pattern is rects_count

[loic-sharma]

@chinmaygarde I deleted my comment as I figured it'd better to keep FlutterDamage and FlutterRegion separate structs in case we ever need to add new members to FlutterDamage that don't make sense in FlutterRegion. Thanks for the feedback though, I agree that'd be better 👍

[knopp]

The ABI remains stable but the API breaks. I'd rather not break. You could use typedefs.
…

FlutterDamage has field called damage while FlutterRegion has field called rects. Not sure how the typedef would help unless we union the fields, at which point maybe it's better to just keep the structs separate.

[loic-sharma]

@knopp FYI, Chris Bracken is out on vacation until July 10th and will likely not be able to review until then. Apologies for the delay!

[knopp]

@knopp FYI, Chris Bracken is out on vacation until July 10th and will likely not be able to review until then. Apologies for the delay!

Thanks for the heads-up!

[cbracken]

I'm back and taking a look at this and the others! Thanks so much for sending them!

[cbracken]

Overall looks great - I'm still looking at the embedder API side changes. Sent the rest of the comments.

[cbracken]

Just a quick note on the embedder.h changes that I'll send out now while I continue to review.

[knopp]

I have removed the commit [Move FlutterBackingStorePresentInfo into FlutterBackingStore]. This moves backing_store_present_info back to FlutterLayer. Question is, whether this should be another union - maybe down the line we'll have additional present information for other layer types as well?

[cbracken]

lgtm - thanks for your patience on this one, in particular on the embedder API changes.