# Problème de Compatibilité: Impeller et Google Navigation intégrée sur Flutter

## Vue d'ensemble du problème

Les applications Flutter utilisant le SDK Google Navigation intégrée (Google Maps Navigation SDK) peuvent rencontrer des problèmes de rendu graphique lorsque le moteur de rendu Impeller est activé sur Android. Ce document explique le problème, ses symptômes et les solutions de contournement disponibles.

### Appareil testé

Ce problème a été observé et documenté sur l'appareil Android **KM10**. D'autres appareils Android peuvent également être affectés.

## Contexte technique

### Qu'est-ce qu'Impeller?

Impeller est le nouveau moteur de rendu de Flutter, conçu pour remplacer le backend Skia. Il offre plusieurs avantages:
- Performance prévisible grâce à la précompilation des shaders
- Réduction du jank et des pertes d'images
- Meilleure utilisation des API graphiques (Metal sur iOS, Vulkan sur Android)

Cependant, Impeller est encore en cours de stabilisation et certains plugins tiers (particulièrement ceux utilisant des vues natives de plateforme) peuvent rencontrer des problèmes de compatibilité.

### Pourquoi Google Navigation intégrée a des problèmes avec Impeller

Le SDK Google Navigation intégrée utilise des vues natives de plateforme (SurfaceView sur Android) pour afficher le contenu de la carte et de la navigation. L'interaction entre:
1. Le pipeline de rendu de Flutter (Impeller)
2. Les vues natives Android (Platform Views)
3. Le rendu complexe de la navigation (SDK Google Navigation)

Peut causer des glitches de rendu, des problèmes de z-index ou des artefacts visuels.

## Symptômes observés

Lorsque Impeller est activé (comportement par défaut), les problèmes suivants peuvent survenir:

### 1. Glitches de rendu de la carte
- Artefacts visuels sur la surface de la carte
- Problèmes de superposition (z-index) entre les widgets Flutter et la vue native de la carte
- Rendu incohérent des tuiles de carte ou des éléments de navigation

### 2. Problèmes de performance
- Sauts d'images: "Skipped X frames! The application may be doing too much work on its main thread"
- Conflits possibles de rendu GPU entre Impeller et le rendu natif de Google Navigation

### 3. Problèmes d'intégration des vues de plateforme
- La carte utilise une SurfaceView (vue native Android) intégrée dans l'arbre de widgets Flutter
- La composition d'Impeller peut entrer en conflit avec la façon dont Flutter gère les vues de plateforme

## Solutions de contournement

### Solution 1: Désactiver Impeller avec le flag de ligne de commande

**Commande de développement:**
```bash
flutter run -d KM10 --no-enable-impeller
```

**Effet:** Force Flutter à utiliser le backend Skia legacy au lieu d'Impeller.

**Avertissement de dépréciation:**

Lorsque vous exécutez avec `--no-enable-impeller`, Flutter affiche l'avertissement suivant:

```
[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:** Ce flag sera retiré dans une future version de Flutter. Cette solution est donc temporaire.

### Solution 2: Configuration permanente dans AndroidManifest

Pour désactiver Impeller dans les builds de production, ajoutez dans `android/app/src/main/AndroidManifest.xml`:

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

**Avertissement:** Cette configuration sera également dépréciée et retirée dans les futures versions de Flutter.

### Solution 3: Configuration via build.gradle (recommandé)

Dans `android/app/build.gradle`:
```gradle
android {
    defaultConfig {
        // Désactiver Impeller pour les builds Android
        manifestPlaceholders = [
            enableImpeller: 'false'
        ]
    }
}
```

Puis référencez dans `AndroidManifest.xml`:
```xml
<meta-data
    android:name="io.flutter.embedding.android.EnableImpeller"
    android:value="${enableImpeller}" />
```

Cette approche permet de gérer la configuration de manière centralisée.

## Solutions potentielles à long terme

### 1. Attendre les correctifs upstream (Recommandé)

**Action:** Surveiller les dépôts suivants pour les mises à jour:
- [Flutter Engine Issues](https://github.com/flutter/flutter/issues)
- [Plugin Flutter Google Navigation](https://github.com/googlemaps/flutter-navigation-sdk/issues)

**Termes de recherche:**
- "Impeller platform view glitch"
- "Google Navigation Impeller rendering"
- "AndroidView Impeller artifacts"

### 2. Signaler le problème à l'équipe Flutter

Si le problème n'est pas déjà signalé, créez un rapport de bug avec:
- Modèle de l'appareil Android (ex: KM10)
- Version de Flutter (obtenir avec `flutter --version`)
- Version du SDK Google Navigation
- Étapes de reproduction détaillées
- Captures d'écran/vidéo du glitch

**Signaler à:** https://github.com/flutter/flutter/issues/new?template=02_bug.yml

### 3. Essayer Hybrid Composition

Tentez de passer en mode Hybrid Composition pour les vues de plateforme:

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

Cela modifie la façon dont Flutter compose les vues natives et peut résoudre les conflits de rendu avec Impeller.

### 4. Surveiller les mises à jour Flutter

À mesure que l'implémentation d'Impeller par Flutter mature, les futures versions stables incluront des correctifs pour les problèmes de rendu des vues de plateforme. Mettez régulièrement à jour Flutter et testez avec Impeller activé:

```bash
flutter upgrade
flutter run -d KM10  # Tester sans --no-enable-impeller
```

## Implémentation du code

### Exemple d'utilisation de AndroidView pour Google Navigation intégrée

```dart
import 'dart:io' show Platform;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class MapWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Platform.isAndroid
        ? AndroidView(
            viewType: 'google_navigation_flutter',
            onPlatformViewCreated: _onViewCreated,
            creationParams: _viewCreationParams,
            creationParamsCodec: const StandardMessageCodec(),
          )
        : UiKitView(
            viewType: 'google_navigation_flutter',
            onPlatformViewCreated: _onViewCreated,
            creationParams: _viewCreationParams,
            creationParamsCodec: const StandardMessageCodec(),
          );
  }

  void _onViewCreated(int id) {
    // Configuration de la navigation et de la carte
  }

  Map<String, dynamic> get _viewCreationParams {
    return {
      // Paramètres de création
    };
  }
}
```

## Liste de vérification pour tester la compatibilité Impeller

Lors des tests de compatibilité Impeller dans les futures versions de Flutter:

- [ ] La carte s'affiche correctement sans artefacts visuels
- [ ] Les widgets Flutter superposés sur la carte ne causent pas de problèmes de rendu
- [ ] Les marqueurs de carte et éléments UI s'affichent correctement
- [ ] Pas de problèmes de z-index entre les widgets Flutter et la vue de carte
- [ ] Défilement et panoramique fluides sans perte d'images
- [ ] Le rendu des itinéraires de navigation fonctionne correctement
- [ ] Les transitions de caméra sont fluides
- [ ] Les performances sont acceptables (vérifier le timing des images dans DevTools)

## Workflow de développement

### Recommandations actuelles

**Pour le développement Android (testé sur KM10):**
```bash
# Utiliser ceci jusqu'à confirmation de la compatibilité Impeller
flutter run -d KM10 --no-enable-impeller
```

**Pour le développement iOS:**
```bash
# Impeller iOS est plus stable, peut utiliser le comportement par défaut
flutter run -d ios
```

### Hot Reload

Le hot reload fonctionne normalement avec Impeller désactivé:
```bash
# Appuyez sur 'r' dans le terminal
r
```

### Builds de production

**Pour les builds Android de production, désactivez également Impeller** en utilisant l'une des méthodes décrites ci-dessus.

## Avertissements liés aux vues de plateforme

Les avertissements suivants peuvent apparaître dans les logs avec Skia ou Impeller et sont des particularités des vues de plateforme Android, pas des erreurs critiques:

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

## Références

- [Documentation Flutter Impeller](https://docs.flutter.dev/perf/impeller)
- [Vues de plateforme Flutter](https://docs.flutter.dev/platform-integration/android/platform-views)
- [SDK Google Navigation Flutter](https://developers.google.com/maps/documentation/navigation/flutter/reference)
- [Issues Flutter: Support des vues de plateforme Impeller](https://github.com/flutter/flutter/issues?q=is%3Aissue+impeller+platform+view)

## Notes importantes

### Statut de la compatibilité

- **Court terme:** Utilisez `--no-enable-impeller` pour le développement Android
- **Moyen terme:** Surveillez les versions stables de Flutter pour les améliorations d'Impeller
- **Long terme:** L'option de désactivation d'Impeller sera retirée de Flutter

### Alternatives à considérer

Si les problèmes de compatibilité persistent après le retrait de l'option de désactivation:
1. Rechercher des problèmes GitHub existants et voter pour eux
2. Envisager des solutions de cartographie alternatives (Apple Maps sur iOS, autres SDKs)
3. Explorer différents modes de composition des vues de plateforme

## Pour les développeurs futurs

Si vous lisez cette documentation:

1. **D'abord, essayez sans le flag** - Impeller peut avoir été corrigé dans votre version de Flutter:
   ```bash
   flutter run -d KM10
   ```

2. **Si vous voyez des glitches de carte**, ajoutez le flag:
   ```bash
   flutter run -d KM10 --no-enable-impeller
   ```

3. **Si le flag a été retiré et que les cartes ont toujours des glitches**, recherchez:
   - "Flutter Impeller Google Navigation" sur les Issues GitHub
   - Solutions de navigation et cartographie alternatives
   - Modes de composition des vues de plateforme

4. **Considérez ceci comme une solution temporaire**, pas une solution permanente.

## Dernière mise à jour

**Date:** Novembre 2025
**Appareil testé:** KM10 (Android)
**Statut:** Solution de contournement active, surveillance des correctifs upstream en cours
