iOS: Deprecate and remove read/write FlutterEngine.isGpuDisabled from public API #191347

Background

FlutterEngine.isGpuDisabled is currently exposed as a public read/write property on FlutterEngine in the iOS framework API (FlutterEngine.h).

This property is used internally by the engine to track whether the app currently has access to the GPU. We update it on lifecycle transitions between foreground and background, as well as on startup and when the view is mounted/unmounted from the view hierarchy.

This state management was orginally added to prevent GPU work from running on the IO thread pool when the application loses access to the GPU. While we do need to expose a read/write property for tests, there was no clear need for it to be exposed as public API, and should have been exposed on FlutterEngine_Internal.h.

Why deprecate/delete?

Because isGpuDisabled is a public read/write property, end-users can interfere with the engine's automatically managed GPU state. Of the two (non-no-op) state transitions, both are bad:

• Setting YES -> NO: If a user forces the GPU enabled while the app is backgrounded, it will crash (iOS kills apps attempting to use OpenGL/Metal in the background).
• Setting NO -> YES: If a user disables the GPU while the app is foregrounded, the view will stop responding and hang.

We haven't been able to identify any legitimate use cases where an end user would need to control this property directly. If an app needs to know whether the app is backgrounded, they can determine this from first principles using standard iOS APIs (e.g. observing UIApplication or UIScene lifecycle events), rather than polling or modifying the engine's internal state.

Proposal

1. Deprecate it: Mark the isGpuDisabled property as deprecated in FlutterEngine.h and expose in FlutterEngine_Internal.h for tests.
2. Delete it: In a future major release, remove the property from the public API entirely.