nandi/vflutter_ffi · README.md

⑂ f7c3825dc671305345e20a62ea6ac8facbc903bb

README.md · 96 lines · 3.3 KBmarkdown    Blame HistoryRaw
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 1# vflutter_ffi example
3A Mandelbrot explorer whose pixels are computed in V. Scroll to zoom smoothly,
4tap to zoom in, right-click to zoom out — all anchored at the cursor. Sliders
5control the iteration cap and how many isolates the frame is split across;
6"Reset view" restores the framing without disturbing either.
8It exists to exercise the parts of the bridge the string demo cannot:
10* **Bulk data across the boundary.** Each frame is a full RGBA buffer, not a
11  string. Dart allocates it and `vf_mandelbrot` fills it in place, so no V
12  memory crosses the boundary and there is nothing to `vf_free`.
13* **Band parallelism.** The image splits into horizontal strips rendered on
14  separate isolates. Bands are independent by construction, and `-gc none`
15  means no stop-the-world phase to serialise them.
16* **An honest benchmark.** The same algorithm is written twice — in V
17  (`src/vflutter.v`) and in Dart (`lib/mandelbrot_dart.dart`) — and the
18  Benchmark button times both. The tests assert the two agree pixel-for-pixel,
19  which is what makes the comparison meaningful.
21## What the numbers actually say
23Measured here (800x600, maxIter 500, release build, 8-core Linux):
25
26
27| V, one isolate | ~152 ms |
28| V, 4 isolates | ~65 ms |
29| Dart AOT, one isolate | ~165 ms |
31**V is not meaningfully faster than Dart at this.** For a scalar
32floating-point loop, V-through-C and Dart AOT land within ~10% of each other.
33The 2.5x comes from the parallel split, which Dart could do on its own without
34any FFI. Treat this app as a demonstration of the *bridge* — bulk buffers,
35caller-owned memory, safe multi-isolate calls — not as a speed claim for V.
37Reach for V here because you want to write the logic in V, or already have it
38in V, not because C-via-V is expected to outrun Dart AOT on arithmetic.
40
Add a justfile  nandithebull 42
43just mandelbrot
46or, driving Flutter yourself:
Add a Mandelbrot example app, and a V kernel worth demonstrating  nandithebull 48
49
50flutter run -d linux
53Only the Linux runner is generated. For the other platforms, generate their
54runner directories once first:
57flutter create --platforms=android,ios,macos,windows .
60`flutter create` leaves `lib/`, `test/` and `pubspec.yaml` alone. The native
61library is built by the plugin itself: CMake invokes `v` on Linux, Windows and
62Android; iOS and macOS compile the pre-generated C in `ios/Classes/`.
66`flutter test` runs on the host VM rather than in the app bundle, so it needs
67the native library on the loader path:
70./tool/build.sh
71cd example && LD_LIBRARY_PATH=../build flutter test
74The suite covers the zoom maths as a property (the point under the cursor stays
75put), the buffer contract, the band split matching a single-shot render, and
76the V and Dart kernels agreeing exactly.
78## Headless scripts
80No Flutter SDK needed — only `dart` and the host library. Run from the
81repository root, which resolves without Flutter:
84./tool/build.sh
85LD_LIBRARY_PATH=build dart example/lib/fractal_bench.dart   # V vs Dart timings
86LD_LIBRARY_PATH=build dart example/lib/main_test.dart       # string round-trips
87LD_LIBRARY_PATH=build dart example/lib/memory_check.dart    # RSS regression guard
90For a like-for-like comparison with a release app, compile the benchmark AOT
91first — `dart run` uses the JIT:
94dart compile exe example/lib/fractal_bench.dart -o /tmp/bench
95LD_LIBRARY_PATH=build /tmp/bench

Add a Mandelbrot example app, and a V kernel worth demonstrating 81540bb nandithebull 5h ago	1	# vflutter_ffi example
	2
	3	A Mandelbrot explorer whose pixels are computed in V. Scroll to zoom smoothly,
	4	tap to zoom in, right-click to zoom out — all anchored at the cursor. Sliders
	5	control the iteration cap and how many isolates the frame is split across;
	6	"Reset view" restores the framing without disturbing either.
	7
	8	It exists to exercise the parts of the bridge the string demo cannot:
	9
	10	* Bulk data across the boundary. Each frame is a full RGBA buffer, not a
	11	string. Dart allocates it and `vf_mandelbrot` fills it in place, so no V
	12	memory crosses the boundary and there is nothing to `vf_free`.
	13	* Band parallelism. The image splits into horizontal strips rendered on
	14	separate isolates. Bands are independent by construction, and `-gc none`
	15	means no stop-the-world phase to serialise them.
	16	* An honest benchmark. The same algorithm is written twice — in V
	17	(`src/vflutter.v`) and in Dart (`lib/mandelbrot_dart.dart`) — and the
	18	Benchmark button times both. The tests assert the two agree pixel-for-pixel,
	19	which is what makes the comparison meaningful.
	20
	21	## What the numbers actually say
	22
	23	Measured here (800x600, maxIter 500, release build, 8-core Linux):
	24
	25	\| \| time \|
	26	\|---\|---\|
	27	\| V, one isolate \| ~152 ms \|
	28	\| V, 4 isolates \| ~65 ms \|
	29	\| Dart AOT, one isolate \| ~165 ms \|
	30
	31	V is not meaningfully faster than Dart at this. For a scalar
	32	floating-point loop, V-through-C and Dart AOT land within ~10% of each other.
	33	The 2.5x comes from the parallel split, which Dart could do on its own without
	34	any FFI. Treat this app as a demonstration of the bridge — bulk buffers,
	35	caller-owned memory, safe multi-isolate calls — not as a speed claim for V.
	36
	37	Reach for V here because you want to write the logic in V, or already have it
	38	in V, not because C-via-V is expected to outrun Dart AOT on arithmetic.
	39
	40	## Run it
	41
Add a justfile f7c3825 nandithebull 5h ago	42	```bash
	43	just mandelbrot
	44	```
	45
	46	or, driving Flutter yourself:
	47
Add a Mandelbrot example app, and a V kernel worth demonstrating 81540bb nandithebull 5h ago	48	```bash
	49	cd example
	50	flutter run -d linux
	51	```
	52
	53	Only the Linux runner is generated. For the other platforms, generate their
	54	runner directories once first:
	55
	56	```bash
	57	flutter create --platforms=android,ios,macos,windows .
	58	```
	59
	60	`flutter create` leaves `lib/`, `test/` and `pubspec.yaml` alone. The native
	61	library is built by the plugin itself: CMake invokes `v` on Linux, Windows and
	62	Android; iOS and macOS compile the pre-generated C in `ios/Classes/`.
	63
	64	## Tests
	65
	66	`flutter test` runs on the host VM rather than in the app bundle, so it needs
	67	the native library on the loader path:
	68
	69	```bash
	70	./tool/build.sh
	71	cd example && LD_LIBRARY_PATH=../build flutter test
	72	```
	73
	74	The suite covers the zoom maths as a property (the point under the cursor stays
	75	put), the buffer contract, the band split matching a single-shot render, and
	76	the V and Dart kernels agreeing exactly.
	77
	78	## Headless scripts
	79
	80	No Flutter SDK needed — only `dart` and the host library. Run from the
	81	repository root, which resolves without Flutter:
	82
	83	```bash
	84	./tool/build.sh
	85	LD_LIBRARY_PATH=build dart example/lib/fractal_bench.dart # V vs Dart timings
	86	LD_LIBRARY_PATH=build dart example/lib/main_test.dart # string round-trips
	87	LD_LIBRARY_PATH=build dart example/lib/memory_check.dart # RSS regression guard
	88	```
	89
	90	For a like-for-like comparison with a release app, compile the benchmark AOT
	91	first — `dart run` uses the JIT:
	92
	93	```bash
	94	dart compile exe example/lib/fractal_bench.dart -o /tmp/bench
	95	LD_LIBRARY_PATH=build /tmp/bench
	96	```