Skip to main content

just_graphics_engine 0.1.0 copy "just_graphics_engine: ^0.1.0" to clipboard
just_graphics_engine: ^0.1.0 copied to clipboard

3D renderer for Flutter on Flutter GPU: glTF 2.0 models, PBR materials, lights, shadows, skinned animation, image-based light and a scene widget.

A 3D renderer for Flutter, built on package:flutter_gpu, Flutter's low-level GPU API powered by Impeller: glTF 2.0 models, physically based materials, lights and shadows, skinned animation and image-based light, drawn into any Flutter app. Made for Flutter 3.47 (3.47.1 or newer): see Flutter versions.

It stands alone, and it is also the 3D of just_game_engine (from its 2.0.0).

Features #

  • gpu.dart: a GPU layer over Flutter GPU (GpuDevice), with a null device for tests and headless runs.
  • assets.dart: glTF 2.0 loading (.glb and .gltf) into ModelData, a model's clip names read from its JSON alone (modelClipNamesOf), and meshes made in code (MeshBuilder).
  • renderer.dart: Renderer3D, a forward renderer with physically based materials, lights, two cascades of sun shadows, skinned meshes, a sky or skybox, image-based light, fog, bloom, HDR, MSAA or FXAA and instancing; DynamicResolution, which picks a render scale from frame times for the caller to apply.
  • Model import: settings beside a model (scale, texture size, material changes) and a cooked copy (.jmodel) a game loads with no glTF parsing or image decoding. Its stamp covers the model, every file it refers to, the settings and the cooker's version, so a tool can tell when to cook it again.
  • Animation: glTF skins and clips (linear, step and cubic-spline keys), sampled into a PosedModel's pose and blended.
  • Scene3DView (in renderer.dart): a widget that draws a Render3DScene from a camera every frame, or says why it can't.
  • testing.dart: GPU test helpers. fixtures.dart: GlbWriter and ready-made skinned models (skinnedBarGlb, mannequinGlb), in pure Dart so a tool can dart run them.

See example/ for models, walking characters, lights, shadows and a sky, drawn by a Scene3DView from an orbiting camera.

Platform support #

flutter_gpu needs the Impeller renderer and an opt-in switch on every platform.

Platform Status
Windows Supported (Impeller on OpenGL ES over ANGLE). Release builds and flutter test both render.
Linux Expected to work the same way as Windows (Impeller on OpenGL ES); untested.
Android Supported on the Vulkan backend only. On devices without Vulkan, Impeller falls back to OpenGL ES, where Flutter GPU draws can hang (flutter/flutter#177873); treat those devices as unsupported.
iOS Expected to work (Impeller on Metal); untested (no Apple hardware).
macOS Expected to work (Impeller on Metal); untested (no Apple hardware).
Web No 3D drawing: Flutter GPU is not available on the web. Web builds (JavaScript and WebAssembly) still compile and run, and Scene3DView shows a short note where the 3D image would be.

On unsupported platforms Renderer3D.tryCreate (and createGpuDevice beneath it) returns null and reports why, so the rest of the app runs as usual.

Flutter versions #

Flutter GPU is still a preview: its API can change from one Flutter minor release to the next. So each release of this package is made for one Flutter minor series — 0.1.x for Flutter 3.47 (3.47.1 or newer; tested on 3.47.9). The package's own API changes only as semantic versioning says; a Flutter that changes Flutter GPU gets a release of this package made for it.

A package can't stop pub from using it with a newer Flutter (pub ignores a dependency's Flutter upper bound), so pin Flutter in your app's own pubspec, where pub does enforce it (Dart 3.9 or newer):

environment:
  sdk: ^3.12.2
  flutter: ">=3.47.1 <3.48.0"

Games made with just and just_game_engine get this, and the exact Flutter installed for them, without asking.

Getting started #

flutter pub add just_graphics_engine

Its build hook compiles the package's shaders with your Flutter SDK when the app builds. Then enable Flutter GPU on the platforms you target.

Windows #

In windows/runner/main.cpp, after the DartProject is created:

project.set_enable_flutter_gpu(true);

flutter run --enable-flutter-gpu also works, but only in debug builds; release builds ignore command-line engine switches.

Linux #

In linux/runner/my_application.cc, on the FlDartProject:

fl_dart_project_set_enable_flutter_gpu(project, TRUE);

Android #

Force the Vulkan backend. Add to your app's android/app/src/main/AndroidManifest.xml, inside <application>:

<meta-data
    android:name="io.flutter.embedding.android.EnableImpeller"
    android:value="true" />
<meta-data
    android:name="io.flutter.embedding.android.EnableFlutterGPU"
    android:value="true" />
<meta-data
    android:name="io.flutter.embedding.android.ImpellerBackend"
    android:value="vulkan" />

Devices (and emulators) without Vulkan still fall back to OpenGL ES. createGpuDevice detects that and returns null with the reason, so the app runs without the 3D view instead of hanging.

iOS / macOS #

Set FLTEnableFlutterGPU to true in Info.plist (and FLTEnableImpeller on macOS).

Testing #

GPU tests are tagged gpu and skip themselves when Flutter GPU is not enabled, so flutter test stays green. To run them (Windows works headless):

flutter test --enable-impeller --enable-flutter-gpu --tags gpu

Wait for submitted work before reading pixels back: reading an image straight after a flutter_gpu CommandBuffer.submit() can return empty pixels on the OpenGL ES backend. submitAndWait in testing.dart waits for a raw command buffer; GpuCommands.submit() already completes only once the GPU is done.

Usage #

Draw a scene #

import 'dart:math' as math;

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:just_graphics_engine/just_graphics_engine.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. The renderer on this platform's GPU, or null (with a reason) where
  //    Flutter GPU can't draw. It loads the shaders and makes its pipelines.
  String? reason;
  final renderer = await Renderer3D.tryCreate(onUnsupported: (r) => reason = r);

  // 2. A scene, in the renderer's axes (+Y down, metres), with a model:
  //    glTF 2.0 (.glb, or .gltf with its files fetched by `fetch`).
  final scene = Render3DScene();
  if (renderer != null) {
    final asset = await rootBundle.load('assets/models/crate.glb');
    final bytes = asset.buffer.asUint8List(asset.offsetInBytes, asset.lengthInBytes);
    final crate = await renderer.uploader.upload(await loadModelData(bytes, name: 'crate.glb'));
    scene.addModel(crate, Matrix4.identity());
    scene.lights.add(Punctual3DLight(kind: Light3DKind.point, position: Vector3(0, -2, -1)));
  }

  // 3. A camera, and a widget that draws the scene from it every frame.
  final camera = Render3DView()..lookAt(Vector3(0, -2, -6), Vector3.zero());
  runApp(MaterialApp(
    home: Scene3DView(
      renderer: renderer,
      scene: scene,
      camera: camera,
      fieldOfView: math.pi / 3,
      unsupportedReason: reason,
      // Before each frame: move the camera, animate the scene.
      onFrame: (elapsed, size) {},
    ),
  ));
}

Scene3DView fills the space it is given, sizes the camera's image from it (renderScale: 0.75 renders fewer pixels) and, with fieldOfView, sets a perspective projection for its aspect ratio. While the GPU is behind (renderer.isBusy: maxFramesInFlight frames not yet drawn) it skips a frame and shows the last image again. Without a renderer it shows the reason; if drawing fails it stops and says why. animate: false draws only when the widget is rebuilt.

Renderer3D.render culls, batches identical meshes into instanced draws, lights with a sun, up to 8 point/spot lights and a hemisphere ambient, draws a gradient sky, and tonemaps HDR into the surface (4x MSAA where the device supports it). renderer.stats tells what the last frame did. To draw into a canvas yourself instead, render into a GpuSurface (renderer.device.createSurface) and paint its image: each read hands out a new ui.Image, so dispose it once drawn. Drawing several views a frame (an editor's panes), pass each render the frame's number (frame:), so the intermediate targets are kept by displayed frames, not by views.

The camera is a Render3DView; nothing here is called RenderView, so package:flutter/rendering.dart can be imported beside this package.

Animated characters #

A PosedModel is one placed copy of a model in a pose of its own. Sample a clip into its pose, update it, and place it each frame:

final posed = PosedModel(mannequin);
scene.addModel(mannequin, placement, posed: posed);
final walk = mannequin.clips['walk']!;

// Each frame:
walk.sample(seconds % walk.duration, posed.pose);
posed.update();
posed.place(placement.clone()..multiply(gltfToEngine));

Skinned meshes sharing a model draw as one instanced draw, their palettes in a float texture.

Meshes made in code #

MeshBuilder builds a Shape3DMesh a triangle, quad, box or lathe at a time; upload it and draw it with a material made in code:

final mesh = (MeshBuilder()..box(-0.5, -0.5, -0.5, 0.5, 0.5, 0.5)).build();
scene.instances.add(MeshInstance(
  renderer.uploader.uploadPrimitive(mesh.toPrimitive()),
  renderer.uploader.material(const Material3DData(baseColor: (1.0, 0.2, 0.2, 1.0), roughness: 0.6)),
  Matrix4.identity(),
));

In a just_game_engine game #

just_game_engine (2.0.0 and later) draws its 3D scenes with this package: give the engine EngineConfig(services: [Graphics3D()]) (package:just_game_engine/just_game_engine_3d.dart) and its Model, Light, Environment and shape components are saved, loaded and drawn from the engine's camera. See just_game_engine's README.

What works today, and what doesn't yet #

  • Models: static glTF 2.0 — meshes, node hierarchies, metallic-roughness materials with every map, alpha mask and blend, double-sided, vertex colours, KHR_texture_transform, KHR_materials_unlit, KHR_materials_emissive_strength, KHR_mesh_quantization, KHR_lights_punctual, sparse accessors. Textures keep straight alpha, as glTF authors them. Mirrored placements (a negative scale) draw the right way out.
  • Animation: skins and glTF clips; poses blend for crossfades. Joint palettes go in one float texture (any joint count, and characters sharing a mesh are one draw); on devices without float textures they go in uniform blocks, up to 64 joints and one draw per character. Morph targets are not played yet.
  • Shadows: the sun casts two cascades of 2048² shadow maps over the first 40 m in front of the camera (renderer.shadows), filtered 3×3. Alpha-masked casters (leaves, fences) are cut out in them as they are drawn.
  • Look: image-based light from the gradient sky or an .hdr skybox (prefiltered reflections, spherical-harmonic ambient), fog, bloom, FXAA; DynamicResolution for the caller's render scale.
  • Not yet: files that require Draco, meshopt or KTX2 textures (refused with a message saying so), compressed cooked textures (ETC2/ASTC), morph targets, a second UV set and more than four joint influences per vertex (the last two load with a warning in ModelData.warnings).
  • Phones: every draw call costs tens of microseconds on Android's Vulkan driver (about 40 us for a bare draw and 60 for a lit one on a Pixel 8), so keep a mobile scene to roughly 100 draws: instancing merges copies of one mesh and material, and renderer.stats.drawCalls counts them.
  • Web: no 3D drawing (see Platform support).

Credits #

The shaders implement published techniques: the BRDF Filament uses, Brian Karis' analytic fit of the environment BRDF, Krzysztof Narkowicz's ACES filmic fit, Christian Schüler's "Followup: Normal Mapping Without Precomputed Tangents", and Timothy Lottes' FXAA (NVIDIA).

License #

BSD 3-Clause; see LICENSE.

0
likes
160
points
505
downloads

Documentation

API reference

Publisher

verified publisherjustunknown.com

Weekly Downloads

3D renderer for Flutter on Flutter GPU: glTF 2.0 models, PBR materials, lights, shadows, skinned animation, image-based light and a scene widget.

Repository (GitHub)
View/report issues
Contributing

Topics

#graphics #gltf #game-engine #gamedev #flutter-gpu

License

BSD-3-Clause (license)

Dependencies

flutter, flutter_gpu, flutter_gpu_shaders, hooks, just_dart, meta, vector_math

More

Packages that depend on just_graphics_engine