ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/android/src/android/kotlin/fi/ranger/evg/RippleEffect.kt

@@ -0,0 +1,262 @@
+package fi.ranger.evg
+
+import android.graphics.RenderEffect
+import android.graphics.RuntimeShader
+import android.os.Build
+import android.util.Log
+import android.view.View
+import fi.ranger.rgr.EVGDisplayList
+
+/**
+ * `evg-surface-effect: ripple`, on Android, as an AGSL post-process.
+ *
+ * The effect is not a command in the display list and cannot be: it is a pass
+ * over the FINISHED pixels, which is why the WebGL host renders the page to a
+ * texture and then draws that texture through a fragment shader. An
+ * `android.graphics.Canvas` has no such stage — which is why this port shipped
+ * without the ripple and said so — but a `RuntimeShader` does. At API 33 the
+ * platform hands Skia's own shading language to an app, and
+ * `RenderEffect.createRuntimeShaderEffect` wires it into exactly that place:
+ * the view is rendered into a texture, the texture is bound to a named
+ * `uniform shader`, and the program below decides every pixel on screen.
+ *
+ * So the shader is a translation of `lib/evg/gl/evg-webgl.js`'s
+ * `RIPPLE_FRAG` and not a second effect that has to be kept looking like the
+ * first one. Two things are genuinely different, and both are simplifications:
+ *
+ *  * **No flips.** A GL texture's origin is the bottom left and the page's is
+ *    the top left, which cost the WebGL host two sign errors worth the comments
+ *    it now carries. A view's coordinate space runs y-down like the page, so
+ *    nothing is negated here.
+ *  * **No `dFdx`.** AGSL has no screen-space derivatives, so the height field's
+ *    gradient — which is where the glint comes from — is taken by evaluating
+ *    the wave one page pixel away and subtracting, rather than by asking the
+ *    hardware. Two extra evaluations of a loop that runs a handful of times.
+ *
+ * Below API 33 this is a no-op and the page draws exactly as it did.
+ */
+class RippleEffect(private val view: View) {
+
+    private var shader: RuntimeShader? = null
+    private var applied = false
+    /** A program that will not compile is reported once, not every frame. */
+    private var broken = false
+
+    /** True when the platform can run this at all. */
+    val available: Boolean = Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU
+
+    /**
+     * Put the current touches on screen, or take the effect off when there are
+     * none left.
+     *
+     * `list` is only read for the effect's PARAMETERS — they come off the
+     * stylesheet and are stamped onto every display list — while the drops are
+     * passed separately, because a ripple frame must not cost a rebuilt page:
+     * ageing a touch changes nothing about what was drawn.
+     *
+     * `drops` is x, y, age per touch, in page pixels and seconds, oldest first.
+     * `scale` is device pixels per page pixel and `panX` is how far the page is
+     * scrolled sideways — together they are how a page coordinate becomes a
+     * coordinate this shader is asked about.
+     */
+    fun update(list: EVGDisplayList, drops: FloatArray, count: Int, scale: Float, panX: Float) {
+        if (!available || broken) return
+        if (list.effectKind != "ripple" || count <= 0) {
+            clear()
+            return
+        }
+        val s = shaderOrNull() ?: return
+        val n = if (count > MAX_DROPS) MAX_DROPS else count
+        // The array is always the full eight: a uniform array is sized by its
+        // declaration, and handing it a short one is an argument error rather
+        // than a partial update.
+        val packed = FloatArray(MAX_DROPS * 3)
+        for (i in 0 until n) {
+            packed[i * 3] = drops[i * 3]
+            packed[i * 3 + 1] = drops[i * 3 + 1]
+            packed[i * 3 + 2] = drops[i * 3 + 2]
+        }
+        try {
+            s.setFloatUniform("uDrops", packed)
+            s.setIntUniform("uCount", n)
+            s.setFloatUniform("uScale", if (scale > 0f) scale else 1f)
+            s.setFloatUniform("uPanX", panX)
+            s.setFloatUniform("uSpeed", list.effectSpeed.toFloat())
+            s.setFloatUniform("uWidth", maxOf(list.effectWidth.toFloat(), 0.001f))
+            s.setFloatUniform("uStrength", list.effectStrength.toFloat())
+            s.setFloatUniform("uDecay", list.effectDecay.toFloat())
+            s.setFloatUniform("uHi", list.effectHighlight.toFloat())
+            s.setIntUniform("uRings", list.effectRings.toInt().coerceIn(1, MAX_RINGS))
+            s.setFloatUniform("uStagger", list.effectStagger.toFloat())
+            s.setFloatUniform("uFalloff", list.effectFalloff.toFloat())
+            s.setFloatUniform("uShine", list.effectShine.toFloat())
+            s.setFloatUniform("uGloss", maxOf(list.effectGloss.toFloat(), 1f))
+            s.setFloatUniform("uBump", list.effectBump.toFloat())
+            s.setFloatUniform(
+                "uLight",
+                list.effectLightX.toFloat(),
+                list.effectLightY.toFloat(),
+                list.effectLightZ.toFloat(),
+            )
+            view.setRenderEffect(RenderEffect.createRuntimeShaderEffect(s, "uContent"))
+            applied = true
+        } catch (e: Throwable) {
+            // A uniform this platform will not take is worth exactly one line
+            // in the log and then silence: the page is still drawn, it just is
+            // not rippling.
+            broken = true
+            clear()
+            Log.w(TAG, "ripple uniforms rejected, effect off: " + e)
+        }
+    }
+
+    /** Off, and cheaply: a view with a render effect is composited off-screen. */
+    fun clear() {
+        if (!applied) return
+        applied = false
+        view.setRenderEffect(null)
+    }
+
+    private fun shaderOrNull(): RuntimeShader? {
+        shader?.let { return it }
+        return try {
+            val s = RuntimeShader(AGSL)
+            shader = s
+            s
+        } catch (e: Throwable) {
+            broken = true
+            Log.w(TAG, "AGSL would not compile, ripple off: " + e)
+            null
+        }
+    }
+
+    private companion object {
+        const val TAG = "EvgRipple"
+
+        /**
+         * Eight touches is not a number anybody reaches by tapping; it is what
+         * a finger dragged across the surface fills in a third of a second, and
+         * the oldest is retired to make room. Five rings is one touch's train.
+         */
+        const val MAX_DROPS = 8
+        const val MAX_RINGS = 5
+
+        val AGSL = """
+uniform shader uContent;
+uniform float3 uDrops[8];   // x, y in PAGE pixels; z is seconds since the touch
+uniform int uCount;
+uniform float uScale;       // device pixels per page pixel
+uniform float uPanX;        // page pixels scrolled sideways
+uniform float uSpeed;       // page px per second the ring travels
+uniform float uWidth;       // the envelope's sigma, page px
+uniform float uStrength;    // displacement at the crest, page px
+uniform float uDecay;       // per second
+uniform float uHi;          // how much the crest lightens
+uniform int uRings;
+uniform float uStagger;     // seconds between one wavefront and the next
+uniform float uFalloff;     // what each ring behind the front is worth
+uniform float uShine;       // how strong the glint is
+uniform float uGloss;       // Blinn-Phong exponent: how tight it is
+uniform float uBump;        // what turns the height field into a slope
+uniform float3 uLight;      // where the light is, not necessarily normalised
+
+// The wave sum at one page point: the displacement as a VECTOR, the crest, and
+// the envelope. Summing the displacement rather than an amplitude is the whole
+// of the interference — two rings arriving from opposite sides push the surface
+// in opposite directions and the pixel between them stays where it was.
+float4 waveAt(float2 p) {
+    float2 push = float2(0.0, 0.0);
+    float crest = 0.0;
+    float energy = 0.0;
+    for (int i = 0; i < 8; i++) {
+        if (i >= uCount) { break; }
+        float3 drop = uDrops[i];
+        float2 delta = p - drop.xy;
+        float d = length(delta);
+        float2 dir = delta / max(d, 0.001);
+        float amp = 1.0;
+        // The TRAIN. A drop on water does not make one ring, it makes several
+        // from the same point a moment apart, each fainter than the one in
+        // front. They cost no state: the k-th is this touch aged by k staggers,
+        // and one that has not started yet has a negative age and is skipped.
+        for (int k = 0; k < 5; k++) {
+            if (k >= uRings) { break; }
+            float t = drop.z - float(k) * uStagger;
+            if (t <= 0.0) { break; }
+            float radius = t * uSpeed;
+            // A Gaussian ring: the wave only exists near the front, so the rest
+            // of the page is sampled where it was drawn and stays sharp.
+            float e = (d - radius) / uWidth;
+            float env = exp(-e * e);
+            float fade = env * exp(-t * uDecay) * amp;
+            float w = sin((d - radius) * 0.16) * fade;
+            push = push + dir * w;
+            crest = crest + w;
+            // The envelope, kept apart from the signal: it is the amplitude
+            // with the oscillation divided out, so unlike the wave itself it
+            // does not pass through zero twice per wavelength.
+            energy = energy + fade;
+            amp = amp * uFalloff;
+        }
+    }
+    return float4(push.x, push.y, crest, energy);
+}
+
+half4 main(float2 fragCoord) {
+    // Device pixels to page pixels. Both spaces run y DOWN — the flips the
+    // WebGL host needs are a GL texture's business, not a view's.
+    float2 p = float2(fragCoord.x / uScale + uPanX, fragCoord.y / uScale);
+    float4 w = waveAt(p);
+
+    // NOTHING HAPPENING HERE, AND THAT IS MOST OF THE SCREEN.
+    //
+    // A ring is a thin annulus travelling across a page that is otherwise
+    // exactly what was drawn. Answering those pixels immediately skips the two
+    // extra wave sums the glint's gradient costs and the three extra texture
+    // reads the aberration costs — the difference between an effect that costs
+    // a ring and one that costs a screen, which on a software-rendered emulator
+    // is the difference between an effect and a hang.
+    if (w.w < 0.0015 && abs(w.z) < 0.0015) {
+        return uContent.eval(fragCoord);
+    }
+
+    // Back to device pixels to sample with.
+    float2 offset = w.xy * uStrength * uScale;
+
+    // A whisper of chromatic aberration along the crest. 1.08 and 0.92 rather
+    // than anything bolder: past about a tenth the page stops looking like
+    // water and starts looking like a filter.
+    float r = uContent.eval(fragCoord + offset * 1.08).r;
+    float g = uContent.eval(fragCoord + offset).g;
+    float b = uContent.eval(fragCoord + offset * 0.92).b;
+    float a = uContent.eval(fragCoord + offset).a;
+
+    // THE SURFACE'S OWN NORMAL. The wave sum is a height field, its gradient is
+    // the slope, and the slope is the normal — so nothing has to be stored to
+    // light this that the displacement did not already need. AGSL has no
+    // dFdx/dFdy, so the gradient is a finite difference one PAGE pixel away,
+    // divided by the scale to be the per-device-pixel slope the WebGL host's
+    // derivative gives it.
+    float wx = waveAt(p + float2(1.0, 0.0)).z - w.z;
+    float wy = waveAt(p + float2(0.0, 1.0)).z - w.z;
+    float2 grad = float2(wx, wy) * uBump / max(uScale, 0.001);
+    float3 N = normalize(float3(-grad.x, -grad.y, 1.0));
+
+    // Blinn-Phong. The eye looks straight down at a flat page, so V is +Z.
+    float3 L = normalize(uLight);
+    float3 V = float3(0.0, 0.0, 1.0);
+    float3 H = normalize(L + V);
+    float spec = pow(max(dot(N, H), 0.0), uGloss) * uShine;
+
+    // The specular lives on the FLANK of a wave rather than its top, which is
+    // why the glint slides along the ring as the ring travels. It is faded out
+    // where there is no ring — by the ENVELOPE, not by the wave, which crosses
+    // zero twice per wavelength and would cut a dark seam through every glint.
+    float alive = clamp(w.w * 3.0, 0.0, 1.0);
+
+    float3 col = float3(r, g, b) + float3(w.z * uHi + spec * alive);
+    return half4(half3(col), half(a));
+}
+""".trimIndent()
+    }
+}

package/dist/lib/evg/android/src/awt/kotlin/fi/ranger/evg/AwtEvgSurface.kt

@@ -0,0 +1,238 @@
+package fi.ranger.evg
+
+import java.awt.AlphaComposite
+import java.awt.BasicStroke
+import java.awt.Color
+import java.awt.GradientPaint
+import java.awt.Graphics2D
+import java.awt.RenderingHints
+import java.awt.Shape
+import java.awt.geom.AffineTransform
+import java.awt.geom.Path2D
+import java.awt.geom.RoundRectangle2D
+import java.awt.image.BufferedImage
+import java.io.ByteArrayInputStream
+import java.io.File
+import javax.imageio.ImageIO
+
+/**
+ * The same display list, painted with Java2D.
+ *
+ * This exists so the port can be *checked*. An `android.graphics.Canvas`
+ * painter can only be run on a device or an emulator, and neither is available
+ * where this repository's tests run; Java2D is in every JDK. Both surfaces
+ * implement the same interface and are driven by the same [EvgPainter], so a
+ * page that renders correctly here is evidence about the walk, the geometry,
+ * the colours, the clip stack and the text placement — everything except the
+ * last page of platform delegation.
+ *
+ * It is also a usable desktop host in its own right: `RenderDeck` turns a
+ * `.pptx` into PNGs with it, and `CheckDashboard` does the same for the ui
+ * gallery's dashboard.
+ */
+class AwtEvgSurface(
+    private val g: Graphics2D,
+    /** The deck's own picture parts, by package path. */
+    private val images: Map<String, ByteArray>,
+    /**
+     * The faces to draw with — the SAME [AwtFaces] the measurer was installed
+     * with ([AwtTextMeasurer.install]), so what the layout measured is what
+     * is painted. The secondary constructor takes the files and makes its
+     * own, for a host that measures with the table.
+     */
+    private val faces: AwtFaces,
+) : EvgSurface {
+
+    constructor(
+        g: Graphics2D,
+        images: Map<String, ByteArray>,
+        /** TrueType files to draw with, by the family name EVG measured under. */
+        fontFiles: Map<String, File>,
+    ) : this(g, images, AwtFaces(fontFiles))
+
+    private val stack = ArrayDeque<State>()
+    private val imageCache = HashMap<String, BufferedImage?>()
+
+    private data class State(val clip: Shape?, val transform: AffineTransform)
+
+    init {
+        g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON)
+        g.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON)
+        g.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY)
+        g.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, RenderingHints.VALUE_STROKE_PURE)
+        g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR)
+    }
+
+    override fun save() {
+        stack.addLast(State(g.clip, AffineTransform(g.transform)))
+    }
+
+    override fun restore() {
+        val s = stack.removeLastOrNull() ?: return
+        g.transform = s.transform
+        g.clip = s.clip
+    }
+
+    override fun clipRect(x: Float, y: Float, w: Float, h: Float) {
+        g.clipRect(x.toInt(), y.toInt(), Math.ceil(w.toDouble()).toInt(), Math.ceil(h.toDouble()).toInt())
+    }
+
+    override fun rotate(degrees: Float, px: Float, py: Float) {
+        g.rotate(Math.toRadians(degrees.toDouble()), px.toDouble(), py.toDouble())
+    }
+
+    override fun fillRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float, color: Int, gradient: EvgGradient?, shadow: EvgShadow?,
+    ) {
+        if (w <= 0f || h <= 0f) return
+        val shape = roundRect(x, y, w, h, radius)
+        shadow?.let { paintShadow(shape, it) }
+        if (gradient != null) {
+            g.paint = if (gradient.vertical) {
+                GradientPaint(x, y, awt(gradient.color1), x, y + h, awt(gradient.color2))
+            } else {
+                GradientPaint(x, y, awt(gradient.color1), x + w, y, awt(gradient.color2))
+            }
+        } else {
+            if (alphaOf(color) == 0) return
+            g.paint = awt(color)
+        }
+        g.fill(shape)
+    }
+
+    override fun strokeRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float, thickness: Float, color: Int,
+    ) {
+        if (w <= 0f || h <= 0f) return
+        // EVG's border is a band of `thickness` kept INSIDE the box, so the
+        // stroke is centred half a thickness in from the edge.
+        val half = thickness / 2f
+        val shape = roundRect(x + half, y + half, w - thickness, h - thickness, (radius - half).coerceAtLeast(0f))
+        g.paint = awt(color)
+        g.stroke = BasicStroke(thickness, BasicStroke.CAP_BUTT, BasicStroke.JOIN_MITER)
+        g.draw(shape)
+    }
+
+    override fun fillPath(
+        pts: List<Double>, ringEnds: List<Int>, evenOdd: Boolean,
+        color: Int, shadow: EvgShadow?,
+    ) {
+        val path = buildPath(pts, ringEnds, evenOdd, close = true) ?: return
+        shadow?.let { paintShadow(path, it) }
+        g.paint = awt(color)
+        g.fill(path)
+    }
+
+    override fun strokePath(pts: List<Double>, ringEnds: List<Int>, thickness: Float, color: Int) {
+        val path = buildPath(pts, ringEnds, evenOdd = false, close = false) ?: return
+        g.paint = awt(color)
+        g.stroke = BasicStroke(thickness, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND)
+        g.draw(path)
+    }
+
+    override fun drawImage(
+        src: String, x: Float, y: Float, w: Float, h: Float,
+        radius: Float, flipH: Boolean, flipV: Boolean,
+    ) {
+        if (w <= 0f || h <= 0f) return
+        val img = imageCache.getOrPut(src) {
+            images[src]?.let { bytes -> runCatching { ImageIO.read(ByteArrayInputStream(bytes)) }.getOrNull() }
+        }
+        if (img == null) {
+            // A missing texture and an empty slide must not look the same.
+            g.paint = Color(180, 198, 230)
+            g.fill(roundRect(x, y, w, h, radius))
+            return
+        }
+        val old = g.clip
+        if (radius > 0.5f) g.clip(roundRect(x, y, w, h, radius))
+        val sx = if (flipH) -1.0 else 1.0
+        val sy = if (flipV) -1.0 else 1.0
+        val at = AffineTransform()
+        at.translate((x + if (flipH) w else 0f).toDouble(), (y + if (flipV) h else 0f).toDouble())
+        at.scale(sx * w / img.width, sy * h / img.height)
+        g.drawImage(img, at, null)
+        g.clip = old
+    }
+
+    override fun drawTextRun(
+        text: String, x: Float, top: Float, sizePx: Float,
+        family: String, bold: Boolean, italic: Boolean, color: Int,
+    ) {
+        if (sizePx <= 0f) return
+        val font = fontFor(family, sizePx, bold, italic)
+        g.font = font
+        g.paint = awt(color)
+        // `top` is the top of the line box; the baseline is one face-ascent
+        // below it. This is the same rule the WebGL atlas and the software
+        // rasteriser place a run by.
+        val baseline = top + g.fontMetrics.ascent
+        g.drawString(text, x, baseline)
+    }
+
+    // --- the parts that are only arithmetic ----------------------------------
+
+    private fun roundRect(x: Float, y: Float, w: Float, h: Float, radius: Float): Shape {
+        if (radius <= 0.5f) {
+            return java.awt.geom.Rectangle2D.Float(x, y, w, h)
+        }
+        val r = radius.coerceAtMost(minOf(w, h) / 2f) * 2f
+        return RoundRectangle2D.Float(x, y, w, h, r, r)
+    }
+
+    private fun buildPath(pts: List<Double>, ringEnds: List<Int>, evenOdd: Boolean, close: Boolean): Path2D.Float? {
+        if (pts.size < 4) return null
+        val path = Path2D.Float(if (evenOdd) Path2D.WIND_EVEN_ODD else Path2D.WIND_NON_ZERO)
+        var start = 0
+        for (end in ringEnds) {
+            val stop = end.coerceAtMost(pts.size)
+            if (stop - start < 4) { start = stop; continue }
+            path.moveTo(pts[start], pts[start + 1])
+            var i = start + 2
+            while (i + 1 < stop) {
+                path.lineTo(pts[i], pts[i + 1])
+                i += 2
+            }
+            if (close) path.closePath()
+            start = stop
+        }
+        return if (path.currentPoint == null) null else path
+    }
+
+    /**
+     * Java2D has no blur, so the soft edge is faked the way a shadow was faked
+     * before anyone had one: the silhouette drawn a few times, growing and
+     * fading. Cheap, and close enough to tell a shadowed shape from a flat one
+     * — which is all this surface is asked to prove.
+     */
+    private fun paintShadow(shape: Shape, shadow: EvgShadow) {
+        val steps = if (shadow.blur > 0.5f) 4 else 1
+        val old = g.composite
+        val at = AffineTransform.getTranslateInstance(shadow.dx.toDouble(), shadow.dy.toDouble())
+        val moved = at.createTransformedShape(shape)
+        val base = alphaOf(shadow.color) / 255f
+        for (s in 0 until steps) {
+            val grow = shadow.blur * s / steps
+            val a = base * (1f - s.toFloat() / steps) / steps * 2f
+            g.composite = AlphaComposite.getInstance(AlphaComposite.SRC_OVER, a.coerceIn(0f, 1f))
+            g.paint = Color(shadow.color and 0xFFFFFF, false)
+            if (grow <= 0f) {
+                g.fill(moved)
+            } else {
+                g.stroke = BasicStroke(grow * 2f, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND)
+                g.fill(moved)
+                g.draw(moved)
+            }
+        }
+        g.composite = old
+    }
+
+    private fun fontFor(family: String, sizePx: Float, bold: Boolean, italic: Boolean): Font =
+        faces.font(family, sizePx, bold, italic)
+
+    private fun awt(argb: Int): Color = Color(argb, true)
+
+    private fun alphaOf(argb: Int): Int = (argb ushr 24) and 0xFF
+}

package/dist/lib/evg/android/src/awt/kotlin/fi/ranger/evg/AwtTextMeasurer.kt

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+package fi.ranger.evg
+
+import fi.ranger.rgr.EVGDefaultMeasurer
+import fi.ranger.rgr.EVGHostTextMeasurer
+import java.awt.Font
+import java.awt.font.FontRenderContext
+import java.io.File
+
+/**
+ * The faces a Java2D host draws with, resolved ONE way.
+ *
+ * [AwtEvgSurface] used to resolve a family to a `Font` privately, per
+ * surface — and a surface is made per `Graphics2D`, so per frame. With a
+ * measurer that has to resolve the same family to the same face without a
+ * `Graphics2D` in hand, the resolution moves here and both ask it: a family
+ * named in [fontFiles] is that file, anything else is the first file or the
+ * JDK's sans, and bold and italic are derived styles of it. Whatever the
+ * rule is, there is one of it.
+ */
+class AwtFaces(fontFiles: Map<String, File>) {
+
+    private data class FontKey(val family: String, val size: Int, val bold: Boolean, val italic: Boolean)
+
+    private val fontCache = HashMap<FontKey, Font>()
+    private val baseFonts = HashMap<String, Font>()
+    private var fallback: Font = Font(Font.SANS_SERIF, Font.PLAIN, 12)
+
+    init {
+        for ((family, file) in fontFiles) {
+            val f = runCatching { Font.createFont(Font.TRUETYPE_FONT, file) }.getOrNull() ?: continue
+            baseFonts[family.lowercase()] = f
+            if (baseFonts.size == 1) fallback = f
+        }
+    }
+
+    fun font(family: String, sizePx: Float, bold: Boolean, italic: Boolean): Font {
+        val key = FontKey(family.lowercase(), Math.round(sizePx * 4), bold, italic)
+        synchronized(fontCache) {
+            return fontCache.getOrPut(key) {
+                val base = baseFonts[family.lowercase()] ?: fallback
+                var style = Font.PLAIN
+                if (bold) style = style or Font.BOLD
+                if (italic) style = style or Font.ITALIC
+                base.deriveFont(style, sizePx)
+            }
+        }
+    }
+}
+
+/**
+ * Java2D measures, EVG breaks the lines — the desktop twin of
+ * [AndroidTextMeasurer], for the same reason [AwtEvgSurface] is the twin of
+ * [AndroidEvgSurface]: so the port can be CHECKED where there is no device.
+ * A check that lays out with the table and paints with Java2D is asserting
+ * about two faces; with this installed it asserts about one.
+ *
+ * Widths come from `Font.getStringBounds` with a fractional-metrics render
+ * context, which is the advance Java2D lays the string out to when the
+ * surface's anti-aliasing hints are on; the vertical numbers from
+ * `getLineMetrics`, which is the face's, not the string's.
+ */
+object AwtTextMeasurer {
+
+    /**
+     * Make the measurer, attach Java2D to it through [faces] and make it the
+     * default every `EVGLayout` and `EVGTextEngine` in the process starts
+     * from. Hand the SAME [AwtFaces] to every [AwtEvgSurface] the check makes.
+     */
+    fun install(faces: AwtFaces): EVGHostTextMeasurer {
+        val frc = FontRenderContext(null, true, true)
+        val measurer = EVGHostTextMeasurer()
+        measurer.attach({ kind, text, family, size, bold, italic ->
+            val font = faces.font(family, size.toFloat(), bold, italic)
+            when (kind) {
+                0 -> if (text.isEmpty()) 0.0 else font.getStringBounds(text, frc).width
+                1 -> font.getLineMetrics("Hg", frc).ascent.toDouble()
+                2 -> font.getLineMetrics("Hg", frc).descent.toDouble()
+                else -> font.getLineMetrics("Hg", frc).leading.toDouble()
+            }
+        }, "awt")
+        EVGDefaultMeasurer.install(measurer)
+        return measurer
+    }
+}