ionic-planb-logistic-app-flutter/docs/IMPELLER_MAP_GLITCH.md

# 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:
1. Flutter's rendering pipeline (Impeller)
2. Native Android views (Platform Views)
3. Complex map rendering (Google Maps SDK)

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

## Current Workaround

### Running with Impeller Disabled

**Command:**
```bash
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:

1. **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

2. **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

3. **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:**
```dart
// 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:
- [Flutter Engine Issues](https://github.com/flutter/flutter/issues)
- [Google Maps Flutter Navigation Plugin](https://github.com/googlemaps/flutter-navigation-sdk/issues)

**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`:

```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:

```dart
// 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:

```bash
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:**
```bash
# Use this until Impeller compatibility is confirmed
flutter run -d KM10 --no-enable-impeller
```

**For iOS development:**
```bash
# iOS Impeller is more stable, can use default
flutter run -d ios
```

### Hot Reload

Hot reload works normally with Impeller disabled:
```bash
# 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`:
```gradle
android {
    defaultConfig {
        // Add Impeller opt-out for release builds
        manifestPlaceholders = [
            enableImpeller: 'false'
        ]
    }
}
```

Then reference in AndroidManifest.xml:
```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

## Related Issues

### 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

- [Flutter Impeller Documentation](https://docs.flutter.dev/perf/impeller)
- [Flutter Platform Views](https://docs.flutter.dev/platform-integration/android/platform-views)
- [Google Maps Flutter Navigation SDK](https://developers.google.com/maps/documentation/navigation/flutter/reference)
- [Flutter Issue: Impeller platform view support](https://github.com/flutter/flutter/issues?q=is%3Aissue+impeller+platform+view)

## 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:

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

2. **If you see map glitches**, add the flag:
   ```bash
   flutter run -d android --no-enable-impeller
   ```

3. **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

4. **Consider this a temporary workaround**, not a permanent solution.