lodim

Description:

lodim

lodim #
Fast and pixel accurate fixed-point 2D geometry with minimal approximations.




Optimal for the following use cases:

2D game development that uses tile-based or grid-based rendering.
Graphic rendering of pixel art or other fixed-point rasterized graphics.
Fixed-point geometry for performance or consistency reasons.

Features #
Use lodim to quickly work with 2D geometry in a fixed-point space:

Fixed-point: All values and results are always integers.
Fast: AOT and JIT benchmarked on the Dart VM.
Pixel accurate: Minimal1 ambiguity or hidden rounding errors.
Ergonomics: Familiar API to dart:ui (and similar) for ease of use.
Cross-platform: Works on all Dart platforms, including Flutter and web.

Design Principles #
lodim is designed to be a low-level, fixed-point geometry library that is not
opionated about how you use it. It is not a game engine, nor does it provide
high-level abstractions for rendering or collections.
For example, top-level functions such as getRect or fillRect operate on
either Rect or Pos types and either callback methods or a generic linear
buffer. For a higher-level APIs, consider using lodim in conjunction with
another library, such as package:sector.
Usage #
Just add a dependency in your pubspec.yaml or run the following command:
dart pub add lodim
copied to clipboard
If you've used another 2D geometry library, such as dart:ui from
Flutter, you will find lodim to be very similar. Work with similar types such
as Pos (i.e. Offset) and Rect:
// Creates a (x, y) position.
final pos = Pos(10, 20);

// Creates a rectangle.
final rect = Rect.fromLTWH(0, 0, 100, 100);
copied to clipboard
Take advantage of tested and benchmarked common operations:
// Rotate a position by 135 degrees counter-clockwise.
final rotated = pos.rotate45(-3);

// Get the intersection of two rectangles.
final intersection = rect.intersect(a, b);
copied to clipboard
Use built-in algorithms for common tasks, or define your own:
// Determine the distance between two positions.
final distance = pos1.distanceTo(pos2);

// Use another algorithm to determine the distance or define your own.
final manhattan = pos1.distanceTo(pos2, using: manhattan);

// Draw a line from one position to another.
final line = pos1.lineTo(pos2);

// Use your own algorithm to draw a line.
final custom = pos1.lineTo(pos2, using: someOtherAlgorithm);
copied to clipboard
Benchmarks #
To run the benchmarks, run:
dart run benchmark/benchmark.dart

# Or, to use AOT:
dart compile exe benchmark/benchmark.dart
./benchmark/benchmark.exe

# Or, to profile using devtools:
dart run --pause-isolates-on-start --observe benchmark/benchmark.dart
copied to clipboard
In local benchmarks on a M2 Macbook Pro, compared to [baseline]2 code.
JIT:



Benchmark
lodim
Baseline
Delta




10k allocations positions
479.8 us
362.9 us
-25%


10k euclidian distance
138.3 us
153.5 us
+11%


10k rotations in 45° steps
6875.8 us
13658.7 us
+98%


10k lines drawn
1340049.5
-
-



AOT:



Benchmark
lodim
Baseline
Delta




10k allocations positions
342.7 us
463.9 us
+35%


10k euclidian distance
139.7 us
132.7 us
-5%


10k rotations in 45° steps
5858.2 us
11708.0 us
+100%


10k lines drawn
1333651.0 us
-
-



tl;dr: lodim is faster than baseline code, using both JIT and AOT.
Specializing based on fixed-point geometry allows for optimizations that are
not possible with general-purpose code, such as jump-table based rotations.
Contributing #
To run the tests, run:
dart test
copied to clipboard
To check code coverage locally, run:
dart tool/coverage.dart
copied to clipboard
To preview dartdoc output locally, run:
dart tool/dartdoc.dart
copied to clipboard