nandi/vflutter_ffi · main.dart

⑂ 4506a586d7400b00d732dcb97167be75ab41cab1
main.dart · 587 lines · 18.9 KBDart    Blame HistoryRaw
Replace V with Nim  nandithebull 1// A Mandelbrot explorer whose pixels are computed in Nim.
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 2
3// What this is actually demonstrating:
4//   * bulk data across the FFI boundary — a full RGBA frame per render,
Replace V with Nim  nandithebull 5//     into a buffer Dart allocates and Nim fills in place (nothing to nf_free)
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 6//   * band parallelism — the image is split into horizontal strips rendered
7//     on separate isolates, which is safe because the library is -gc none
Replace V with Nim  nandithebull 8//   * the same algorithm written twice, in Nim and in Dart, so the cost of the
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 9//     bridge is a number on screen rather than a claim
10import 'dart:async';
11import 'dart:math' as math;
12import 'dart:typed_data';
13import 'dart:ui' as ui;
15import 'package:flutter/gestures.dart';
16import 'package:flutter/material.dart';
Replace V with Nim  nandithebull 17import 'package:nimflutter_ffi/nimflutter_ffi.dart' as v;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 18
19import 'mandelbrot_dart.dart';
21void main() => runApp(const ExampleApp());
23class ExampleApp extends StatelessWidget {
const ExampleApp({super.key});
@override
Widget build(BuildContext context) => MaterialApp(
Replace V with Nim  nandithebull 28        title: 'nimflutter_ffi',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 29        debugShowCheckedModeBanner: false,
      theme: ThemeData.dark(useMaterial3: true).copyWith(
        scaffoldBackgroundColor: const Color(0xFF12141A),
      home: const ExplorerPage(),
37class ExplorerPage extends StatefulWidget {
const ExplorerPage({super.key});
@override
State<ExplorerPage> createState() => _ExplorerPageState();
Add drag-to-pan  nandithebull 44/// Identifies the interactive canvas, so tests can drive gestures on it
45/// without depending on whether a frame has finished rendering yet.
46const Key canvasKey = Key('fractal-canvas');
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 48class _ExplorerPageState extends State<ExplorerPage> {
static const int _renderWidth = 720;
static const int _renderHeight = 540;
v.FractalView _view = const v.FractalView(
  width: _renderWidth,
  height: _renderHeight,
  maxIter: 400,
ui.Image? _image;
bool _rendering = false;
bool _renderQueued = false;
int _lastMs = 0;
Raise the isolate ceiling to 32, and add the sweep that justifies it  nandithebull 62  int _tiles = 16;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 63  _Benchmark? _benchmark;
Add a WebAssembly backend for the example  nandithebull 64  String? _bootError;
/// Bands run on isolates natively and sequentially on web, so the word the
/// UI uses for them has to follow the backend.
Render in parallel on web, via a pool of Web Workers  nandithebull 68  String get _unit =>
    v.supportsIsolateParallelism ? v.parallelUnitName : 'band';
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 70
@override
void initState() {
  super.initState();
Add a WebAssembly backend for the example  nandithebull 74    _boot();
/// Brings the bridge up and draws the first frame.
Future<void> _boot() => _render();
/// Waits for the bridge, returning false if it could not be brought up.
/// On native this resolves immediately. On web it is where the wasm module
/// is fetched and instantiated, which cannot be synchronous.
/// Every path that asks for a frame goes through here, not just startup:
/// the first layout pass calls _fitToCanvas -> _render before initState's
/// future has resolved, so gating only the boot path would still let the
/// very first render race the module load. initialize() is idempotent and
/// hands back the in-flight future, so the extra calls just wait.
Future<bool> _ensureReady() async {
  if (v.isInitialized) return true;
92
    await v.initialize();
    return true;
  } catch (e) {
    if (mounted) setState(() => _bootError = '$e');
    return false;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 99
@override
void dispose() {
  _image?.dispose();
  super.dispose();
/// Renders the current view, coalescing requests that arrive mid-frame.
/// A wheel gesture emits far more events than we can render. Dropping them
/// outright would leave the view mutated but never drawn, so instead the
/// latest request is remembered and serviced once the in-flight frame lands.
Future<void> _render() async {
Add a WebAssembly backend for the example  nandithebull 113    if (!await _ensureReady()) return;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 114    if (_rendering) {
    _renderQueued = true;
    return;
  setState(() => _rendering = true);
120
    _renderQueued = false;
    final view = _view;
    final watch = Stopwatch()..start();
    final pixels = _tiles > 1
        ? await v.renderParallel(view, tiles: _tiles)
        : v.render(view);
    watch.stop();
    final image = await _decode(pixels, view.width, view.height);
    if (!mounted) {
      image.dispose();
      return;
    setState(() {
      _image?.dispose();
      _image = image;
      _lastMs = watch.elapsedMilliseconds;
139
  } while (_renderQueued);
  if (!mounted) return;
  setState(() => _rendering = false);
static Future<ui.Image> _decode(Uint8List rgba, int w, int h) {
  final completer = Completer<ui.Image>();
  ui.decodeImageFromPixels(rgba, w, h, ui.PixelFormat.rgba8888,
      completer.complete);
  return completer.future;
Add drag-to-pan  nandithebull 153  /// Drags the view by a pixel delta, so the image follows the cursor.
void _panBy(Offset delta, Size widgetSize) {
  if (widgetSize.isEmpty || delta == Offset.zero) return;
  setState(() {
    _view = _view.pannedBy(
      delta.dx / widgetSize.width,
      delta.dy / widgetSize.height,
  _render();
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 165  /// Zooms about a point, keeping that point under the cursor.
void _zoomAt(Offset local, Size widgetSize, double factor) {
  if (widgetSize.isEmpty) return;
  setState(() {
    _view = _view.zoomedAt(
      local.dx / widgetSize.width,
      local.dy / widgetSize.height,
      factor,
  _render();
/// Restores the starting framing.
/// Only the pan/zoom is reset. Width and height belong to the canvas (see
/// _fitToCanvas) and maxIter belongs to its slider — clobbering those made
/// "Reset view" silently undo settings the button does not own, and briefly
/// render at the wrong aspect ratio before the canvas corrected it.
void _reset() {
  const home = v.FractalView(width: 1, height: 1);
  setState(() {
    _view = _view.copyWith(
      centerX: home.centerX,
      centerY: home.centerY,
      scale: home.scale,
  _render();
Replace V with Nim  nandithebull 196  /// Renders the identical frame in Nim and in Dart on this isolate, so the
/// comparison is like-for-like rather than Nim-plus-parallelism vs Dart.
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 198  Future<void> _runBenchmark() async {
Add a WebAssembly backend for the example  nandithebull 199    if (!await _ensureReady()) return;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 200    setState(() {
    _rendering = true;
    _benchmark = null;
  final swV = Stopwatch()..start();
  v.render(_view);
  swV.stop();
  final swP = Stopwatch()..start();
  await v.renderParallel(_view, tiles: _tiles);
  swP.stop();
  final swD = Stopwatch()..start();
  renderDart(_view);
  swD.stop();
  if (!mounted) return;
  setState(() {
    _rendering = false;
    _benchmark = _Benchmark(
Add a WebAssembly backend for the example  nandithebull 221        unit: _unit,
      parallel: v.supportsIsolateParallelism,
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 223        vSerialMs: swV.elapsedMilliseconds,
      vParallelMs: swP.elapsedMilliseconds,
      dartMs: swD.elapsedMilliseconds,
      tiles: _tiles,
@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: LayoutBuilder(
        builder: (context, constraints) {
          final wide = constraints.maxWidth > 900;
          final canvas = _buildCanvas();
          final controls = _buildControls();
          return wide
                  crossAxisAlignment: CrossAxisAlignment.stretch,
                  children: [
                    Expanded(child: canvas),
                    SizedBox(
                      child: SingleChildScrollView(child: controls),
              : ListView(
                  children: [
                    AspectRatio(
                      aspectRatio: _renderWidth / _renderHeight,
                      child: canvas,
                    controls,
/// Keeps the rendered buffer at the canvas's aspect ratio.
/// Without this the image would be letterboxed or cropped, and the
/// click-to-zoom maths — which maps widget coordinates straight into the
/// complex plane — would point at the wrong place.
void _fitToCanvas(Size size) {
  if (size.isEmpty) return;
  final height = (_renderWidth * size.height / size.width).round();
  if ((height - _view.height).abs() <= 2) return;
  WidgetsBinding.instance.addPostFrameCallback((_) {
    if (!mounted) return;
    setState(() => _view = _view.copyWith(height: height));
    _render();
Widget _buildCanvas() {
  return LayoutBuilder(
    builder: (context, constraints) {
      final size = Size(constraints.maxWidth, constraints.maxHeight);
      _fitToCanvas(size);
      return Listener(
Add drag-to-pan  nandithebull 288          key: canvasKey,
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 289          // Wheel zoom, anchored at the cursor like the tap zoom. One notch is
        // a small step so a scroll feels continuous rather than octave-wise;
        // the render loop coalesces whatever it cannot keep up with.
        onPointerSignal: (event) {
          if (event is! PointerScrollEvent) return;
          final dy = event.scrollDelta.dy;
          if (dy == 0) return;
          _zoomAt(event.localPosition, size, math.pow(1.0015, dy).toDouble());
        child: GestureDetector(
Add drag-to-pan  nandithebull 299            // Zoom on tap up rather than tap down. The gesture arena already
          // keeps onTapDown from firing once a pan claims the pointer, so
          // this is not what makes drag-to-pan work — it just means the
          // zoom commits on a completed tap.
          onTapUp: (d) => _zoomAt(d.localPosition, size, 0.5),
          onSecondaryTapUp: (d) => _zoomAt(d.localPosition, size, 2.0),
          onPanUpdate: (d) => _panBy(d.delta, size),
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 306            child: Stack(
          fit: StackFit.expand,
          children: [
Add a WebAssembly backend for the example  nandithebull 309              if (_bootError != null)
              // Most likely on web: the wasm glue did not load, so there is
Replace V with Nim  nandithebull 311                // no Nim to call. Say so rather than spinning forever.
Add a WebAssembly backend for the example  nandithebull 312                Center(
                child: Padding(
                  padding: const EdgeInsets.all(24),
                  child: Text(
Replace V with Nim  nandithebull 316                      'Could not start the Nim bridge.\n\n$_bootError',
Add a WebAssembly backend for the example  nandithebull 317                      textAlign: TextAlign.center,
                    style: Theme.of(context).textTheme.bodySmall,
            else if (_image != null)
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 323                RawImage(image: _image, fit: BoxFit.fill)
              const Center(child: CircularProgressIndicator()),
            Positioned(
              left: 12,
              bottom: 12,
              child: _Chip(
                'zoom ${(3.0 / _view.scale).toStringAsFixed(1)}x  ·  '
                '$_lastMs ms  ·  '
Add a WebAssembly backend for the example  nandithebull 332                  '${_tiles > 1 ? "$_tiles ${_unit}s" : "1 $_unit"}',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 333
            if (_rendering)
              const Positioned(
                right: 12,
                child: SizedBox(
                  width: 18,
                  height: 18,
                  child: CircularProgressIndicator(strokeWidth: 2),
/// Returns a non-scrolling column.
/// The wide layout wraps this in its own scroll view; the narrow layout
/// embeds it in the page's ListView. Making this a ListView itself would
/// nest two scrollables and give the inner one unbounded height.
Widget _buildControls() {
  final theme = Theme.of(context);
  return Padding(
    padding: const EdgeInsets.all(20),
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
Replace V with Nim  nandithebull 365        Text('Mandelbrot in Nim', style: theme.textTheme.titleLarge),
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 366        const SizedBox(height: 4),
      Text(
Add drag-to-pan  nandithebull 368          'Scroll or tap to zoom in, right-click to zoom out, drag to pan. '
Replace V with Nim  nandithebull 369          'Every pixel is computed by nf_mandelbrot in src/nimflutter.v.',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 370          style: theme.textTheme.bodySmall,
      const SizedBox(height: 20),
      _Labelled(
        label: 'iterations',
        value: '${_view.maxIter}',
        child: Slider(
          value: _view.maxIter.toDouble(),
          min: 50,
          divisions: 39,
          onChanged: (n) =>
              setState(() => _view = _view.copyWith(maxIter: n.round())),
          onChangeEnd: (_) => _render(),
      _Labelled(
Add a WebAssembly backend for the example  nandithebull 387          label: '${_unit}s',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 388          value: '$_tiles',
        child: Slider(
          value: _tiles.toDouble(),
          min: 1,
Raise the isolate ceiling to 32, and add the sweep that justifies it  nandithebull 392            // Deliberately well past the core count. Bands cost wildly
          // different amounts — rows through the set's interior run the full
          // iteration cap, rows in open space escape immediately — so the
          // frame waits on its slowest band. Over-decomposing lets a free
          // core pick up the next small band instead of idling. Measured on
          // an 8-thread machine: 8 tiles 44 ms, 24 tiles 29 ms.
          max: 32,
          divisions: 31,
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 400            onChanged: (n) => setState(() => _tiles = n.round()),
          onChangeEnd: (_) => _render(),
      const SizedBox(height: 8),
      Row(
        children: [
          Expanded(
            child: FilledButton.tonal(
              onPressed: _rendering ? null : _reset,
              child: const Text('Reset view'),
          const SizedBox(width: 12),
          Expanded(
            child: FilledButton(
              onPressed: _rendering ? null : _runBenchmark,
              child: const Text('Benchmark'),
      const SizedBox(height: 20),
      if (_benchmark != null) _BenchmarkCard(result: _benchmark!),
      const SizedBox(height: 12),
      Card(
        color: theme.colorScheme.surfaceContainerHighest,
        child: Padding(
          padding: const EdgeInsets.all(14),
          child: Text(
Render in parallel on web, via a pool of Web Workers  nandithebull 430              v.backendName == 'dart:ffi'
Replace V with Nim  nandithebull 431                  ? 'The Nim kernel fills a buffer Dart allocates, so no Nim '
Add a WebAssembly backend for the example  nandithebull 432                      'memory crosses the boundary and there is nothing to '
                    'free. Bands are independent, which is what makes the '
Render in parallel on web, via a pool of Web Workers  nandithebull 434                      'isolate slider safe: ARC has no stop-the-world phase '
                    'to serialise them.'
Replace V with Nim  nandithebull 436                  : 'The same Nim kernel, compiled to WebAssembly and reached '
Add a WebAssembly backend for the example  nandithebull 437                      'over dart:js_interop instead of dart:ffi — it fills a '
                    'buffer in the wasm heap, so nothing needs freeing on '
Render in parallel on web, via a pool of Web Workers  nandithebull 439                      'the Dart side. Each Web Worker holds its own instance '
                    'of the module, so nothing is shared and no '
                    'SharedArrayBuffer or COOP/COEP headers are needed. The '
                    'frame is identical to the native build, byte for byte.',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 443              style: theme.textTheme.bodySmall,
453class _Benchmark {
const _Benchmark({
  required this.vSerialMs,
  required this.vParallelMs,
  required this.dartMs,
  required this.tiles,
Add a WebAssembly backend for the example  nandithebull 459    required this.unit,
  required this.parallel,
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 461
final int vSerialMs;
final int vParallelMs;
final int dartMs;
final int tiles;
Add a WebAssembly backend for the example  nandithebull 467
/// 'isolate' natively, 'band' on web.
final String unit;
/// Whether the split actually ran concurrently.
final bool parallel;
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 473
475class _BenchmarkCard extends StatelessWidget {
const _BenchmarkCard({required this.result});
final _Benchmark result;
@override
Widget build(BuildContext context) {
  final theme = Theme.of(context);
  final ratio = result.dartMs / result.vSerialMs;
  return Card(
    child: Padding(
      padding: const EdgeInsets.all(14),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('same frame, three ways',
              style: theme.textTheme.titleSmall),
          const SizedBox(height: 10),
Replace V with Nim  nandithebull 493            _Row(label: 'Nim, 1 ${result.unit}', value: '${result.vSerialMs} ms'),
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 494            _Row(
Replace V with Nim  nandithebull 495                label: 'Nim, ${result.tiles} ${result.unit}s',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 496                value: '${result.vParallelMs} ms'),
Add a WebAssembly backend for the example  nandithebull 497            _Row(label: 'Dart, 1 ${result.unit}', value: '${result.dartMs} ms'),
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 498            const Divider(height: 20),
          Text(
Add a WebAssembly backend for the example  nandithebull 500              result.parallel
Replace V with Nim  nandithebull 501                  ? 'Nim is ${ratio.toStringAsFixed(2)}x Dart on one isolate. '
Add a WebAssembly backend for the example  nandithebull 502                      'For a scalar FP loop the two are close — the real win '
                    'here is the parallel split, which Dart could also do. '
                    'The bridge is what this demonstrates, not a speed claim.'
Replace V with Nim  nandithebull 505                  : 'Nim is ${ratio.toStringAsFixed(2)}x Dart on one thread. '
Add a WebAssembly backend for the example  nandithebull 506                      'The wasm module is single-threaded, so the '
                    '${result.tiles}-band row above is the same work done '
                    'in sequence, not in parallel — it is here to show the '
                    'split produces identical pixels either way.',
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 510              style: theme.textTheme.bodySmall,
519class _Row extends StatelessWidget {
const _Row({required this.label, required this.value});
final String label;
final String value;
@override
Widget build(BuildContext context) => Padding(
      padding: const EdgeInsets.symmetric(vertical: 2),
      child: Row(
        mainAxisAlignment: MainAxisAlignment.spaceBetween,
        children: [
          Text(label, style: Theme.of(context).textTheme.bodyMedium),
          Text(value,
              style: Theme.of(context)
                  .textTheme
                  .bodyMedium
                  ?.copyWith(fontFeatures: const [ui.FontFeature.tabularFigures()])),
542class _Labelled extends StatelessWidget {
const _Labelled({
  required this.label,
  required this.value,
  required this.child,
final String label;
final String value;
final Widget child;
@override
Widget build(BuildContext context) {
  final theme = Theme.of(context);
  return Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      Row(
        mainAxisAlignment: MainAxisAlignment.spaceBetween,
        children: [
          Text(label, style: theme.textTheme.labelLarge),
          Text(value, style: theme.textTheme.labelLarge),
      child,
572class _Chip extends StatelessWidget {
const _Chip(this.text);
final String text;
@override
Widget build(BuildContext context) => Container(
      padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 6),
      decoration: BoxDecoration(
        color: Colors.black.withValues(alpha: 0.55),
        borderRadius: BorderRadius.circular(8),
      child: Text(text,
          style: const TextStyle(color: Colors.white, fontSize: 12)),