Fixes https://github.com/flutter/flutter/issues/129073
## Changes to Embedder API
Introduced `FlutterRegion` to represent arbitrary region:
```cpp
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`:
```cpp
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`:
```cpp
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
https://github.com/flutter/flutter/assets/96958/09a75eee-316b-4d53-a8b4-d6bb4e1e52f7
## Pre-launch Checklist
- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [X] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [X] I read and followed the [Flutter Style Guide] and the [C++,
Objective-C, Java style guides].
- [X] I listed at least one issue that this PR fixes in the description
above.
- [X] 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.
- [X] I updated/added relevant documentation (doc comments with `///`).
- [X] I signed the [CLA].
- [X] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-new channel
on [Discord].
<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[C++, Objective-C, Java style guides]:
https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
[testing the engine]:
https://github.com/flutter/flutter/wiki/Testing-the-engine
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat
3cb8e82909