2nd/10_Wiki/Topics/Frontend/Impeller_Engine.md

---
id: wiki-2026-0508-impeller-engine
title: Impeller Engine
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Impeller, Flutter Impeller, Skia Replacement]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [flutter, rendering, gpu, metal, vulkan]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: dart
  framework: flutter
---

# Impeller Engine

## 매 한 줄
> **"매 shader compilation jank 의 제거 — precompiled, predictable"**. Flutter 의 새 rendering engine, Skia 의 replacement. 매 first-frame shader hitch (iOS 특히) 의 근본 해결 — 매 shader 를 build-time 에 precompile 하여 runtime JIT 의 회피.

## 매 핵심

### 매 Skia 의 문제
- Skia 의 SkSL shader 는 매 runtime 에 platform 별 (Metal MSL / Vulkan SPIR-V) 로 compile.
- 매 first encounter 시 ms-단위 stall — janky animation onset.
- iOS 의 특히 심각 (Metal pipeline state object 의 cost).

### 매 Impeller 의 솔루션
- **Ahead-of-time shader compilation**: build 시 모든 shader 를 platform IR 로 변환.
- **Predictable performance**: runtime 에 매 shader compile 의 X — frame budget 안정.
- **Tessellation**: GPU-friendly geometry pipeline (path → triangles 의 CPU offload).
- **Backend**: iOS Metal (stable, Flutter 3.10+ default), Android Vulkan (stable, 3.27+ default), macOS Metal.

### 매 응용
1. iOS Flutter 앱 의 매 launch animation jank 제거.
2. 매 complex path animation (Lottie, custom painters) 의 안정 frame rate.
3. 매 game-like Flutter UI 의 60/120Hz 유지.

## 💻 패턴

### Impeller 활성화 확인 (iOS)
```dart
// ios/Runner/Info.plist
<key>FLTEnableImpeller</key>
<true/>
```

### Custom shader (Impeller-compatible)
```glsl
// shaders/wave.frag
#version 460 core
#include <flutter/runtime_effect.glsl>

uniform vec2 uSize;
uniform float uTime;
out vec4 fragColor;

void main() {
  vec2 uv = FlutterFragCoord().xy / uSize;
  float wave = sin(uv.x * 10.0 + uTime) * 0.5 + 0.5;
  fragColor = vec4(wave, uv.y, 1.0 - wave, 1.0);
}
```

```yaml
# pubspec.yaml
flutter:
  shaders:
    - shaders/wave.frag
```

```dart
// 매 build-time precompiled, 매 runtime jank 의 X
final program = await FragmentProgram.fromAsset('shaders/wave.frag');
final shader = program.fragmentShader()
  ..setFloat(0, size.width)
  ..setFloat(1, size.height)
  ..setFloat(2, time);
canvas.drawRect(rect, Paint()..shader = shader);
```

### Performance overlay
```dart
MaterialApp(
  showPerformanceOverlay: true, // 매 GPU/UI thread frame time 의 visual
  home: MyApp(),
);
```

### Disable Impeller (debugging)
```bash
flutter run --no-enable-impeller
```

### CustomPainter — Impeller 의 fast path
```dart
class WavePainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final path = Path();
    for (double x = 0; x <= size.width; x += 2) {
      path.lineTo(x, sin(x * 0.05) * 20 + size.height / 2);
    }
    // 매 Impeller tessellator 가 GPU 친화 triangle 로 변환
    canvas.drawPath(path, Paint()
      ..style = PaintingStyle.stroke
      ..strokeWidth = 2);
  }
  @override bool shouldRepaint(_) => true;
}
```

### Backdrop blur (Impeller 의 optimized)
```dart
BackdropFilter(
  filter: ImageFilter.blur(sigmaX: 10, sigmaY: 10), // 매 Impeller GPU blur
  child: Container(color: Colors.black.withOpacity(0.3)),
)
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Flutter 3.10+ iOS | Impeller default 유지 |
| Flutter 3.27+ Android | Impeller (Vulkan) default 유지 |
| 매 legacy device (Android API <29) | Skia fallback 자동 |
| Custom shader 사용 | Impeller 의 IR precompile 활용 |
| Engine bug 의심 | `--no-enable-impeller` 로 A/B |

**기본값**: 매 Impeller 활성화 유지 (Flutter 3.27+).

## 🔗 Graph
- 부모: [[Flutter]]
- 변형: [[Skia]] · [[Metal]] · [[Vulkan]]

## 🤖 LLM 활용
**언제**: Flutter 앱 의 jank 진단, custom shader 작성, iOS/Android rendering 차이 디버깅.
**언제 X**: web target (Flutter Web 은 CanvasKit/Skia), 매 Skia-specific API 의존 코드.

## ❌ 안티패턴
- **runtime shader string compile**: Impeller 의 AOT 의 우회 — jank 재발.
- **CustomPainter shouldRepaint=true 남발**: 매 frame 의 unnecessary repaint.
- **legacy SKSL caching workaround 유지**: Impeller 환경에서 의미 없음, 코드 cleanup 필요.

## 🧪 검증 / 중복
- Verified (Flutter docs `flutter.dev/perf/impeller`, Flutter 3.27 release notes).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Impeller engine architecture 정리 |