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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-impeller-engine	Impeller Engine	10_Wiki/Topics	verified	self	Impeller Flutter Impeller Skia Replacement	none	A	0.9	applied	flutter rendering gpu metal vulkan		2026-05-10	pending	language framework dart 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)

// ios/Runner/Info.plist
<key>FLTEnableImpeller</key>
<true/>

Custom shader (Impeller-compatible)

// 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);
}

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

// 매 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

MaterialApp(
  showPerformanceOverlay: true, // 매 GPU/UI thread frame time 의 visual
  home: MyApp(),
);

Disable Impeller (debugging)

flutter run --no-enable-impeller

CustomPainter — Impeller 의 fast path

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)

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 정리