Flutter

Index and plan for a set of English learning notes on Flutter, targeting Flutter 3.44. This page is the map: it defines the scope, the reading order, what each page delivers, and the conventions they all follow. The pages themselves are one file per topic in this same directory.

The outline below is organised around what a developer has to be able to do, not around a table of contents. It draws on a common Flutter curriculum (language basics, environment, architecture, widgets, animation, storage, routing, concurrency, networking, state management, lifecycle, the three trees, DevTools, testing, AI, further reading) but restructures it into tracks, and adds the material that outline leaves out — most importantly a 3D rendering track.

Contents

• Baseline and scope
• Curriculum map
• The 3D rendering track
• Additions beyond the reference outline
• Page conventions
• Files and structure
• Related notes

Baseline and scope

Item	Decision
Target SDK	Flutter 3.44 (stable channel) and the Dart release bundled with it
Rendering backend	Impeller, which is the default on mobile — Skia only where a platform still requires it
Design language	Material 3
Primary platforms	Android and iOS; desktop and web called out per page when behaviour differs
Language	English throughout, including code comments

Version discipline: every page records the exact flutter --version output it was verified against, and pins package versions in the pubspec.yaml snippets it shows. Anything described as new, changed, or deprecated in a specific release must be checked against the official release notes and the package changelog before it is written down — not recalled from memory. Where an API is still in preview (Flutter GPU, for example) the page says so and states the risk of churn.

Out of scope: teaching general programming, native Android/iOS development beyond what a Flutter plugin needs, and full app case studies. Each page is a reference with runnable fragments, not a tutorial series.

Curriculum map

Read in this order. The sidebar lists files alphabetically, so this table is the authoritative reading order.

Foundations

Order	File	Delivers
1	Dart essentials	Built-in types, collections, generics, null safety, records, and pattern matching — the language surface Flutter code actually uses
2	Environment setup	SDK install, version switching with FVM, IDE setup, flutter doctor triage, Android/iOS toolchain prerequisites, creating and running the first project
3	Project structure	Directory layout, naming conventions, feature-first vs layer-first, when to split into packages, StatelessWidget vs StatefulWidget as a design choice

Building interfaces

Order	File	Delivers
4	Widgets and layout	Core widgets, the constraints-down/sizes-up layout algorithm, Row/Column/Stack/Flex/slivers, and using Flutter Inspector to explain a layout
5	Animation	Implicit vs explicit animation, AnimationController, Tween, CurvedAnimation, transitions, and how to keep animation off the critical path
6	Navigation and routing	Navigator 1.0 and 2.0, go_router, nested and shell routes, custom transitions, deep and app links

Data and platform

Order	File	Delivers
7	Async and isolates	Event loop, Future/Stream, async/await, isolates, Isolate.spawn, compute, and the failure modes (blocked UI thread, orphaned isolates, unhandled errors)
8	Networking and serialization	REST with http and dio, interceptors, retry, cancellation, caching, and model generation with freezed plus json_serializable
9	Local storage	shared_preferences for settings, SQLite via sqflite/drift for structured data, secure storage for secrets, plain file I/O, and how to choose
10	State management	setState → InheritedWidget → Provider → Riverpod → Bloc, with a decision guide by project size and team, not a winner

How Flutter works

Order	File	Delivers
11	Lifecycle	App lifecycle states, State callbacks (initState, didChangeDependencies, didUpdateWidget, dispose), and disposing resources without leaks
12	Rendering pipeline	Widget / Element / RenderObject trees, why three exist, build-layout-paint-composite phases, dirty marking, repaint boundaries, and what makes rebuilds cheap

Graphics and 3D

Order	File	Delivers
13	Custom painting	CustomPainter, Canvas, paths, transforms, drawVertices, and where custom painting beats composing widgets
14	Fragment shaders	Authoring GLSL for FragmentProgram, declaring shaders in pubspec.yaml, passing uniforms, and raymarched/SDF effects that look 3D at 2D cost
15	3D rendering overview	The approach decision matrix below, prerequisites, and the asset pipeline
16	3D with Flutter GPU and flutter_scene	Real meshes in-process: Flutter GPU and flutter_scene, glTF import, camera, lighting, materials, gesture-driven orbit control
17	Embedded 3D renderers	Handing 3D to an external renderer: Filament (thermion), model_viewer_plus, Unity, AR plugins — and the integration cost of each
18	3D performance	Frame budgets, draw calls, mesh and texture optimisation, measuring on a real mid-range device

Quality and delivery

Order	File	Delivers
19	DevTools and performance	Widget rebuild tracking, Layout Explorer, repaint highlighting, timeline and frame analysis, memory and image sizing
20	Testing	Unit, widget, golden, and integration tests; fakes and mocks; coverage; running tests in CI
21	Build and release	Flavours, signing, build modes, size analysis, and shipping to the stores

Beyond the basics

Order	File	Delivers
22	AI integration	Calling generative models from a Flutter app: SDK options, streaming responses into the UI, key handling, cost and failure design
23	Resources	Curated further reading, source-reading targets, and what to study to move from mid-level to senior

The 3D rendering track

Flutter has no single "3D mode". Getting 3D on screen means choosing a renderer and accepting its trade-offs, so the track starts with the choice rather than with an API.

Choosing an approach

Approach	Renders with	Best for	Main cost
Transform / Matrix4 on widgets	Flutter's compositor	Card flips, parallax, cover-flow, 2.5D	Not real 3D — no depth buffer or lighting, ordering is painter's order
CustomPainter + Canvas.drawVertices	Flutter canvas	Wireframes, low-poly shapes, charts in perspective	You implement projection, culling, and shading yourself
Fragment shaders (FragmentProgram)	GPU, per pixel	Raymarched/SDF scenes, procedural materials, backgrounds, post-effects	No meshes or scene graph; cost scales with painted area
flutter_scene on Flutter GPU	Impeller, in-process	Real glTF models, cameras, lights, inside the widget tree	Preview-stage APIs; expect churn; Impeller required
flutter_gpu directly	Impeller, in-process	Custom render pipelines	Most work — you own buffers, shaders, and pipeline state
Filament via thermion	Native renderer in a texture/platform view	PBR quality, image-based lighting, mature engine	Larger binary, per-platform support to verify
model_viewer_plus (<model-viewer>)	WebView	Quickly showing a .glb, AR quick look	WebView overhead; limited interaction with Flutter state
flutter_unity_widget	Unity runtime	Games or scenes already built in Unity	Two runtimes, heavy binary, complex build
ARCore / ARKit plugins	Native AR frameworks	Camera-anchored AR	Device support, permissions, platform-specific code

Quick rule for 3D rendering overview: decorative depth → transforms or shaders; a model the user manipulates → flutter_scene or Filament; an existing game → Unity; just display a .glb → model_viewer_plus.

Prerequisites to document

• Impeller must be active for the Flutter GPU path; state how to confirm it and what happens on platforms that fall back.
• Per-platform support matrix (Android, iOS, desktop, web) for each package, filled in from the package's own documentation at the time of writing.
• Device baseline for testing: one mid-range Android phone, not only a simulator, because GPU behaviour and thermal throttling do not show up there.

Asset pipeline to document

1. Author or acquire the model; keep it low-poly with baked PBR textures.
2. Export glTF/GLB from Blender with agreed axis and unit conventions, then validate the file before it goes near the app.
3. Compress textures and strip unused channels; record the triangle and texture budget the page recommends.
4. Declare the asset in pubspec.yaml, and for flutter_scene run its importer step so the model is converted to the engine's runtime format at build time. The exact hook and output extension get verified against the pinned package version.
5. Load, then measure cold-start model load time separately from frame time.

Worked example

One example carried across the 3D pages: a product viewer — a full-screen 3D model with orbit and pinch-zoom, tap-to-highlight on a part, and a Flutter UI overlay (title, chips, bottom sheet) drawn as ordinary widgets above it.

It gets built twice, with flutter_scene and with model_viewer_plus, so the comparison is concrete rather than asserted: frame time, APK size delta, cold load time, and how well each one interoperates with widget state and theming. Gesture handling, camera rig, lighting setup, and hit-testing are shown in the flutter_scene version; the WebView version shows the messaging boundary and where it gets awkward.

Caveats the pages must state

• Flutter GPU and flutter_scene are preview-stage. Pin versions, expect breaking changes, and do not present them as the safe default for production.
• Shader and model work is the easiest place in a Flutter app to lose frames. Every 3D page ends with a measurement, not a screenshot.
• Anything claimed about platform support gets checked against the package documentation on the day the page is written.

Additions beyond the reference outline

The source outline is a solid spine but has gaps for the kind of app this repo cares about. Planned additions, in priority order:

• 3D rendering and shaders (pages 13–18) — the reason for this plan.
• Build and release (page 21) — flavours, signing, and size analysis, absent from the source outline but needed by anyone shipping.
• Accessibility and internationalisation — semantics, text scaling, locale handling, RTL. Planned as a section inside Widgets and layout first, and promoted to its own page if it outgrows that.
• Security — key handling, certificate pinning, and secure storage caveats. Cross-linked to the existing Security and SSL notes rather than duplicated.

Page conventions

Every page in this directory follows the repo standard:

• English prose, sentence-case headings, no numbered headings, no sidebar_position front matter.
• Kebab-case file names.
• Fenced code blocks tagged with a language (dart, yaml, bash, glsl, json).
• One topic per file; cross-link instead of repeating another page's material.
• Short intro paragraph stating what the page covers and what it assumes.
• A ## Contents list on any page long enough to need one.
• Code that has been run, not sketched. Snippets show imports when the import is not obvious.
• Version-sensitive statements carry the version they were verified on.

Files and structure

All pages live in docs/flutter/ as flat files — no nesting, since the 3D pages are already grouped by their 3d- prefix. _category_.json supplies the sidebar label and a generated-index landing page, matching the pattern used by the linux/ and yocto/ directories in this repo.

The sidebar orders these files alphabetically. The curriculum map above is the reading order, and each page ends with a link to the next one.

Related notes

Existing notes in this repo that the Flutter pages will link to rather than restate:

• Gradle — the Android build layer underneath a Flutter build.
• IDE, VS Code, and Tools — editor setup shared with other stacks.
• SQLite — the database behind sqflite and drift.
• AI — model and provider background for AI integration.
• Security and SSL — signing, certificates, TLS.
• STM32MP135F-DK — this repo already builds meta-flutter for embedded Linux, which is the natural target for a future page on Flutter outside phones.