Mathias Beaulieu-Duncan d46ac9dc14 checkpoint

2025-11-25 17:05:08 -05:00

9.4 KiB

Raw Blame History

Impeller Map Rendering Issue Documentation

Issue Overview

The Plan B Logistics Flutter app experiences map rendering glitches when using Flutter's Impeller rendering engine on Android. This requires the app to run with the --no-enable-impeller flag to function correctly.

Affected Components

Component: Google Maps Navigation SDK for Flutter
Platform: Android (device: KM10 - Android physical device)
Rendering Engine: Impeller (Flutter's new rendering backend)
Symptoms: Visual glitches and rendering artifacts on the map view

Technical Background

What is Impeller?

Impeller is Flutter's next-generation rendering engine designed to replace the Skia backend. It provides:

Predictable performance by precompiling shaders
Reduced jank and frame drops
Better graphics API utilization (Metal on iOS, Vulkan on Android)

However, Impeller is still being stabilized and some third-party plugins (particularly those with native platform views) may experience compatibility issues.

Why Google Maps Has Issues with Impeller

Google Maps Navigation SDK uses native platform views (SurfaceView on Android) that render the map content. The interaction between:

Flutter's rendering pipeline (Impeller)
Native Android views (Platform Views)
Complex map rendering (Google Maps SDK)

Can cause rendering glitches, z-index issues, or visual artifacts.

Current Workaround

Running with Impeller Disabled

Command:

flutter run -d KM10 --no-enable-impeller

Effect: Forces Flutter to use the legacy Skia rendering backend instead of Impeller.

Deprecation Warning

When running with --no-enable-impeller, Flutter displays the following warning:

[IMPORTANT:flutter/shell/common/shell.cc(527)] [Action Required]: Impeller opt-out deprecated.
    The application opted out of Impeller by either using the
    `--no-enable-impeller` flag or the
    `io.flutter.embedding.android.EnableImpeller` `AndroidManifest.xml` entry.
    These options are going to go away in an upcoming Flutter release. Remove
    the explicit opt-out. If you need to opt-out, please report a bug describing
    the issue.

Important: This flag will be removed in a future Flutter release, meaning this workaround is temporary.

Observed Symptoms (When Impeller is Enabled)

When running with Impeller enabled (default behavior), the following issues occur:

Map Rendering Glitches
- Visual artifacts on the map surface
- Possible z-index layering issues between Flutter widgets and native map view
- Inconsistent rendering of map tiles or navigation elements
Performance Issues
- Frame skipping: "Skipped 128 frames! The application may be doing too much work on its main thread"
- Possible GPU rendering conflicts between Impeller and Google Maps' native rendering
Platform View Integration Issues
- The map uses a SurfaceView (native Android view) embedded in Flutter's widget tree
- Impeller's composition may conflict with how Flutter manages platform views

File References

Map Component Implementation

File: lib/components/dark_mode_map.dart

Implements Google Maps Navigation SDK integration
Uses AndroidView platform view for native map rendering
Lines 403-408, 421-426: Auto-recenter functionality
Configures map settings for performance optimization

Key Code Sections:

// Platform view creation (Android)
body: Platform.isAndroid
    ? AndroidView(
        viewType: 'google_navigation_flutter',
        onPlatformViewCreated: _onViewCreated,
        creationParams: _viewCreationParams,
        creationParamsCodec: const StandardMessageCodec(),
      )

Potential Solutions

1. Wait for Upstream Fixes (Recommended)

Action: Monitor the following repositories for updates:

Search Terms:

"Impeller platform view glitch"
"Google Maps Impeller rendering"
"AndroidView Impeller artifacts"

2. Report Issue to Flutter Team

If not already reported, file a bug report with:

Device: KM10 Android device
Flutter version: (check with flutter --version)
Google Maps Navigation SDK version
Detailed reproduction steps
Screenshots/video of the glitch

Report at: https://github.com/flutter/flutter/issues/new?template=02_bug.yml

3. Permanent AndroidManifest Configuration (Temporary)

If needed for production builds before Flutter removes the flag, add to android/app/src/main/AndroidManifest.xml:

<application
    ...>
    <meta-data
        android:name="io.flutter.embedding.android.EnableImpeller"
        android:value="false" />
</application>

Warning: This will also be deprecated and removed in future Flutter releases.

4. Investigate Hybrid Composition (Alternative)

Try switching to Hybrid Composition mode for platform views:

// In android/app/src/main/AndroidManifest.xml
<meta-data
    android:name="io.flutter.embedded_views_preview"
    android:value="true" />

This changes how Flutter composites native views and may resolve rendering conflicts with Impeller.

5. Monitor Flutter Stable Channel Updates

As Flutter's Impeller implementation matures, future stable releases will include fixes for platform view rendering issues. Regularly update Flutter and test with Impeller enabled:

flutter upgrade
flutter run -d KM10  # Test without --no-enable-impeller flag

Testing Checklist

When testing Impeller compatibility in future Flutter versions:

Map renders correctly without visual artifacts
Delivery list sidebar doesn't interfere with map rendering
Map markers and navigation UI elements display properly
No z-index issues between Flutter widgets and map view
Smooth scrolling and panning without frame drops
Navigation route rendering works correctly
Camera transitions are smooth
Auto-recenter functionality works
Performance is acceptable (check frame timing in DevTools)

Development Workflow

Current Recommendation

For Android development:

# Use this until Impeller compatibility is confirmed
flutter run -d KM10 --no-enable-impeller

For iOS development:

# iOS Impeller is more stable, can use default
flutter run -d ios

Hot Reload

Hot reload works normally with Impeller disabled:

# Press 'r' in terminal or
echo "r" | nc localhost 7182

Release Builds

Current Android release builds should also disable Impeller:

In android/app/build.gradle:

android {
    defaultConfig {
        // Add Impeller opt-out for release builds
        manifestPlaceholders = [
            enableImpeller: 'false'
        ]
    }
}

Then reference in AndroidManifest.xml:

<meta-data
    android:name="io.flutter.embedding.android.EnableImpeller"
    android:value="${enableImpeller}" />

Timeline and Impact

Short-term (Current)

Status: Using --no-enable-impeller flag for all Android development
Impact: No user-facing issues, development proceeds normally
Risk: None, Skia backend is stable and well-tested

Medium-term (Next 3-6 months)

Status: Monitor Flutter stable releases for Impeller improvements
Action: Test each stable release with Impeller enabled
Risk: Low, workaround is stable

Long-term (6-12 months)

Status: Impeller opt-out will be removed from Flutter
Action: Must resolve compatibility or report blocking issues
Risk: Medium - may need to migrate away from Google Maps if incompatibility persists

Performance Warnings

The following warnings appear in logs but are expected during development:

I/Choreographer(22365): Skipped 128 frames! The application may be doing too much work on its main thread.

This is related to initial app load and map initialization, not specifically to the Impeller workaround.

Platform View Warnings

E/FrameEvents(22365): updateAcquireFence: Did not find frame.
W/Parcel(22365): Expecting binder but got null!

These warnings appear with both Skia and Impeller backends and are Android platform view quirks, not critical errors.

References

Last Updated

Date: 2025-11-25 Flutter Version: (Run flutter --version to check) Device: KM10 Android Status: Workaround active, monitoring for upstream fixes

Notes for Future Developers

If you're reading this documentation:

First, try without the flag - Impeller may have been fixed in your Flutter version:
```
flutter run -d android
```

If you see map glitches, add the flag:

flutter run -d android --no-enable-impeller

If the flag is removed and maps still glitch, search for:
- "Flutter Impeller Google Maps" on GitHub Issues
- Alternative map solutions (Apple Maps on iOS, alternative SDKs)
- Platform view composition modes
Consider this a temporary workaround, not a permanent solution.

9.4 KiB Raw Blame History