feat: Added TextFormatter classes

packages/flame/lib/src/text/common/glyph_data.dart

@@ -0,0 +1,19 @@
+class GlyphData {
+  const GlyphData({
+    required this.left,
+    required this.top,
+    this.right,
+    this.bottom,
+  });
+
+  const GlyphData.fromLTWH(this.left, this.top, double width, double height)
+      : right = left + width,
+        bottom = top + height;
+
+  const GlyphData.fromLTRB(this.left, this.top, this.right, this.bottom);
+
+  final double left;
+  final double top;
+  final double? right;
+  final double? bottom;
+}

packages/flame/lib/src/text/common/glyph_info.dart

@@ -0,0 +1,14 @@
+/// Helper class that stores dimensions of a single glyph for a spritesheet-
+/// based font.
+class GlyphInfo {
+  double srcLeft = 0;
+  double srcTop = 0;
+  double srcRight = 0;
+  double srcBottom = 0;
+  double rstSCos = 1;
+  double rstSSin = 0;
+  double rstTx = 0;
+  double rstTy = 0;
+  double width = 0;
+  double height = 0;
+}

packages/flame/lib/src/text/common/line_metrics.dart

@@ -0,0 +1,98 @@
+import 'dart:ui';
+
+import 'package:flame/src/text/common/text_line.dart';
+
+/// [LineMetrics] object contains measurements of a [TextLine].
+///
+/// A line of text can be thought of as surrounded by a box (rect) that outlines
+/// the boundaries of the text, plus there is a [baseline] inside the box which
+/// is the line on top of which the text is placed.
+///
+/// The [LineMetrics] box surrounding a piece of text is not necessarily tight:
+/// there's usually some amount of space above and below the text glyphs to
+/// improve legibility of multi-line text.
+class LineMetrics {
+  LineMetrics({
+    double left = 0,
+    double baseline = 0,
+    double width = 0,
+    double? ascent,
+    double? descent,
+    double? height,
+  })  : _left = left,
+        _baseline = baseline,
+        _width = width,
+        _ascent = ascent ?? (height == null ? 0 : height - (descent ?? 0)),
+        _descent =
+            descent ?? (height == null ? 0 : height - (ascent ?? height));
+
+  /// X-coordinate of the left edge of the box.
+  double get left => _left;
+  double _left;
+
+  /// Y-coordinate of the baseline of the box. When several line fragments are
+  /// placed next to each other, their baselines will match.
+  double get baseline => _baseline;
+  double _baseline;
+
+  /// The total width of the box.
+  double get width => _width;
+  double _width;
+
+  /// The distance from the baseline to the top of the box.
+  double get ascent => _ascent;
+  double _ascent;
+
+  /// The distance from the baseline to the bottom of the box.
+  double get descent => _descent;
+  double _descent;
+
+  double get right => left + width;
+  double get top => baseline - ascent;
+  double get bottom => baseline + descent;
+  double get height => ascent + descent;
+
+  /// Moves the [LineMetrics] box by the specified offset [dx], [dy] leaving its
+  /// width and height unmodified.
+  void translate(double dx, double dy) {
+    _left += dx;
+    _baseline += dy;
+  }
+
+  /// Moves this [LineMetrics] box to the origin, setting [left] and [baseline]
+  /// to 0.
+  void moveToOrigin() {
+    _left = 0;
+    _baseline = 0;
+  }
+
+  /// Sets the position of the left edge of this [LineMetrics] box, leaving the
+  /// [right] edge in place.
+  void setLeftEdge(double x) {
+    _width = right - x;
+    _left = x;
+  }
+
+  /// Appends another [LineMetrics] box that is adjacent to the current and on
+  /// the same baseline. The current object will be modified to encompass the
+  /// [other] box.
+  void append(LineMetrics other) {
+    assert(
+      baseline == other.baseline,
+      'Baselines do not match: $baseline vs ${other.baseline}',
+    );
+    _width = other.right - left;
+    if (_ascent < other.ascent) {
+      _ascent = other.ascent;
+    }
+    if (_descent < other.descent) {
+      _descent = other.descent;
+    }
+  }
+
+  Rect toRect() => Rect.fromLTWH(left, top, width, height);
+
+  @override
+  String toString() => 'LineMetrics(left: $left, baseline: $baseline, '
+      'width: $width, ascent: $ascent, descent: $descent)';
+}

packages/flame/lib/src/text/common/text_line.dart

@@ -0,0 +1,15 @@
+import 'package:flame/src/text/common/line_metrics.dart';
+import 'package:flame/src/text/inline/text_element.dart';
+
+/// [TextLine] is an abstract class describing a single line (or a fragment of
+/// a line) of a laid-out text.
+///
+/// More specifically, after any [TextElement] has been laid out, its layout
+/// will be described by one or more [TextLine]s.
+abstract class TextLine {
+  /// The dimensions of this line.
+  LineMetrics get metrics;
+
+  /// Move the text within this [TextLine] by the specified offsets [dx], [dy].
+  void translate(double dx, double dy);
+}

packages/flame/lib/src/text/formatter_text_renderer.dart

@@ -0,0 +1,35 @@
+import 'dart:ui';
+
+import 'package:flame/src/anchor.dart';
+import 'package:flame/src/text/formatters/text_formatter.dart';
+import 'package:flame/text.dart';
+import 'package:vector_math/vector_math_64.dart';
+
+/// Helper class that implements a [TextRenderer] using a [TextFormatter].
+class FormatterTextRenderer<T extends TextFormatter> extends TextRenderer {
+  FormatterTextRenderer(this.formatter);
+
+  final T formatter;
+
+  @override
+  Vector2 measureText(String text) {
+    final box = formatter.format(text).lastLine.metrics;
+    return Vector2(box.width, box.height);
+  }
+
+  @override
+  void render(
+    Canvas canvas,
+    String text,
+    Vector2 position, {
+    Anchor anchor = Anchor.topLeft,
+  }) {
+    final txt = formatter.format(text);
+    final box = txt.lastLine.metrics;
+    txt.lastLine.translate(
+      position.x - box.width * anchor.x,
+      position.y - box.height * anchor.y - box.top,
+    );
+    txt.render(canvas);
+  }
+}

packages/flame/lib/src/text/formatters/sprite_font_text_formatter.dart

@@ -0,0 +1,83 @@
+import 'dart:typed_data';
+import 'dart:ui' hide LineMetrics;
+
+import 'package:flame/src/text/common/glyph_data.dart';
+import 'package:flame/src/text/common/glyph_info.dart';
+import 'package:flame/src/text/common/line_metrics.dart';
+import 'package:flame/src/text/formatters/text_formatter.dart';
+import 'package:flame/src/text/inline/sprite_font_text_element.dart';
+
+class SpriteFontTextFormatter extends TextFormatter {
+  SpriteFontTextFormatter({
+    required this.source,
+    required double charWidth,
+    required double charHeight,
+    required Map<String, GlyphData> glyphs,
+    this.scale = 1,
+    this.letterSpacing = 0,
+  })  : scaledCharWidth = charWidth * scale,
+        scaledCharHeight = charHeight * scale,
+        _glyphs = glyphs.map((char, rect) {
+          assert(
+            char.length == 1,
+            'A glyph must have a single character: "$char"',
+          );
+          final info = GlyphInfo();
+          info.srcLeft = rect.left;
+          info.srcTop = rect.top;
+          info.srcRight = rect.right ?? rect.left + charWidth;
+          info.srcBottom = rect.bottom ?? rect.top + charHeight;
+          info.rstSCos = scale;
+          info.rstTy = (charHeight - (info.srcBottom - info.srcTop)) * scale;
+          info.width = charWidth * scale;
+          info.height = charHeight * scale;
+          return MapEntry(char.codeUnitAt(0), info);
+        });
+
+  final Image source;
+  final paint = Paint()..color = const Color(0xFFFFFFFF);
+  final double letterSpacing;
+  final double scale;
+  final double scaledCharWidth;
+  final double scaledCharHeight;
+  final Map<int, GlyphInfo> _glyphs;
+
+  @override
+  SpriteFontTextElement format(String text) {
+    final rstTransforms = Float32List(4 * text.length);
+    final rects = Float32List(4 * text.length);
+    var j = 0;
+    var x0 = 0.0;
+    final y0 = -scaledCharHeight;
+    for (final glyph in _textToGlyphs(text)) {
+      rects[j + 0] = glyph.srcLeft;
+      rects[j + 1] = glyph.srcTop;
+      rects[j + 2] = glyph.srcRight;
+      rects[j + 3] = glyph.srcBottom;
+      rstTransforms[j + 0] = glyph.rstSCos;
+      rstTransforms[j + 1] = glyph.rstSSin;
+      rstTransforms[j + 2] = x0 + glyph.rstTx;
+      rstTransforms[j + 3] = y0 + glyph.rstTy;
+      x0 += glyph.width + letterSpacing;
+      j += 4;
+    }
+    return SpriteFontTextElement(
+      source: source,
+      transforms: rstTransforms,
+      rects: rects,
+      paint: paint,
+      metrics: LineMetrics(width: x0, height: scaledCharHeight, descent: 0),
+    );
+  }
+
+  Iterable<GlyphInfo> _textToGlyphs(String text) {
+    return text.codeUnits.map((int i) {
+      final glyph = _glyphs[i];
+      assert(
+        glyph != null,
+        'No glyph for character "${String.fromCharCode(i)}"',
+      );
+      return glyph!;
+    });
+  }
+}

packages/flame/lib/src/text/formatters/text_formatter.dart

@@ -0,0 +1,7 @@
+import 'package:flame/src/text/inline/text_element.dart';
+
+/// [TextFormatter] is an abstract interface for a class that can convert an
+/// arbitrary string of text into a renderable [TextElement].
+abstract class TextFormatter {
+  TextElement format(String text);
+}

packages/flame/lib/src/text/formatters/text_painter_text_formatter.dart

@@ -0,0 +1,38 @@
+import 'package:flame/src/text/formatters/text_formatter.dart';
+import 'package:flame/src/text/inline/debug_text_painter_text_element.dart';
+import 'package:flame/src/text/inline/text_painter_text_element.dart';
+import 'package:flutter/rendering.dart';
+
+/// [TextPainterTextFormatter] applies a Flutter [TextStyle] to a string of
+/// text, creating a [TextPainterTextElement].
+///
+/// If the [debugMode] is true, this formatter will wrap the text with a
+/// [DebugTextPainterTextElement] instead. This mode is mostly useful for tests.
+class TextPainterTextFormatter extends TextFormatter {
+  TextPainterTextFormatter({
+    required this.style,
+    this.textDirection = TextDirection.ltr,
+    this.debugMode = false,
+  });
+
+  final TextStyle style;
+  final TextDirection textDirection;
+  final bool debugMode;
+
+  @override
+  TextPainterTextElement format(String text) {
+    final tp = _textToTextPainter(text);
+    if (debugMode) {
+      return DebugTextPainterTextElement(tp);
+    } else {
+      return TextPainterTextElement(tp);
+    }
+  }
+
+  TextPainter _textToTextPainter(String text) {
+    return TextPainter(
+      text: TextSpan(text: text, style: style),
+      textDirection: textDirection,
+    )..layout();
+  }
+}

packages/flame/lib/src/text/inline/debug_text_painter_text_element.dart

@@ -0,0 +1,21 @@
+import 'dart:ui';
+
+import 'package:flame/src/text/inline/text_painter_text_element.dart';
+
+/// Replacement class for [TextPainterTextElement] which draws solid rectangles
+/// instead of regular text.
+///
+/// This class is useful for testing purposes: different test environments may
+/// have slightly different font definitions and mechanisms for anti-aliased
+/// font rendering, which makes it impossible to create golden tests with
+/// regular text painter.
+class DebugTextPainterTextElement extends TextPainterTextElement {
+  DebugTextPainterTextElement(super.textPainter);
+
+  final paint = Paint()..color = const Color(0xFFFFFFFF);
+
+  @override
+  void render(Canvas canvas) {
+    canvas.drawRect(metrics.toRect(), paint);
+  }
+}

packages/flame/lib/src/text/inline/sprite_font_text_element.dart

@@ -0,0 +1,42 @@
+import 'dart:typed_data';
+import 'dart:ui';
+
+import 'package:flame/src/text/common/line_metrics.dart';
+import 'package:flame/src/text/common/text_line.dart';
+import 'package:flame/src/text/inline/text_element.dart';
+
+class SpriteFontTextElement extends TextElement implements TextLine {
+  SpriteFontTextElement({
+    required this.source,
+    required this.transforms,
+    required this.rects,
+    required this.paint,
+    required LineMetrics metrics,
+  }) : _box = metrics;
+
+  final Image source;
+  final Float32List transforms;
+  final Float32List rects;
+  final Paint paint;
+  final LineMetrics _box;
+
+  @override
+  TextLine get lastLine => this;
+
+  @override
+  LineMetrics get metrics => _box;
+
+  @override
+  void translate(double dx, double dy) {
+    _box.translate(dx, dy);
+    for (var i = 0; i < transforms.length; i += 4) {
+      transforms[i + 2] += dx;
+      transforms[i + 3] += dy;
+    }
+  }
+
+  @override
+  void render(Canvas canvas) {
+    canvas.drawRawAtlas(source, transforms, rects, null, null, null, paint);
+  }
+}