Repository: flutter
Issue: Platform Views are massively expensive and the docs and instrumentation don't highlight this enough.
Labels: framework,engine,d: api docs,a: platform-views,P3,a: plugins,team-engine,triaged-engine

Platform views are massively expensive in terms on memory usage, loss of concurrency, battery usage, additional render target switches, etc.. Based on feedback seen from customers (for example, in this [internal doc](https://docs.google.com/document/d/16Vel2Nwy97Bc65yIiTpF-zevgArLqK8ISdgIQtV_igw/edit?ts=5d76b651#heading=h.r2i7gn60zi3s)), it is observed that customers may not be adequately aware of the negative performance implications of the addition of a platform views in their applications. While these impacts were known upfront, they are only documented at the lowest levels of the API at [`SceneBuilder::addPlatformView`](https://api.flutter.dev/flutter/dart-ui/SceneBuilder/addPlatformView.html). Even the documentation at that level is easy to miss. Also, customers rarely use that API directly (instead platform views are wrapped in higher level widgets) and may miss the moment they step off a steep performance cliff.

While the implementation of platform views continues to get better, the savings are minor compared to the baseline impact of the addition of a single platform view to the hierarchy. The well informed developer has the opportunity to make their applications significantly more performant and delightful for their users.

A deeper discussion of the performance impact of the feature should include a discussion of the following issues:
* The additional memory use.
  * Discuss how the extra backing stores have be created.
  * Discuss how large each backing store can get (screen size times buffer count which could be as high as 3 plus some additional fixed overhead).
  * Discuss how the over is not constant and is function of the number of interleaving levels in the resultant view hierarchy.
* The negative implications to concurrency (subject to platform specific restrictions).
  * How a more restrictive thread configuration needs to be chosen (no GPU thread).
  * How the frame pipeline depth needs to be reduced.
  * The cost of switching thread configurations (barrier blocks and such).
* De-optimizations in the renderer due to fewer retained layers from frame to frame.
* De-optimization in the driver due to additional render target switches.
  * Discuss how expensive a render target switch is relative to something the user can observe (say a backdrop filter).
* The degradation in battery life.
  * Discuss how Flutter has to perform more composition (that would otherwise have been avoided if there was no interleaving level).
  * Discuss how the system compositor has to do more composition.

It is recommended that these discussions are surfaces at multiple levels in the documentation. Including the following landing pages specifically identified:
* The [PlatformViewLayer](https://api.flutter.dev/flutter/rendering/PlatformViewLayer-class.html) class reference  and each memory of the same (for example the separate page for the constructor which comes up before everything else in search results).
* The specific link for the [platform view layer](https://api.flutter.dev/flutter/rendering/rendering-library.html) in the rendering library.
* It is recommended that discussions about performance be highlighted somehow (maybe a red highlight to draw attention so it is hard to miss).
* Highlight these platform view related discussions in the [Performance best practices](https://flutter.dev/docs/testing/best-practices) section. The omission of platform views from this section is alarming and we should address it ASAP. Especially since this feature has a more severe performance implication than everything currently on that page.
* Highlight how to find and audit the use of platform views in the application in the section on [performance profiling](https://flutter.dev/docs/testing/ui-performance). Again, this section is not accurate today w.r.t the discussion on threading configuration when a platform view is in use.
* In each of the sections on the main docs sites, a discussion of the performant alternatives to the use of platform views ought to be added.

I suspect these discussions will need to be quickly and constantly updated as the some of the performance impacts are ameliorated. Platform views are really powerful and sometimes the only way to achieve some key piece of functionality in the application. But a more informed approach to their use can significantly improve application performance along multiple dimensions.