Skip to content

Latest commit

 

History

History
428 lines (343 loc) · 20.9 KB

README.md

File metadata and controls

428 lines (343 loc) · 20.9 KB

Flutter VR fork

Experimental VR fork of flutter/flutter, maintained by Adrian Moisa. This fork is the engine half of the Flutter Scene VR demo. The original Flutter README is preserved below this addendum.

Demo setup snapshot: 31 August 2026.

Both forks keep their maintained VR changes on vr. Commit and push fork work only to origin/vr; leave master untouched. Explicitly select vr when cloning either fork, even if GitHub opens a different default branch. Maintainers should select vr as each fork's default branch in GitHub repository settings so repository visitors see the maintained code too.

Why this fork exists

This experiment grew out of building VR support for Visual Space. Maintaining Flutter Scene for the flat application and a separate native 3D engine for Quest would mean implementing and tuning materials, lighting, shadows, and scene features twice. We want to keep Flutter Scene as the 3D renderer in both modes, with native OpenXR responsible for the headset session and presentation.

Flutter Scene already renders geometry on the GPU. The problem was the route its finished images took to the headset: Flutter composition, a large Android surface, and a native copy into the OpenXR eye images. This fork adds the missing engine boundary for borrowing an external GPU render target so that Flutter Scene can write directly into those eye images.

Repository Responsibility
flutter_vr (this repository) Generic external GPU surfaces, frame ownership/completion, and Android GLES interoperation.
flutter_scene_vr Rendering scenes into supplied targets, stereo views, the OpenXR plugin, and the gallery/demo.

The Flutter patch is intentionally generic; it does not put Meta Quest or OpenXR application logic into Flutter. The current external-target implementation is Android/OpenGL ES, not a general Vulkan, Metal, or all-headset VR solution. The API and synchronization contract remain experimental.

Setup scope

The recipe below follows the development setup used for the demo: macOS on Apple Silicon, an Android ARM64 profile engine, and a Meta Quest 3. Other host platforms need the appropriate host build configuration from Flutter's engine setup and compilation guide. Do not copy the macOS ARM64 host target unchanged onto Intel or Linux. Windows is not the documented host for cross-compiling this Android engine.

Install Git, Python 3, curl/unzip, full Xcode with its platform/Metal toolchains, and the Rosetta components required by Flutter's Apple Silicon engine setup. Make sure xcode-select -p selects the full Xcode developer directory rather than only Command Line Tools. For the Android application, install Android Studio, SDK Platform/Build Tools 36, Platform Tools (adb), NDK 28.2.13676358, and CMake 3.22.1 or newer. Use an Android Studio JDK compatible with the checked-in Gradle configuration (Java source compatibility is 17). Engine dependencies are downloaded separately by gclient.

Allow substantial disk space for source dependencies and two engine outputs; this is much larger than installing a normal Flutter SDK. Initial dependency downloads and compilation can take a long time.

1. Install the fork beside your normal Flutter SDK

Use a writable directory without spaces, such as ~/Projects. Keep your stock Flutter installation available for unrelated applications. The engine is already inside the Flutter monorepo; do not clone the retired standalone engine repo.

mkdir -p "$HOME/Projects"
git clone --branch vr https://github.com/adrian-moisa/flutter_vr.git "$HOME/Projects/flutter_vr"
git -C "$HOME/Projects/flutter_vr" remote add upstream https://github.com/flutter/flutter.git
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git "$HOME/Projects/depot_tools"

For an existing fork clone, keep its SDK cache, dependencies, and engine outputs. First commit or otherwise preserve local work, then fetch origin. If local vr does not exist, create it with git switch --create vr --track origin/vr. If it exists, use git switch vr and git branch --set-upstream-to=origin/vr vr to replace any old origin/main tracking. If origin/vr is missing, the maintainer must publish local vr with git push -u origin vr first; do not substitute master. Use origin for your fork and upstream for official Flutter. If reusing an existing SDK at another path, set FLUTTER_VR_ROOT to that path below.

Add these lines to your shell configuration (~/.zshrc for the usual macOS terminal, or your Bash configuration), then open a new terminal:

export FLUTTER_VR_ROOT="$HOME/Projects/flutter_vr"
export FLUTTER_GIT_URL="https://github.com/adrian-moisa/flutter_vr.git"
export PATH="$HOME/Projects/depot_tools:$FLUTTER_VR_ROOT/bin:$PATH"
export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$PATH"

FLUTTER_VR_ROOT is a convenience variable used by this guide. Adjust ANDROID_HOME if Android Studio uses another SDK location. There is no need to copy engine binaries over your stock SDK or install Flutter system-wide.

type -a flutter
flutter --version
flutter doctor -v
flutter doctor --android-licenses

The first Flutter executable should be inside flutter_vr/bin. An explicit "$FLUTTER_VR_ROOT/bin/flutter" invocation also avoids aliases, version-manager shims, or another SDK earlier on PATH.

In Android Studio, set Languages & Frameworks → Flutter → Flutter SDK path to the fork root, not its bin directory. If Dart is not detected, use <fork>/bin/cache/dart-sdk. In VS Code, set dart.flutterSdkPath to the same absolute fork root. Check the Android app's local android/local.properties if Gradle still finds an older SDK; flutter.sdk must refer to this fork. Do not commit machine-specific IDE paths or local.properties.

Selecting the SDK does not select your compiled engine. Without the local-engine flags in step 4, Flutter normally uses downloaded engine artifacts. Do not run flutter upgrade or switch Flutter channels as part of this setup; use the fork revision containing the VR patches.

2. Download engine dependencies

From a fresh clone:

cd "$FLUTTER_VR_ROOT"
cp engine/scripts/standard.gclient .gclient

In the new .gclient, change the solution's url from the upstream Flutter URL to https://github.com/adrian-moisa/flutter_vr.git. Keep its name: ".", managed: False, and deps_file: "DEPS" settings. If you already have a .gclient, inspect and update it instead of overwriting your configuration.

gclient sync --no-history --jobs=1

This is the conservative download recipe used locally after parallel downloads hit rate limits. --no-history reduces dependency history, not the top-level fork's patch history; omit it if you need full dependency histories. The sync job count is independent of the compiler job count below. No separate web-engine build is required to run the gallery in Chrome.

Do not proceed to GN with an incomplete sync. Missing paths such as engine/src/flutter/third_party/skia indicate missing dependencies, not a reason to remove build targets. Re-run the sync after resolving the reported network or toolchain error.

3. Build the engine without exhausting memory

The successful local recipe used a 24 GB Apple Silicon machine, with four Android build jobs and two host build jobs, run sequentially:

cd "$FLUTTER_VR_ROOT/engine/src"

./flutter/tools/gn --android --android-cpu arm64 --runtime-mode profile --no-lto --no-enable-unittests
./flutter/tools/gn --mac-cpu arm64 --runtime-mode profile --no-lto --no-enable-unittests

ninja -C out/android_profile_arm64 -j 4
ninja -C out/host_profile_arm64 -j 2

Both builds are required. The Android output supplies the headset engine and embedding JARs; the host output supplies tools such as gen_snapshot, font-subset, and the shader compiler used to build the application. Run each command only after the previous one succeeds.

  • Limit parallel jobs. Each compile/link process consumes memory. Start at the values above, or reduce to -j 1/-j 2 on smaller machines. A powerful workstation with enough RAM can try -j 20 or more, scaling toward its available core count while watching memory pressure. Core count alone does not determine a safe setting, particularly during linking.
  • Close other applications before building, especially IDE indexing, browsers, and other builds. Do not run the Android and host Ninja builds concurrently when memory is tight.
  • Disable LTO for this demo build. --no-lto avoids the expensive link-time optimization that contributed to local memory pressure. It is a build-time compromise, not a runtime performance improvement.
  • Disable unit-test targets for this demo build. --no-enable-unittests avoids compiling/linking the full unit-test and related benchmark target set just to obtain demo artifacts. We used this to get the local build through, not because tests are unnecessary. This is not an upstream validation recipe; proper coverage and normal validation are still required before proposing the engine changes for acceptance.

If a prior configuration enabled LTO/tests, rerun both GN commands before resuming Ninja. If a linker is killed or the machine starts swapping heavily, stop that build and restart with fewer jobs. Keep the existing output directories so completed work can be reused; deleting the build is not the first remedy.

Check that the outputs include:

engine/src/out/android_profile_arm64/lib.stripped/libflutter.so
engine/src/out/android_profile_arm64/flutter_embedding_profile.jar
engine/src/out/android_profile_arm64/arm64_v8a_profile.jar
engine/src/out/host_profile_arm64/gen_snapshot
engine/src/out/host_profile_arm64/font-subset
engine/src/out/host_profile_arm64/impellerc
engine/src/out/host_profile_arm64/shader_lib/

The two engine configurations and the APK must use the same runtime mode. Changing only --profile to --debug or --release is not sufficient; build matching Android and host outputs first.

4. Use the engine with Flutter Scene VR

Follow the Flutter Scene VR README to clone its workspace, select the local flutter_gpu Dart package, connect Quest, and launch the gallery. That Dart dependency override is essential: --local-engine selects native artifacts, not the matching package sources.

After that workspace setup, a manual APK build has this shape:

cd "$HOME/Projects/flutter_scene_vr/examples/openxr_quest"
"$FLUTTER_VR_ROOT/bin/flutter" \
  --local-engine-src-path="$FLUTTER_VR_ROOT/engine/src" \
  --local-engine=android_profile_arm64 \
  --local-engine-host=host_profile_arm64 \
  build apk --profile --target-platform android-arm64 --target lib/main.dart

Building an APK does not install or launch it. The Scene repository's quest-build-and-deploy-local-forks.sh helper performs the build, device selection, install, and immersive launch, with overridable SDK/engine paths. Use that helper for the complete first-run flow.

Status and upstream direction

These forks make the demo reproducible while the shared rendering approach is developed. They are not official Flutter VR support, and upstream acceptance or a delivery date has not been agreed. The intent is to contribute the changes back and stop requiring forks.

The Flutter engine contribution needs careful API, resource lifetime, synchronization, backend, and test review. The Scene integration is more local, but still depends on that engine capability and needs performance and platform validation. GPU completion uses EGL fences where supported, with a conservative blocking fallback. Further synchronization, lifecycle, and performance work must keep borrowed images alive until GPU work is complete.

The plan is to periodically rebase these forks onto their upstream projects while preparing contributions. Treat the two forks as a compatible pair: record their commit IDs for a shared demo, preserve local changes before updating, and follow the fork's published revision rather than blindly tracking upstream. After engine source or DEPS changes, sync dependencies, rerun GN as needed, and rebuild both engine outputs before rebuilding the APK. After Scene changes, refresh dependencies and let its build hooks regenerate assets.

Update or publish vr

For developers and runners consuming the published fork:

cd "$FLUTTER_VR_ROOT"
git switch vr
git pull --ff-only origin vr

When engine source, dependencies, or build configuration changes, repeat the sync, GN, and both Ninja builds above. Keep out for incremental compilation. A branch rename alone or a framework-only Dart change does not require native engine compilation. Rebuild the application to pick up framework changes.

Maintainers commit on vr and publish ordinary new commits with git push -u origin vr. For an upstream update, start from a clean working tree, fetch both remotes, review any remote-only commits, then rebase:

cd "$FLUTTER_VR_ROOT"
git switch vr
git fetch origin
git log --oneline --left-right vr...origin/vr
git fetch upstream
git rebase upstream/master

Use upstream for https://github.com/flutter/flutter.git; add that remote if an older clone lacks it. Reconcile unexpected divergence before rebasing. After rebuilding affected engine outputs and checking the matching Scene fork, publish rewritten history with git push --force-with-lease origin vr. Never push to master, main, or upstream. A failed lease requires reviewing remote changes. If a consumer's fast-forward pull fails after a rebase or amend, reconcile it with published vr; do not switch to master or delete the engine outputs. The runner consumes published revisions and does not rebase or push.

Original Flutter README

The material below is preserved from upstream. Its stock installation links do not replace the custom-engine setup above.


Flutter CI Status Discord badge Twitter handle BlueSky badge LFX Health Score CII Best Practices SLSA 1

Flutter is Google's SDK for crafting beautiful, fast user experiences for mobile, web, and desktop from a single codebase. Flutter works with existing code, is used by developers and organizations around the world, and is free and open source.

Documentation

For release and other announcements, join the flutter-announce mailing list. Our documentation also tracks breaking changes across releases.

Terms of service

The Flutter tool may occasionally download resources from Google servers. By downloading or using the Flutter SDK, you agree to the Google Terms of Service: https://policies.google.com/terms

For example, when installed from GitHub (as opposed to from a prepackaged archive), the Flutter tool will download the Dart SDK from Google servers immediately when first run, as it is used to execute the flutter tool itself. This will also occur when Flutter is upgraded (e.g. by running the flutter upgrade command).

About Flutter

We think Flutter will help you create beautiful, fast apps, with a productive, extensible and open development model, whether you're targeting iOS or Android, web, Windows, macOS, Linux or embedding it as the UI toolkit for a platform of your choice.

Beautiful user experiences

We want to enable designers to deliver their full creative vision without being forced to water it down due to limitations of the underlying framework. Flutter's layered architecture gives you control over every pixel on the screen and its powerful compositing capabilities let you overlay and animate graphics, video, text, and controls without limitation. Flutter includes a full set of widgets that deliver pixel-perfect experiences whether you're building for iOS (Cupertino) or other platforms (Material), along with support for customizing or creating entirely new visual components.

Reflectly hero image

Fast results

Flutter is fast. It's powered by hardware-accelerated 2D graphics libraries like Skia (which underpins Chrome and Android) and Impeller. We architected Flutter to support glitch-free, jank-free graphics at the native speed of your device.

Flutter code is powered by the world-class Dart programming language, which enables compilation to 32-bit and 64-bit ARM machine code for iOS and Android, JavaScript and WebAssembly for the web, as well as Intel x64 and ARM for desktop devices.

Dart diagram

Productive development

Flutter offers stateful hot reload, allowing you to make changes to your code and see the results instantly without restarting your app or losing its state.

Hot reload animation

Extensible and open model

Flutter works with any development tool (or none at all), and also includes editor plug-ins for both Visual Studio Code and IntelliJ / Android Studio. Flutter provides tens of thousands of packages to speed your development, regardless of your target platform. And accessing other native code is easy, with support for both FFI (on Android, on iOS, on macOS, on Linux, and on Windows) as well as platform-specific APIs.

Flutter is a fully open-source project, and we welcome contributions. Information on how to get started can be found in our contributor guide.