@pickleball/rtmp-native 0.1.0 → 0.2.0

package/android/src/main/java/expo/modules/pickleballrtmp/GlCompositor.kt

@@ -0,0 +1,755 @@
+package expo.modules.pickleballrtmp
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.Movie
+import android.graphics.Paint
+import android.graphics.PorterDuff
+import android.graphics.RectF
+import android.graphics.SurfaceTexture
+import android.graphics.Typeface
+import android.media.MediaPlayer
+import android.opengl.EGL14
+import android.opengl.EGLConfig
+import android.opengl.EGLContext
+import android.opengl.EGLDisplay
+import android.opengl.EGLExt
+import android.opengl.EGLSurface
+import android.opengl.GLES11Ext
+import android.opengl.GLES20
+import android.opengl.GLUtils
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.SystemClock
+import android.view.Surface
+import java.io.File
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.FloatBuffer
+import java.util.concurrent.CountDownLatch
+
+/**
+ * Pass GL chen giữa Camera2 và encoder — CHỈ tồn tại khi giải có overlay.
+ *
+ *   Camera2 ──addTarget──▶ Surface(SurfaceTexture OES)
+ *                              │ onFrameAvailable (nhịp = camera, ~30fps)
+ *                              ▼
+ *                        GlCompositor (EGL riêng, 1 render thread)
+ *                          camera quad + từng lớp overlay theo thứ tự
+ *                              ├─▶ EGLSurface(encoder input)   (+presentation time)
+ *                              └─▶ EGLSurface(preview view)    (nếu có)
+ *
+ * Không có overlay thì module đi đường addTarget thẳng như kiến trúc 08/08 —
+ * pass này là opt-in, không phải hồi sinh tầng GL cũ. Hai bài học từ tầng cũ
+ * được khắc ở đây:
+ *  · GL_LINEAR cho MỌI texture (GL_NEAREST là lý do tầng cũ bị gỡ — răng cưa);
+ *  · blend GL_ONE / GL_ONE_MINUS_SRC_ALPHA vì Bitmap Android decode
+ *    PREMULTIPLIED — dùng GL_SRC_ALPHA là viền đen quanh mép trong suốt.
+ *
+ * Timestamp: lấy từ SurfaceTexture của camera và đóng qua
+ * eglPresentationTimeANDROID — encoder KHÔNG được tự đóng dấu (VFR loạn nhịp).
+ *
+ * GIF đi đường Movie (deprecated nhưng vẫn sống ở API 35): mình tự cầm đồng hồ
+ * (setTime theo elapsed % duration) nên nhịp khung tất định như GifSource bên
+ * iOS, RAM O(1 khung). Movie chết ở Android nào đó thì lớp đó rơi riêng —
+ * animation là trang trí, không được đụng đường phát.
+ * VIDEO đi MediaPlayer → SurfaceTexture OES thứ hai, loop + câm tiếng.
+ */
+internal class GlCompositor(
+  private val context: Context,
+  private val outWidth: Int,
+  private val outHeight: Int,
+  private val encoderSurface: Surface,
+  /**
+   * Xoay nguồn camera (độ, bội 90). Chuẩn tham chiếu là CAMERA SAU của Redmi
+   * (sensor 90° — buffer tự nhiên đúng chiều ngang, đã kiểm 2 ngày field):
+   * module truyền (SENSOR_ORIENTATION − 90). Camera TRƯỚC (sensor 270) → 180.
+   * Hiện chỉ xử 0/180; 90/270 (dựng dọc) ngoài phạm vi như đường cũ.
+   */
+  private val cameraRotation: Int = 0,
+) {
+  /** Một lớp overlay theo hợp đồng JS (pixel của khung encode, gốc trên-trái). */
+  data class LayerSpec(
+    val id: String,
+    val kind: String, // "image" | "gif" | "video"
+    val filePath: String,
+    val x: Int,
+    val y: Int,
+    val width: Int,
+    val height: Int,
+    val opacity: Float,
+  )
+
+  /**
+   * Một lớp CHỮ đã điền sẵn (JS điền template — native chỉ vẽ). `x` là MỎ NEO
+   * theo `align`; màu đã parse thành ARGB ở module (bgArgb null = không nền,
+   * alpha của nền nằm trong chính bgArgb).
+   */
+  data class TextSpec(
+    val id: String,
+    val text: String,
+    val x: Int,
+    val y: Int,
+    val fontSizePx: Int,
+    val align: String, // "left" | "center" | "right"
+    val bold: Boolean,
+    val colorArgb: Int,
+    val opacity: Float,
+    val bgArgb: Int?,
+  )
+
+  private val thread = HandlerThread("pickleball-gl").also { it.start() }
+  private val handler = Handler(thread.looper)
+
+  private var eglDisplay: EGLDisplay = EGL14.EGL_NO_DISPLAY
+  private var eglContext: EGLContext = EGL14.EGL_NO_CONTEXT
+  private var eglConfig: EGLConfig? = null
+  private var encoderEgl: EGLSurface = EGL14.EGL_NO_SURFACE
+  private var previewEgl: EGLSurface = EGL14.EGL_NO_SURFACE
+  private var previewW = 0
+  private var previewH = 0
+
+  private var cameraTexId = 0
+  private var cameraST: SurfaceTexture? = null
+  /** Camera2 addTarget vào đây thay vì encoder surface. */
+  @Volatile var inputSurface: Surface? = null
+    private set
+
+  private var oesProgram = 0
+  private var rgbaProgram = 0
+  private val camMatrix = FloatArray(16)
+
+  private var layers: List<RuntimeLayer> = emptyList()
+  /** Lớp CHỮ — danh sách RIÊNG, vẽ TRÊN mọi lớp media. Tách để cập nhật chữ
+   * (2 lần/phút theo pha bóng) KHÔNG đụng tới media layer: setLayers rebuild
+   * là restart MediaPlayer của lớp video — churn đã đo, cấm tái phạm. */
+  private var textLayers: List<TextLayer> = emptyList()
+  @Volatile private var released = false
+
+  /** Báo cáo dựng lớp lần gần nhất — module trả về JS để log. */
+  @Volatile var lastLayerReport: List<Map<String, Any>> = emptyList()
+    private set
+
+  /** Báo cáo lớp chữ lần áp gần nhất. */
+  @Volatile var lastTextReport: List<Map<String, Any>> = emptyList()
+    private set
+
+  init {
+    runBlockingOnGl {
+      setupEgl()
+      setupCameraSource()
+    }
+  }
+
+  // MARK: - API (mọi việc GL đều nhảy vào render thread)
+
+  fun setLayers(specs: List<LayerSpec>) {
+    runBlockingOnGl {
+      layers.forEach { it.release() }
+      val report = mutableListOf<Map<String, Any>>()
+      layers = specs.mapNotNull { spec ->
+        val built = buildLayer(spec)
+        report.add(
+          if (built != null) {
+            mapOf("id" to spec.id, "applied" to true, "kind" to spec.kind)
+          } else {
+            mapOf("id" to spec.id, "applied" to false, "why" to "${spec.kind}_decode_failed")
+          },
+        )
+        built
+      }
+      lastLayerReport = report
+    }
+  }
+
+  /**
+   * Áp danh sách lớp CHỮ — cập nhật TẠI CHỖ theo id: chữ đổi thì render lại
+   * bitmap + texImage2D lên texture cũ; media layers không bị chạm. Spec y hệt
+   * lần trước thì lớp đó là no-op tuyệt đối.
+   */
+  fun setTextLayers(specs: List<TextSpec>) {
+    runBlockingOnGl {
+      val byId = textLayers.associateBy { it.id }.toMutableMap()
+      val report = mutableListOf<Map<String, Any>>()
+      val next = mutableListOf<TextLayer>()
+      for (spec in specs) {
+        // Tái dùng texture theo id — lấy RA khỏi map để phần còn lại là "lớp bị gỡ".
+        val layer = byId.remove(spec.id) ?: TextLayer(spec.id, makeTexture2D())
+        val ok = runCatching { layer.update(this, spec) }.getOrDefault(false)
+        if (ok) {
+          next.add(layer)
+          report.add(mapOf("id" to spec.id, "applied" to true))
+        } else {
+          // Lớp hỏng rơi RIÊNG (chữ là trang trí) — trả texture, không giữ xác.
+          layer.release()
+          report.add(mapOf("id" to spec.id, "applied" to false, "why" to "text_render_failed"))
+        }
+      }
+      byId.values.forEach { it.release() }
+      textLayers = next
+      lastTextReport = report
+    }
+  }
+
+  /** Preview view đến/đi không cần dựng lại camera — chỉ thay EGLSurface đích. */
+  fun setPreviewSurface(surface: Surface?, width: Int, height: Int) {
+    runBlockingOnGl {
+      if (previewEgl != EGL14.EGL_NO_SURFACE) {
+        EGL14.eglDestroySurface(eglDisplay, previewEgl)
+        previewEgl = EGL14.EGL_NO_SURFACE
+      }
+      if (surface != null && surface.isValid) {
+        previewEgl = EGL14.eglCreateWindowSurface(eglDisplay, eglConfig, surface, intArrayOf(EGL14.EGL_NONE), 0)
+        previewW = width
+        previewH = height
+      }
+    }
+  }
+
+  fun release() {
+    released = true
+    runBlockingOnGl {
+      layers.forEach { it.release() }
+      layers = emptyList()
+      textLayers.forEach { it.release() }
+      textLayers = emptyList()
+      cameraST?.setOnFrameAvailableListener(null)
+      inputSurface?.release()
+      inputSurface = null
+      cameraST?.release()
+      cameraST = null
+      if (oesProgram != 0) GLES20.glDeleteProgram(oesProgram)
+      if (rgbaProgram != 0) GLES20.glDeleteProgram(rgbaProgram)
+      if (cameraTexId != 0) GLES20.glDeleteTextures(1, intArrayOf(cameraTexId), 0)
+      if (previewEgl != EGL14.EGL_NO_SURFACE) EGL14.eglDestroySurface(eglDisplay, previewEgl)
+      if (encoderEgl != EGL14.EGL_NO_SURFACE) EGL14.eglDestroySurface(eglDisplay, encoderEgl)
+      EGL14.eglMakeCurrent(
+        eglDisplay, EGL14.EGL_NO_SURFACE, EGL14.EGL_NO_SURFACE, EGL14.EGL_NO_CONTEXT,
+      )
+      if (eglContext != EGL14.EGL_NO_CONTEXT) EGL14.eglDestroyContext(eglDisplay, eglContext)
+      if (eglDisplay != EGL14.EGL_NO_DISPLAY) EGL14.eglTerminate(eglDisplay)
+    }
+    thread.quitSafely()
+  }
+
+  // MARK: - EGL + camera source
+
+  private fun setupEgl() {
+    eglDisplay = EGL14.eglGetDisplay(EGL14.EGL_DEFAULT_DISPLAY)
+    check(eglDisplay != EGL14.EGL_NO_DISPLAY) { "không lấy được EGL display" }
+    val version = IntArray(2)
+    check(EGL14.eglInitialize(eglDisplay, version, 0, version, 1)) { "eglInitialize thất bại" }
+    val attribs = intArrayOf(
+      EGL14.EGL_RED_SIZE, 8,
+      EGL14.EGL_GREEN_SIZE, 8,
+      EGL14.EGL_BLUE_SIZE, 8,
+      EGL14.EGL_ALPHA_SIZE, 8,
+      EGL14.EGL_RENDERABLE_TYPE, EGL14.EGL_OPENGL_ES2_BIT,
+      // EGL_RECORDABLE_ANDROID: bắt buộc để ghi được vào surface của MediaCodec.
+      0x3142, 1,
+      EGL14.EGL_NONE,
+    )
+    val configs = arrayOfNulls<EGLConfig>(1)
+    val num = IntArray(1)
+    check(EGL14.eglChooseConfig(eglDisplay, attribs, 0, configs, 0, 1, num, 0) && num[0] > 0) {
+      "không có EGL config phù hợp"
+    }
+    eglConfig = configs[0]
+    eglContext = EGL14.eglCreateContext(
+      eglDisplay, eglConfig, EGL14.EGL_NO_CONTEXT,
+      intArrayOf(EGL14.EGL_CONTEXT_CLIENT_VERSION, 2, EGL14.EGL_NONE), 0,
+    )
+    check(eglContext != EGL14.EGL_NO_CONTEXT) { "không tạo được EGL context" }
+    encoderEgl = EGL14.eglCreateWindowSurface(
+      eglDisplay, eglConfig, encoderSurface, intArrayOf(EGL14.EGL_NONE), 0,
+    )
+    check(encoderEgl != EGL14.EGL_NO_SURFACE) { "không tạo được EGLSurface cho encoder" }
+    check(EGL14.eglMakeCurrent(eglDisplay, encoderEgl, encoderEgl, eglContext)) {
+      "eglMakeCurrent thất bại"
+    }
+    oesProgram = buildProgram(VERTEX_SHADER, FS_OES)
+    rgbaProgram = buildProgram(VERTEX_SHADER, FS_RGBA)
+  }
+
+  private fun setupCameraSource() {
+    val ids = IntArray(1)
+    GLES20.glGenTextures(1, ids, 0)
+    cameraTexId = ids[0]
+    GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, cameraTexId)
+    linearClamp(GLES11Ext.GL_TEXTURE_EXTERNAL_OES)
+    val st = SurfaceTexture(cameraTexId)
+    st.setDefaultBufferSize(outWidth, outHeight)
+    // Nghe trên CHÍNH render thread — khung camera đến là vẽ, không nhảy thread.
+    st.setOnFrameAvailableListener({ onCameraFrame() }, handler)
+    cameraST = st
+    inputSurface = Surface(st)
+  }
+
+  // MARK: - Render
+
+  private fun onCameraFrame() {
+    if (released) return
+    val st = cameraST ?: return
+    if (!EGL14.eglMakeCurrent(eglDisplay, encoderEgl, encoderEgl, eglContext)) return
+    st.updateTexImage()
+    st.getTransformMatrix(camMatrix)
+    layers.forEach { it.tick() }
+
+    drawScene(outWidth, outHeight)
+    EGLExt.eglPresentationTimeANDROID(eglDisplay, encoderEgl, st.timestamp)
+    EGL14.eglSwapBuffers(eglDisplay, encoderEgl)
+
+    if (previewEgl != EGL14.EGL_NO_SURFACE) {
+      if (EGL14.eglMakeCurrent(eglDisplay, previewEgl, previewEgl, eglContext)) {
+        drawScene(previewW, previewH)
+        EGL14.eglSwapBuffers(eglDisplay, previewEgl)
+      }
+    }
+  }
+
+  private fun drawScene(viewW: Int, viewH: Int) {
+    GLES20.glViewport(0, 0, viewW, viewH)
+    GLES20.glClearColor(0f, 0f, 0f, 1f)
+    GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT)
+    // Camera full khung — KHÔNG dùng transform matrix của SurfaceTexture: ma
+    // trận đó xoay ảnh về chiều dọc-tự-nhiên của điện thoại (chuẩn hiển thị),
+    // vẽ vào khung ngang là xoay 90° + bóp dẹt (đo thật 26/08 tối). Đường
+    // encoder trực tiếp (không GL, đã kiểm field) nhận BUFFER THÔ — GL phải
+    // sample đúng buffer thô đó: identity + lật v cho hệ GL.
+    drawQuad(
+      oesProgram, GLES11Ext.GL_TEXTURE_EXTERNAL_OES, cameraTexId,
+      if (cameraRotation == 180) FULL_RECT_NDC_ROT180 else FULL_RECT_NDC,
+      IDENTITY, 1f, blend = false,
+    )
+    for (layer in layers) {
+      layer.draw(this)
+    }
+    // Chữ trên cùng — sau mọi lớp media.
+    for (layer in textLayers) {
+      layer.draw(this)
+    }
+  }
+
+  internal fun drawLayerQuad(
+    program: Int, target: Int, texId: Int,
+    rect: FloatArray, texMatrix: FloatArray, opacity: Float,
+  ) = drawQuad(program, target, texId, rect, texMatrix, opacity, blend = true)
+
+  private fun drawQuad(
+    program: Int, target: Int, texId: Int,
+    ndcRect: FloatArray, texMatrix: FloatArray, opacity: Float, blend: Boolean,
+  ) {
+    GLES20.glUseProgram(program)
+    if (blend) {
+      GLES20.glEnable(GLES20.GL_BLEND)
+      // Premultiplied alpha — GL_ONE, không phải GL_SRC_ALPHA (viền đen).
+      GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ONE_MINUS_SRC_ALPHA)
+    } else {
+      GLES20.glDisable(GLES20.GL_BLEND)
+    }
+    val pos = GLES20.glGetAttribLocation(program, "aPos")
+    val tex = GLES20.glGetAttribLocation(program, "aTex")
+    val uM = GLES20.glGetUniformLocation(program, "uTexMatrix")
+    val uA = GLES20.glGetUniformLocation(program, "uAlpha")
+    val uS = GLES20.glGetUniformLocation(program, "uTexture")
+
+    vertexBuf.clear()
+    vertexBuf.put(ndcRect).position(0)
+    GLES20.glEnableVertexAttribArray(pos)
+    GLES20.glVertexAttribPointer(pos, 2, GLES20.GL_FLOAT, false, 16, vertexBuf)
+    vertexBuf.position(2)
+    GLES20.glEnableVertexAttribArray(tex)
+    GLES20.glVertexAttribPointer(tex, 2, GLES20.GL_FLOAT, false, 16, vertexBuf)
+
+    GLES20.glUniformMatrix4fv(uM, 1, false, texMatrix, 0)
+    GLES20.glUniform1f(uA, opacity)
+    GLES20.glActiveTexture(GLES20.GL_TEXTURE0)
+    GLES20.glBindTexture(target, texId)
+    GLES20.glUniform1i(uS, 0)
+    GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4)
+    GLES20.glDisableVertexAttribArray(pos)
+    GLES20.glDisableVertexAttribArray(tex)
+  }
+
+  /**
+   * [x,y,w,h] pixel (gốc trên-trái) → strip NDC xen kẽ pos/tex (x,y,u,v ×4).
+   * Hai hệ v NGƯỢC nhau: bitmap upload hàng đầu = mép TRÊN (v=0 ở đỉnh), còn
+   * SurfaceTexture OES (video/camera) theo hệ GL v=0 ở ĐÁY — đo thật 26/08:
+   * dùng hệ bitmap cho video là chữ trên sóng lật ngược.
+   */
+  internal fun ndcRectOf(x: Int, y: Int, w: Int, h: Int, oesV: Boolean = false): FloatArray {
+    val x0 = 2f * x / outWidth - 1f
+    val x1 = 2f * (x + w) / outWidth - 1f
+    val yTop = 1f - 2f * y / outHeight
+    val yBot = 1f - 2f * (y + h) / outHeight
+    val vTop = if (oesV) 1f else 0f
+    val vBot = if (oesV) 0f else 1f
+    return floatArrayOf(
+      x0, yBot, 0f, vBot,
+      x1, yBot, 1f, vBot,
+      x0, yTop, 0f, vTop,
+      x1, yTop, 1f, vTop,
+    )
+  }
+
+  // MARK: - Layers
+
+  private fun buildLayer(spec: LayerSpec): RuntimeLayer? {
+    if (spec.width < 1 || spec.height < 1) return null
+    if (!File(spec.filePath).exists()) return null
+    return when (spec.kind) {
+      "image" -> StaticLayer.create(this, spec)
+      "gif" -> GifLayer.create(this, spec)
+      "video" -> VideoLayer.create(this, spec)
+      else -> null
+    }
+  }
+
+  internal fun makeTexture2D(): Int {
+    val ids = IntArray(1)
+    GLES20.glGenTextures(1, ids, 0)
+    GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, ids[0])
+    linearClamp(GLES20.GL_TEXTURE_2D)
+    return ids[0]
+  }
+
+  internal fun makeTextureOes(): Int {
+    val ids = IntArray(1)
+    GLES20.glGenTextures(1, ids, 0)
+    GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, ids[0])
+    linearClamp(GLES11Ext.GL_TEXTURE_EXTERNAL_OES)
+    return ids[0]
+  }
+
+  private fun linearClamp(target: Int) {
+    GLES20.glTexParameteri(target, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR)
+    GLES20.glTexParameteri(target, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR)
+    GLES20.glTexParameteri(target, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE)
+    GLES20.glTexParameteri(target, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE)
+  }
+
+  internal abstract class RuntimeLayer {
+    /** Cập nhật nguồn (khung gif/video mới) — chạy trên render thread. */
+    open fun tick() = Unit
+    abstract fun draw(gl: GlCompositor)
+    open fun release() = Unit
+  }
+
+  /** Ảnh tĩnh (composite/logo): upload MỘT lần, mỗi khung chỉ còn draw. */
+  private class StaticLayer(
+    private val texId: Int,
+    private val rect: FloatArray,
+    private val opacity: Float,
+  ) : RuntimeLayer() {
+    override fun draw(gl: GlCompositor) =
+      gl.drawLayerQuad(gl.rgbaProgram, GLES20.GL_TEXTURE_2D, texId, rect, IDENTITY, opacity)
+
+    override fun release() {
+      GLES20.glDeleteTextures(1, intArrayOf(texId), 0)
+    }
+
+    companion object {
+      fun create(gl: GlCompositor, spec: LayerSpec): StaticLayer? {
+        val bitmap = BitmapFactory.decodeFile(spec.filePath) ?: return null
+        val texId = gl.makeTexture2D()
+        GLUtils.texImage2D(GLES20.GL_TEXTURE_2D, 0, bitmap, 0)
+        bitmap.recycle()
+        return StaticLayer(texId, gl.ndcRectOf(spec.x, spec.y, spec.width, spec.height), spec.opacity)
+      }
+    }
+  }
+
+  /**
+   * GIF qua Movie: mình cầm đồng hồ (elapsed % duration), mỗi tick vẽ đúng một
+   * khung vào bitmap cỡ ô rồi texSubImage2D — RAM O(1 khung) như GifSource iOS.
+   */
+  private class GifLayer(
+    private val movie: Movie,
+    private val texId: Int,
+    private val bitmap: Bitmap,
+    private val canvas: Canvas,
+    private val rect: FloatArray,
+    private val opacity: Float,
+  ) : RuntimeLayer() {
+    private val startedAt = SystemClock.elapsedRealtime()
+    private val durationMs = movie.duration().coerceAtLeast(1)
+    private var lastShownMs = -1
+
+    override fun tick() {
+      val t = ((SystemClock.elapsedRealtime() - startedAt) % durationMs).toInt()
+      // Movie tự biết khung nào ứng thời điểm nào; chỉ upload khi mốc đổi.
+      if (t == lastShownMs) return
+      lastShownMs = t
+      movie.setTime(t)
+      canvas.drawColor(0, PorterDuff.Mode.CLEAR)
+      canvas.save()
+      canvas.scale(
+        bitmap.width.toFloat() / movie.width().coerceAtLeast(1),
+        bitmap.height.toFloat() / movie.height().coerceAtLeast(1),
+      )
+      movie.draw(canvas, 0f, 0f)
+      canvas.restore()
+      GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, texId)
+      GLUtils.texSubImage2D(GLES20.GL_TEXTURE_2D, 0, 0, 0, bitmap)
+    }
+
+    override fun draw(gl: GlCompositor) =
+      gl.drawLayerQuad(gl.rgbaProgram, GLES20.GL_TEXTURE_2D, texId, rect, IDENTITY, opacity)
+
+    override fun release() {
+      GLES20.glDeleteTextures(1, intArrayOf(texId), 0)
+      bitmap.recycle()
+    }
+
+    companion object {
+      @Suppress("DEPRECATION")
+      fun create(gl: GlCompositor, spec: LayerSpec): GifLayer? {
+        val movie = runCatching { Movie.decodeFile(spec.filePath) }.getOrNull() ?: return null
+        if (movie.width() < 1 || movie.height() < 1) return null
+        val bitmap = Bitmap.createBitmap(spec.width, spec.height, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bitmap)
+        val texId = gl.makeTexture2D()
+        GLUtils.texImage2D(GLES20.GL_TEXTURE_2D, 0, bitmap, 0)
+        return GifLayer(
+          movie, texId, bitmap, canvas,
+          gl.ndcRectOf(spec.x, spec.y, spec.width, spec.height), spec.opacity,
+        )
+      }
+    }
+  }
+
+  /**
+   * VIDEO qua MediaPlayer → SurfaceTexture OES riêng: decode cứng, loop, câm
+   * tiếng. Opacity ép 1 (khớp iOS — nhãn UI đã nói thật điều này).
+   */
+  private class VideoLayer(
+    private val player: MediaPlayer,
+    private val texId: Int,
+    private val st: SurfaceTexture,
+    private val surface: Surface,
+    private val rect: FloatArray,
+  ) : RuntimeLayer() {
+    @Volatile private var frameReady = false
+    private val matrix = FloatArray(16)
+
+    init {
+      st.setOnFrameAvailableListener { frameReady = true }
+      android.opengl.Matrix.setIdentityM(matrix, 0)
+    }
+
+    override fun tick() {
+      if (!frameReady) return
+      frameReady = false
+      st.updateTexImage()
+      st.getTransformMatrix(matrix)
+    }
+
+    override fun draw(gl: GlCompositor) =
+      gl.drawLayerQuad(gl.oesProgram, GLES11Ext.GL_TEXTURE_EXTERNAL_OES, texId, rect, matrix, 1f)
+
+    override fun release() {
+      runCatching { player.stop() }
+      runCatching { player.release() }
+      st.setOnFrameAvailableListener(null)
+      surface.release()
+      st.release()
+      GLES20.glDeleteTextures(1, intArrayOf(texId), 0)
+    }
+
+    companion object {
+      fun create(gl: GlCompositor, spec: LayerSpec): VideoLayer? {
+        val texId = gl.makeTextureOes()
+        val st = SurfaceTexture(texId)
+        st.setDefaultBufferSize(spec.width, spec.height)
+        val surface = Surface(st)
+        val player = MediaPlayer()
+        val ok = runCatching {
+          player.setDataSource(spec.filePath)
+          player.setSurface(surface)
+          player.isLooping = true
+          player.setVolume(0f, 0f)
+          player.prepare()
+          player.start()
+        }.isSuccess
+        if (!ok) {
+          runCatching { player.release() }
+          surface.release()
+          st.release()
+          GLES20.glDeleteTextures(1, intArrayOf(texId), 0)
+          return null
+        }
+        return VideoLayer(
+          player, texId, st, surface,
+          gl.ndcRectOf(spec.x, spec.y, spec.width, spec.height, oesV = true),
+        )
+      }
+    }
+  }
+
+  /**
+   * Lớp CHỮ: bitmap vẽ bằng Paint (font hệ thống — tiếng Việt đủ dấu) upload
+   * lên MỘT texture tái dùng theo id. `update` chỉ chạy khi spec ĐỔI (so
+   * equality data class) — mỗi pha bóng một lần render ~vài trăm µs, giữa hai
+   * pha là no-op tuyệt đối. Hình học nền = bội fontSize (0.45/0.25/0.22),
+   * PHẢI khớp OVERLAY_TEXT_BG của @pickleball/shared (preview editor cùng công thức).
+   */
+  internal class TextLayer(val id: String, private val texId: Int) : RuntimeLayer() {
+    private var applied: TextSpec? = null
+    private var rect: FloatArray = FloatArray(16)
+    private var opacity = 1f
+    private var hasContent = false
+
+    /** Render + upload nếu spec đổi. Trả false khi không dựng được bitmap. */
+    fun update(gl: GlCompositor, spec: TextSpec): Boolean {
+      if (spec == applied) return true
+      val fontSize = spec.fontSizePx.coerceAtLeast(8).toFloat()
+      val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        textSize = fontSize
+        typeface = if (spec.bold) Typeface.DEFAULT_BOLD else Typeface.DEFAULT
+        color = spec.colorArgb
+      }
+      val fm = paint.fontMetrics
+      val textW = paint.measureText(spec.text)
+      val hasBg = spec.bgArgb != null
+      val padX = if (hasBg) fontSize * 0.45f else 0f
+      val padY = if (hasBg) fontSize * 0.25f else 0f
+      val w = kotlin.math.ceil(textW + padX * 2).toInt().coerceAtLeast(1)
+      val h = kotlin.math.ceil((fm.descent - fm.ascent) + padY * 2).toInt().coerceAtLeast(1)
+      if (w > 4096 || h > 1024) return false
+      val bitmap = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+      val canvas = Canvas(bitmap)
+      if (hasBg) {
+        val bgPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply { color = spec.bgArgb!! }
+        val radius = fontSize * 0.22f
+        canvas.drawRoundRect(RectF(0f, 0f, w.toFloat(), h.toFloat()), radius, radius, bgPaint)
+      }
+      canvas.drawText(spec.text, padX, padY - fm.ascent, paint)
+      GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, texId)
+      // texImage2D (không phải SUB): bề rộng chữ đổi theo nội dung ("7"→"10"),
+      // cấp phát lại storage trên CÙNG texture id — layer không bị dựng lại.
+      GLUtils.texImage2D(GLES20.GL_TEXTURE_2D, 0, bitmap, 0)
+      bitmap.recycle()
+      // Mỏ neo theo align: x là mép trái/tâm/mép phải của ẢNH (ảnh ôm trọn nền).
+      val left = when (spec.align) {
+        "center" -> spec.x - w / 2
+        "right" -> spec.x - w
+        else -> spec.x
+      }.coerceAtLeast(0)
+      rect = gl.ndcRectOf(left, spec.y, w, h)
+      opacity = spec.opacity
+      applied = spec
+      hasContent = true
+      return true
+    }
+
+    override fun draw(gl: GlCompositor) {
+      if (!hasContent) return
+      // Opacity CẢ LỚP qua uAlpha: shader nhân cả rgb lẫn alpha — đúng phép
+      // fade premultiplied, không cần bake vào bitmap như đường CPU bên iOS.
+      gl.drawLayerQuad(gl.rgbaProgram, GLES20.GL_TEXTURE_2D, texId, rect, IDENTITY, opacity)
+    }
+
+    override fun release() {
+      GLES20.glDeleteTextures(1, intArrayOf(texId), 0)
+    }
+  }
+
+  // MARK: - Helpers
+
+  private fun runBlockingOnGl(block: () -> Unit) {
+    if (Thread.currentThread() === thread) {
+      block()
+      return
+    }
+    val latch = CountDownLatch(1)
+    handler.post {
+      try {
+        block()
+      } finally {
+        latch.countDown()
+      }
+    }
+    latch.await()
+  }
+
+  private fun buildProgram(vs: String, fs: String): Int {
+    fun compile(type: Int, src: String): Int {
+      val id = GLES20.glCreateShader(type)
+      GLES20.glShaderSource(id, src)
+      GLES20.glCompileShader(id)
+      val ok = IntArray(1)
+      GLES20.glGetShaderiv(id, GLES20.GL_COMPILE_STATUS, ok, 0)
+      check(ok[0] != 0) { "shader lỗi: ${GLES20.glGetShaderInfoLog(id)}" }
+      return id
+    }
+    val program = GLES20.glCreateProgram()
+    GLES20.glAttachShader(program, compile(GLES20.GL_VERTEX_SHADER, vs))
+    GLES20.glAttachShader(program, compile(GLES20.GL_FRAGMENT_SHADER, fs))
+    GLES20.glLinkProgram(program)
+    val ok = IntArray(1)
+    GLES20.glGetProgramiv(program, GLES20.GL_LINK_STATUS, ok, 0)
+    check(ok[0] != 0) { "link program lỗi: ${GLES20.glGetProgramInfoLog(program)}" }
+    return program
+  }
+
+  private companion object {
+    val IDENTITY = FloatArray(16).also { android.opengl.Matrix.setIdentityM(it, 0) }
+
+    /**
+     * Full khung cho CAMERA sample BUFFER THÔ (identity, không qua ma trận ST):
+     * hàng-0 của buffer = mép TRÊN ảnh → v=0 phải nằm ở ĐỈNH quad. Gắn v=0
+     * xuống đáy là "lộn ngược chốc đầu" (đo thật 26/08 tối, vòng thử 2).
+     */
+    val FULL_RECT_NDC = floatArrayOf(
+      -1f, -1f, 0f, 1f,
+      1f, -1f, 1f, 1f,
+      -1f, 1f, 0f, 0f,
+      1f, 1f, 1f, 0f,
+    )
+
+    /** Như trên nhưng texcoord xoay 180° — (u,v) → (1−u, 1−v). */
+    val FULL_RECT_NDC_ROT180 = floatArrayOf(
+      -1f, -1f, 1f, 1f,
+      1f, -1f, 0f, 1f,
+      -1f, 1f, 1f, 0f,
+      1f, 1f, 0f, 0f,
+    )
+
+    val vertexBuf: FloatBuffer = ByteBuffer.allocateDirect(16 * 4)
+      .order(ByteOrder.nativeOrder()).asFloatBuffer()
+
+    const val VERTEX_SHADER = """
+      attribute vec2 aPos;
+      attribute vec2 aTex;
+      uniform mat4 uTexMatrix;
+      varying vec2 vTex;
+      void main() {
+        gl_Position = vec4(aPos, 0.0, 1.0);
+        vTex = (uTexMatrix * vec4(aTex, 0.0, 1.0)).xy;
+      }
+    """
+
+    const val FS_OES = """
+      #extension GL_OES_EGL_image_external : require
+      precision mediump float;
+      varying vec2 vTex;
+      uniform samplerExternalOES uTexture;
+      uniform float uAlpha;
+      void main() {
+        gl_FragColor = texture2D(uTexture, vTex) * uAlpha;
+      }
+    """
+
+    const val FS_RGBA = """
+      precision mediump float;
+      varying vec2 vTex;
+      uniform sampler2D uTexture;
+      uniform float uAlpha;
+      void main() {
+        gl_FragColor = texture2D(uTexture, vTex) * uAlpha;
+      }
+    """
+  }
+}