@pictor-sdk/video-android 0.1.0

package/android/src/main/java/dev/pictor/video/SkiaPassThroughEffect.kt

@@ -0,0 +1,695 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.opengl.EGL14
+import android.opengl.GLES20
+import androidx.media3.common.VideoFrameProcessingException
+import androidx.media3.common.util.GlProgram
+import androidx.media3.common.util.Size
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.BaseGlShaderProgram
+import androidx.media3.effect.GlEffect
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * The gate's effect: a pass-through that proves the boundary is usable.
+ *
+ * Transformer owns the decode, the timing, the encode and the mux. This sits in
+ * the middle of its video chain and must come out the other side with the
+ * picture unchanged — which is what makes it a *gate* rather than a feature: any
+ * difference beyond the codec's own noise is this code's fault, and there is
+ * nowhere else for it to come from.
+ *
+ * ## Borrowed, never owned
+ *
+ * The input texture and the output framebuffer belong to Transformer. Nothing
+ * here deletes or retains either beyond the callback: `drawFrame` reads the
+ * input texture id and writes to whatever framebuffer
+ * [BaseGlShaderProgram] has bound, and holds neither afterwards. The only
+ * objects this class owns are its own [GlProgram] and its own instrumentation,
+ * and those are released exactly once, on the thread that made them.
+ *
+ * ## GL state is restored
+ *
+ * Transformer's chain expects the state it left. Viewport, blend, the bound
+ * texture and the active unit are captured on entry and put back on exit — a
+ * chain that draws correctly and leaves blending enabled corrupts whatever runs
+ * after it, and the failure appears in someone else's effect.
+ *
+ * ## It executes a scene, when given one
+ *
+ * With a [SceneProgram] it performs the scene's `clear` and then its identity
+ * `video` command. Without one it is the bare blit that established the frozen
+ * codec control — the two must produce identical pixels for an identity scene,
+ * which is exactly the gate.
+ *
+ * ## Not yet Skia
+ *
+ * This is the first half of the V3.3 gate. It establishes that the hook works,
+ * that presentation timestamps carry through untouched, that the expected EGL
+ * context is current on the frame-processing thread, and that release happens
+ * once — before a second Skia context is introduced into the same thread.
+ * Skia's draw replaces the blit below; everything around it is what has to be
+ * true either way.
+ */
+@UnstableApi
+internal class SkiaPassThroughEffect(
+    private val program: SceneProgram? = null,
+    /**
+     * Fail deliberately, to prove cleanup.
+     *
+     * `-1` never fails. `0` fails after GL initialisation and before the first
+     * frame — the window where a program exists and nothing has drawn, which is
+     * the leak a naive teardown misses. A positive number fails after that many
+     * frames, mid-run, with an encoder and a muxer already holding state.
+     */
+    private val failAfterFrames: Int = -1,
+    /** A compiled program, selected per frame by presentation timestamp. */
+    private val sceneProgram: SceneProgramNative? = null,
+    /**
+     * Where this shard sits on the timeline, compiled in TypeScript.
+     *
+     * Native's whole contribution to placement is one addition. The offset is
+     * the accumulated length of everything before this clip, and accumulating it
+     * is exactly the arithmetic that must not exist twice.
+     */
+    private val timelineOffsetUs: Long = 0,
+    /** Rasters, already loaded and checked before Transformer started. */
+    private val overlayResources: OverlayResources? = null,
+    /**
+     * Fail during overlay drawing, after N draws.
+     *
+     * `0` fails on the first draw — after the texture exists but before anything
+     * has used it, which is the window where an upload could leak. A positive
+     * number fails mid-sequence with textures bound and a partial frame drawn.
+     */
+    private val overlayFailAfterDraws: Int = -1,
+) : GlEffect {
+
+    val overlayUploads = AtomicLong(0)
+    val overlayDraws = AtomicLong(0)
+    val overlayTexturesFreed = AtomicLong(0)
+    private val shaderPrograms = AtomicLong(0)
+    private val frames = AtomicLong(0)
+    private val releases = AtomicLong(0)
+    private val timestamps = StringBuilder()
+    private val glErrorCodes = mutableSetOf<Int>()
+    /** The EGL context seen on the frame-processing thread, as a handle. */
+    @Volatile private var contextHandle: Long = 0
+    /** The thread the frame processor called us on. */
+    @Volatile private var threadId: Long = 0
+    @Volatile private var threadName: String = ""
+    @Volatile private var threadChanges: Int = 0
+    @Volatile private var contextChanges: Int = 0
+    /** Distinct segments the program selected, and when each was first entered. */
+    private val segmentsSeen = mutableSetOf<Int>()
+    private val transitions = mutableListOf<String>()
+    @Volatile private var shader: PassThroughProgram? = null
+
+    fun frameCount(): Long = frames.get()
+
+    fun releaseCount(): Long = releases.get()
+
+    /** Every distinct `glGetError` seen. Empty means the chain stayed clean. */
+    fun glErrors(): String = synchronized(glErrorCodes) { glErrorCodes.joinToString(",") }
+
+    /** Presentation timestamps, in order, as the effect received them. */
+    fun timestamps(): String = synchronized(timestamps) { timestamps.toString() }
+
+    /** Times the current EGL context changed under the effect. Must stay 0. */
+    fun contextChangeCount(): Int = contextChanges
+
+    /** GL programs created and deleted, and the thread each happened on. */
+    fun programTrace(): String = synchronized(segmentsSeen) {
+        "segments=" + segmentsSeen.sorted().joinToString("/") +
+            " enteredAt=" + transitions.joinToString(",")
+    }
+
+    fun lifecycle(): String =
+        "created=${glCreated.get()} deleted=${glDeleted.get()} " +
+            "createThread=$createThread deleteThread=$deleteThread"
+
+    private val glCreated = AtomicLong(0)
+    private val glDeleted = AtomicLong(0)
+    @Volatile private var createThread: Long = 0
+    @Volatile private var deleteThread: Long = 0
+
+    /**
+     * Who Transformer ran the effect on, and in which GL context.
+     *
+     * The invocation-boundary question turns on this: if the composition lives
+     * on another thread with another EGL context, then handing it this frame is
+     * a cross-context transfer with a synchronisation problem, not a function
+     * call.
+     */
+    fun boundary(): String =
+        "ctx=$contextHandle thread=$threadId/$threadName ctxChanges=$contextChanges threadChanges=$threadChanges"
+
+    override fun toGlShaderProgram(context: Context, useHdr: Boolean): BaseGlShaderProgram {
+        val made = PassThroughProgram(useHdr)
+        shader = made
+        shaderPrograms.incrementAndGet()
+        return made
+    }
+
+    /**
+     * Release the effect's own instrumentation.
+     *
+     * The shader program is released by Transformer, on the frame-processing
+     * thread, through `BaseGlShaderProgram.release`. Releasing it from here as
+     * well would be a second release on the wrong thread, which is the failure
+     * this counter exists to catch.
+     */
+    fun release() {
+        releases.incrementAndGet()
+    }
+
+    private inner class PassThroughProgram(useHdr: Boolean) : BaseGlShaderProgram(useHdr, 1) {
+        private var glProgram: GlProgram? = null
+        private var released = false
+        private var outputWidth = 0
+        private var outputHeight = 0
+        private var projectWidth = 0
+        private var projectHeight = 0
+
+        /** Reused, so a per-frame transform allocates nothing. */
+        private val matrixScratch = floatArrayOf(1f, 0f, 0f, 1f, 0f, 0f)
+        private var opacity = 1f
+        private var segmentIndex = -1
+
+        /**
+         * One texture per resource, uploaded on first use and reused after.
+         *
+         * Not per frame: a large raster re-uploaded 300 times is 300 transfers
+         * of bytes that never changed. Freed in [release], which Transformer
+         * calls on the thread that created them.
+         */
+        private val overlayTextures = HashMap<String, Int>()
+        private var overlayProgram: GlProgram? = null
+
+        override fun configure(inputWidth: Int, inputHeight: Int): Size {
+            // Project size, from the scene. The conversion below needs the space
+            // the matrix was written in, not the one it is rendered into.
+            projectWidth = sceneProgram?.projectWidth ?: program?.projectWidth ?: inputWidth
+            projectHeight = sceneProgram?.projectHeight ?: program?.projectHeight ?: inputHeight
+            /*
+              The output is the **project's** size, not this input's.
+
+              Each clip is encoded in its own pass and the parts are then
+              concatenated by copying samples, which writes every part's payload
+              under the *first* part's track format. A shard that sized its
+              output to its own source therefore produced a different
+              elementary stream — measured on a 540x960 clip beside two
+              1080x1920 ones: `960x540, level 512, csd-0 22 bytes` copied under
+              `1920x1080, level 2048, csd-0 23 bytes`. A decoder configured from
+              the declared codec-specific data cannot correctly decode those
+              samples, and the finished file reports one format for everything
+              inside it, so nothing downstream can notice.
+
+              Every shard must therefore agree on one output format, and the
+              project is the only thing that defines it. Sampling still uses the
+              input texture at whatever size it arrived — the video quad spans
+              the output and reads the texture across its whole extent, so a
+              smaller source is scaled up here rather than encoded small and
+              reinterpreted later.
+
+              Scene matrices and overlay quads are unaffected: both are in
+              project space and converted to clip space, which is what makes
+              this change a format decision rather than a geometry one.
+            */
+            outputWidth = projectWidth
+            outputHeight = projectHeight
+            // GL initialisation, eagerly, so "after init and before the first
+            // frame" is a window that actually exists to fail in.
+            if (glProgram == null) {
+                glProgram = makeProgram()
+                glCreated.incrementAndGet()
+                createThread = Thread.currentThread().id
+            }
+            return Size(outputWidth, outputHeight)
+        }
+
+        override fun drawFrame(inputTexId: Int, presentationTimeUs: Long) {
+            if (failAfterFrames >= 0 && frames.get() >= failAfterFrames) {
+                throw VideoFrameProcessingException(
+                    RuntimeException("injected failure at frame ${'$'}{frames.get()}"),
+                )
+            }
+            recordContext()
+            recordTimestamp(presentationTimeUs)
+
+            // Captured, then restored below. Transformer's chain expects the
+            // state it left.
+            val savedViewport = IntArray(4)
+            GLES20.glGetIntegerv(GLES20.GL_VIEWPORT, savedViewport, 0)
+            val savedActive = IntArray(1)
+            GLES20.glGetIntegerv(GLES20.GL_ACTIVE_TEXTURE, savedActive, 0)
+            val blendWasOn = GLES20.glIsEnabled(GLES20.GL_BLEND)
+
+            try {
+                /*
+                  The scene's `clear`, executed rather than assumed redundant.
+
+                  An identity video covers the output, so the clear is invisible
+                  here — and it is still performed, because whether coverage
+                  holds is not this interpreter's judgement to make. When a
+                  transform or a partial opacity arrives it will be the only
+                  thing standing between a fade and the previous frame.
+                */
+                /*
+                  A program selects per frame; a single scene applies to all of
+                  them. Selection is a binary search over the compiled intervals
+                  — native learns which interval this timestamp falls in and
+                  nothing else about the timeline.
+                */
+                val compiled = sceneProgram
+                if (compiled != null) {
+                    val index = compiled.segmentAt(timelineOffsetUs + presentationTimeUs)
+                    if (index < 0) {
+                        throw VideoFrameProcessingException(
+                            RuntimeException("no segment covers " + presentationTimeUs),
+                        )
+                    }
+                    /*
+                      The segment's first timestamp is recorded; its window is
+                      not checked against a decoder.
+
+                      There is no per-frame window signal in this path.
+                      `FrameClock.windowIndex` belongs to the **preview**
+                      player, and Transformer's effect receives a presentation
+                      timestamp and nothing else — comparing the two produced a
+                      confident false failure at the seam, from a counter
+                      another pipeline had left behind. Deriving the window from
+                      the timestamp instead would be timeline arithmetic in
+                      native, which is the thing this design exists to avoid.
+
+                      What *is* observable is which segment each timestamp
+                      selected, so the transitions are recorded and checked
+                      against the program's own boundaries by the caller.
+                    */
+                    synchronized(segmentsSeen) {
+                        if (segmentsSeen.add(index)) {
+                            transitions.add(index.toString() + "@" + (timelineOffsetUs + presentationTimeUs))
+                        }
+                    }
+                    compiled.matrixAt(index, matrixScratch)
+                    opacity = compiled.opacityAt(index)
+                    segmentIndex = index
+                    val c = compiled.clearColorAt(index)
+                    GLES20.glClearColor(
+                        ((c shr 16) and 0xff) / 255f,
+                        ((c shr 8) and 0xff) / 255f,
+                        (c and 0xff) / 255f,
+                        ((c ushr 24) and 0xff) / 255f,
+                    )
+                    GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT)
+                }
+                val scene = program
+                if (scene != null) {
+                    opacity = 1f
+                    matrixScratch[0] = 1f
+                    matrixScratch[1] = 0f
+                    matrixScratch[2] = 0f
+                    matrixScratch[3] = 1f
+                    matrixScratch[4] = 0f
+                    matrixScratch[5] = 0f
+                    val c = scene.clearColor
+                    GLES20.glClearColor(
+                        ((c shr 16) and 0xff) / 255f,
+                        ((c shr 8) and 0xff) / 255f,
+                        (c and 0xff) / 255f,
+                        ((c ushr 24) and 0xff) / 255f,
+                    )
+                    GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT)
+                }
+                val prog = glProgram ?: makeProgram().also { glProgram = it }
+                prog.use()
+                prog.setSamplerTexIdUniform("uTexSampler", inputTexId, 0)
+                prog.setFloatsUniform("uTransform", clipSpaceTransform())
+                prog.setFloatUniform("uOpacity", opacity)
+                prog.setFloatUniform("uUseAttrCoord", 0f)
+                prog.setFloatUniform("uPremultiplied", 0f)
+                prog.setBufferAttribute("aTexCoord", OVERLAY_TEX_COORDS, 2)
+                /*
+                  Source-over, onto the clear the scene already drew.
+
+                  The order is the rule: background first, then the transformed
+                  video at the clip's opacity. A partly transparent clip reveals
+                  that background — the file stays opaque and never becomes an
+                  alpha video.
+
+                  Blending is left off at full opacity. `1·src + 0·dst` is src, so
+                  it would be a no-op arithmetically, and skipping it keeps the
+                  established max-delta-0 floor a property of the same code path
+                  rather than of a rounding mode.
+                */
+                val blending = opacity < 1f
+                if (blending) {
+                    GLES20.glEnable(GLES20.GL_BLEND)
+                    GLES20.glBlendFunc(GLES20.GL_SRC_ALPHA, GLES20.GL_ONE_MINUS_SRC_ALPHA)
+                } else {
+                    GLES20.glDisable(GLES20.GL_BLEND)
+                }
+                prog.bindAttributesAndUniforms()
+                GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4)
+                drawOverlays()
+            } catch (e: Exception) {
+                throw VideoFrameProcessingException(e)
+            } finally {
+                if (blendWasOn) GLES20.glEnable(GLES20.GL_BLEND) else GLES20.glDisable(GLES20.GL_BLEND)
+                GLES20.glActiveTexture(savedActive[0])
+                GLES20.glViewport(savedViewport[0], savedViewport[1], savedViewport[2], savedViewport[3])
+                recordGlError()
+            }
+            frames.incrementAndGet()
+        }
+
+        override fun release() {
+            // Once, on the thread Transformer calls it on — which is the thread
+            // the program was made on.
+            if (released) return
+            released = true
+            if (overlayTextures.isNotEmpty()) {
+                val ids = overlayTextures.values.toIntArray()
+                runCatching { GLES20.glDeleteTextures(ids.size, ids, 0) }
+                overlayTexturesFreed.addAndGet(ids.size.toLong())
+                overlayTextures.clear()
+            }
+            runCatching { overlayProgram?.delete() }
+            overlayProgram = null
+            runCatching { glProgram?.delete() }
+            if (glProgram != null) {
+                glDeleted.incrementAndGet()
+                deleteThread = Thread.currentThread().id
+            }
+            glProgram = null
+            super.release()
+        }
+
+        /**
+         * The scene matrix, converted to clip space. The only conversion applied.
+         *
+         * `resolveVideoScene` emits an affine over normalised project
+         * coordinates, and preview applies it in output pixels as
+         * `translate(tx·W, ty·H) · translate(W/2, H/2) · L · translate(-W/2, -H/2)`.
+         * Clip space is square and pixels are not, so the off-diagonal terms
+         * carry the aspect ratio — without it a rotation would shear on a
+         * non-square output, and would still look plausible on a square one.
+         *
+         * The matrix already carries the box's anchor, so it is applied and
+         * **not centred again** — the surplus `(I − L)·centre` is what displaced
+         * a 0.55 scale by a half-extent and pushed a flip off the canvas.
+         *
+         * The terms below depend only on the **project** size. Output size
+         * cancels out of the conversion, which is the arithmetic saying the two
+         * spaces agree: a scene means the same thing whatever it is rendered
+         * into.
+         *
+         * Nothing else is applied here. The source's own orientation was settled
+         * upstream by Media3's frame processor, which is what keeps it innermost
+         * and this matrix outermost, exactly as preview orders them.
+         *
+         * Column-major, as GLSL wants it.
+         */
+        private fun clipSpaceTransform(): FloatArray {
+            val m = matrixScratch
+            val w = projectWidth.toFloat()
+            val h = projectHeight.toFloat()
+            if (w <= 0f || h <= 0f) return IDENTITY_MAT3
+            val a = m[0]
+            val b = m[1]
+            val c = m[2]
+            val d = m[3]
+            val tx = m[4]
+            val ty = m[5]
+            /*
+              Clip space is [-1, 1] with y up; project space is [0, size] with y
+              down. Both the scale and the origin shift, so the constant term is
+              not simply the translation: it also carries what the linear part
+              does to the corner the two spaces disagree about.
+
+              An earlier version used `2·tx/Wp` alone, which is the constant only
+              when the matrix is expressed as an offset from the centre. Under the
+              canonical convention `tx` is an absolute project coordinate, and
+              that shortcut put a 0.25 scale at 405..540 instead of 202..337 —
+              exactly twice the offset, the same failure the convention was
+              corrected to remove.
+            */
+            val ax = c * (h / w)
+            val by = b * (w / h)
+            val cx = a + ax + 2f * tx / w - 1f
+            val cy = 1f - by - d - 2f * ty / h
+            // x' =  a·x − ax·y + cx
+            // y' = −by·x +  d·y + cy
+            return floatArrayOf(
+                a, -by, 0f,
+                -ax, d, 0f,
+                cx, cy, 1f,
+            )
+        }
+
+        /**
+         * Overlays, after the video and in the resolver's z order.
+         *
+         * Placement mirrors preview exactly: the scene matrix positions the
+         * overlay's **centre**, and the measured half-extent that arrived with
+         * the resource turns that into a box. The four corners are computed in
+         * project units and converted to clip space directly — a quad needs no
+         * matrix conversion, and deriving one would be a second place for the
+         * aspect terms to disagree.
+         */
+        /** Deduplicates the trace above: one line per fact, not per frame. */
+        private val overlayTrace = java.util.Collections.synchronizedSet(HashSet<String>())
+
+        private fun drawOverlays() {
+            val compiled = sceneProgram ?: return
+            val resources = overlayResources
+            if (segmentIndex < 0) return
+            /*
+              One line per distinct segment, and per segment-and-overlay.
+
+              An overlay that does not appear has three possible explanations —
+              the segment carried no command, the command was carried but the
+              resource was absent, or it was drawn to a quad nobody can see —
+              and from outside the encoder they are indistinguishable. This
+              separates them at the only place that knows.
+            */
+            val draws = if (resources == null) emptyList() else compiled.overlaysAt(segmentIndex)
+            if (overlayTrace.add("seg$segmentIndex")) {
+                android.util.Log.i(
+                    "PictorOverlay",
+                    "segment=" + segmentIndex + " offsetUs=" + timelineOffsetUs +
+                        " resources=" + (resources != null) +
+                        " commands=" + (if (resources == null) -1 else compiled.overlaysAt(segmentIndex).size),
+                )
+            }
+            if (draws.isEmpty()) return
+            // Narrowed after the trace above, which is the only thing that
+            // needed to observe the null case.
+            val res = resources ?: return
+
+            val program = overlayProgram ?: GlProgram(VERTEX_SHADER, FRAGMENT_SHADER).also {
+                overlayProgram = it
+            }
+            val pw = projectWidth.toFloat()
+            val ph = projectHeight.toFloat()
+            GLES20.glEnable(GLES20.GL_BLEND)
+            for (draw in draws) {
+                val entry = res.entries[draw.resourceId] ?: throw VideoFrameProcessingException(
+                    RuntimeException("overlay resource '" + draw.resourceId + "' was not preloaded"),
+                )
+                val texId = overlayTextures.getOrPut(draw.resourceId) { upload(entry) }
+                if (overlayFailAfterDraws >= 0 && overlayDraws.get() >= overlayFailAfterDraws) {
+                    throw VideoFrameProcessingException(
+                        RuntimeException("injected overlay failure after " + overlayDraws.get() + " draws"),
+                    )
+                }
+                overlayDraws.incrementAndGet()
+                /*
+                  The blend function follows what the producer declared.
+
+                  Straight and premultiplied describe the same picture with
+                  different stored numbers, and using one function on the other's
+                  bytes darkens or haloes every antialiased edge — subtly enough
+                  to look like a font-rendering difference rather than a bug.
+                */
+                if (entry.premultiplied) {
+                    GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ONE_MINUS_SRC_ALPHA)
+                } else {
+                    GLES20.glBlendFunc(GLES20.GL_SRC_ALPHA, GLES20.GL_ONE_MINUS_SRC_ALPHA)
+                }
+                val m = draw.matrix
+                // Anchored on the logical size, laid out over the visual bounds.
+                val halfW = entry.projectWidth / 2f
+                val halfH = entry.projectHeight / 2f
+                val x0 = entry.boundsX - halfW
+                val y0 = entry.boundsY - halfH
+                val x1 = x0 + entry.boundsWidth
+                val y1 = y0 + entry.boundsHeight
+                val local = floatArrayOf(x0, y0, x1, y0, x0, y1, x1, y1)
+                val quad = FloatArray(8)
+                for (k in 0 until 4) {
+                    val lx = local[k * 2]
+                    val ly = local[k * 2 + 1]
+                    val px = m[0] * lx + m[2] * ly + m[4]
+                    val py = m[1] * lx + m[3] * ly + m[5]
+                    quad[k * 2] = 2f * px / pw - 1f
+                    quad[k * 2 + 1] = 1f - 2f * py / ph
+                }
+                if (overlayTrace.add("seg" + segmentIndex + ":" + draw.resourceId)) {
+                    android.util.Log.i(
+                        "PictorOverlay",
+                        "draw segment=" + segmentIndex + " id=" + draw.overlayId +
+                            " quad=[" + quad[0] + "," + quad[1] + " " + quad[6] + "," + quad[7] + "]" +
+                            " logical=" + entry.projectWidth + "x" + entry.projectHeight +
+                            " bounds=" + entry.boundsX + "," + entry.boundsY + "," +
+                            entry.boundsWidth + "x" + entry.boundsHeight +
+                            " project=" + pw + "x" + ph,
+                    )
+                }
+                program.use()
+                program.setBufferAttribute("aFramePosition", quad, 2)
+                program.setBufferAttribute("aTexCoord", OVERLAY_TEX_COORDS, 2)
+                program.setSamplerTexIdUniform("uTexSampler", texId, 0)
+                program.setFloatsUniform("uTransform", IDENTITY_MAT3)
+                program.setFloatUniform("uOpacity", draw.opacity)
+                program.setFloatUniform("uUseAttrCoord", 1f)
+                program.setFloatUniform("uPremultiplied", if (entry.premultiplied) 1f else 0f)
+                program.bindAttributesAndUniforms()
+                GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4)
+            }
+        }
+
+        private fun upload(entry: OverlayResources.Entry): Int {
+            val ids = IntArray(1)
+            GLES20.glGenTextures(1, ids, 0)
+            GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, ids[0])
+            GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR)
+            GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR)
+            GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE)
+            GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE)
+            val buffer = java.nio.ByteBuffer.allocateDirect(entry.pixels.size)
+                .order(java.nio.ByteOrder.nativeOrder())
+            buffer.put(entry.pixels)
+            buffer.position(0)
+            GLES20.glTexImage2D(
+                GLES20.GL_TEXTURE_2D, 0, GLES20.GL_RGBA,
+                entry.rasterWidth, entry.rasterHeight, 0,
+                GLES20.GL_RGBA, GLES20.GL_UNSIGNED_BYTE, buffer,
+            )
+            overlayUploads.incrementAndGet()
+            return ids[0]
+        }
+
+        private fun makeProgram(): GlProgram {
+            val program = GlProgram(VERTEX_SHADER, FRAGMENT_SHADER)
+            program.setBufferAttribute(
+                "aFramePosition",
+                floatArrayOf(-1f, -1f, 1f, -1f, -1f, 1f, 1f, 1f),
+                2,
+            )
+            return program
+        }
+    }
+
+    private fun recordContext() {
+        val current = Thread.currentThread()
+        if (threadId == 0L) {
+            threadId = current.id
+            threadName = current.name
+        } else if (threadId != current.id) {
+            threadChanges += 1
+            threadId = current.id
+            threadName = current.name
+        }
+        val handle = EGL14.eglGetCurrentContext().nativeHandle
+        if (contextHandle == 0L) {
+            contextHandle = handle
+        } else if (contextHandle != handle) {
+            // The frame processor is documented to run on one thread with one
+            // context. If that stops being true, every assumption about who owns
+            // what goes with it — so it is counted rather than assumed.
+            contextChanges += 1
+            contextHandle = handle
+        }
+    }
+
+    private fun recordTimestamp(us: Long) {
+        synchronized(timestamps) {
+            if (timestamps.isNotEmpty()) timestamps.append(',')
+            timestamps.append(us)
+        }
+    }
+
+    private fun recordGlError() {
+        var code = GLES20.glGetError()
+        while (code != GLES20.GL_NO_ERROR) {
+            synchronized(glErrorCodes) { glErrorCodes.add(code) }
+            code = GLES20.glGetError()
+        }
+    }
+
+    private companion object {
+        val IDENTITY_MAT3 = floatArrayOf(1f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 1f)
+
+        /**
+         * TL, TR, BL, BR — matching the order the overlay quad is built in.
+         *
+         * `v = 0` at the top: a raster's first row is its top row, and the
+         * corner it belongs with is the one at project `y = 0`. Getting this
+         * backwards gives a vertically mirrored overlay that is otherwise
+         * perfectly placed, which is why the gate's synthetic pattern has four
+         * differently coloured quadrants.
+         */
+        val OVERLAY_TEX_COORDS = floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f)
+
+        const val VERTEX_SHADER = """
+            attribute vec4 aFramePosition;
+            attribute vec2 aTexCoord;
+            uniform mat3 uTransform;
+            uniform highp float uUseAttrCoord;
+            uniform highp float uPremultiplied;
+            varying vec2 vTexCoord;
+            void main() {
+              // The texture coordinate stays with the *original* corner, so the
+              // quad moves and the sampling does not. Pixels the quad no longer
+              // covers keep the clear colour instead of stale texture.
+              vTexCoord = mix(aFramePosition.xy * 0.5 + 0.5, aTexCoord, uUseAttrCoord);
+              vec3 p = uTransform * vec3(aFramePosition.xy, 1.0);
+              gl_Position = vec4(p.xy, 0.0, 1.0);
+            }
+        """
+
+        const val FRAGMENT_SHADER = """
+            precision mediump float;
+            uniform sampler2D uTexSampler;
+            uniform float uOpacity;
+            // Declared in both stages, and explicitly `highp` in both: a
+            // uniform is per-program, and a vertex `float` defaults to highp
+            // while a fragment one here would be mediump. The link then fails
+            // with "the precision does not match" rather than anything about
+            // the variable being undeclared.
+            uniform highp float uUseAttrCoord;
+            uniform highp float uPremultiplied;
+            varying vec2 vTexCoord;
+            void main() {
+              /*
+                Straight alpha, paired with SRC_ALPHA/ONE_MINUS_SRC_ALPHA.
+
+                Video carries no per-pixel alpha, so the clip's opacity is the
+                whole of it and the texture's own channel is ignored -- which
+                keeps that path bit-identical to before overlays existed. An
+                overlay raster is the opposite: its shape *is* its alpha, and
+                discarding it drew a solid rectangle where a soft one belonged.
+                `uUseAttrCoord` already distinguishes the two.
+              */
+              vec4 c = texture2D(uTexSampler, vTexCoord);
+              float a = mix(uOpacity, c.a * uOpacity, uUseAttrCoord);
+              // Premultiplied colour must be scaled by the same opacity its
+              // alpha is, or a faded overlay brightens instead of fading.
+              vec3 rgb = mix(c.rgb, c.rgb * uOpacity, uPremultiplied);
+              gl_FragColor = vec4(rgb, a);
+            }
+        """
+    }
+}