From e1bc8cc52f9d43c2994da1aa4e79fd16e2f8ecdc Mon Sep 17 00:00:00 2001
From: BoatingCloud <1759888028@qq.com>
Date: Sat, 29 Aug 2026 12:43:14 +0800
Subject: [PATCH] docs: add Phase 4 OHCodec status

---
 DOCS/OHCODEC_INTEGRATION.md | 42 +++++++++++++++++++++++++++++++++++++
 DOCS/PHASE4_STATUS.md       | 42 +++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 DOCS/OHCODEC_INTEGRATION.md
 create mode 100644 DOCS/PHASE4_STATUS.md

diff --git a/DOCS/OHCODEC_INTEGRATION.md b/DOCS/OHCODEC_INTEGRATION.md
new file mode 100644
index 0000000000..05467ebeca
--- /dev/null
+++ b/DOCS/OHCODEC_INTEGRATION.md
@@ -0,0 +1,42 @@
+# MPV OHCodec 集成说明
+
+## 已实现路径
+
+`hwdec=ohcodec` 由 MPV/FFmpeg 的动态 hardware-decoder 枚举进入独立
+`AV_HWDEVICE_TYPE_OHCODEC` backend。`IMGFMT_OHCODEC` 与
+`AV_PIX_FMT_OHCODEC` 使用单一映射。当前 adapter 只允许 H.264 和 HEVC，先
+查询 API 24 OHCodec hardware capability，再检查 host 注入的独占
+`ohos_direct_surface`，最后创建带 `OHNativeWindow*` 的 FFmpeg hwdevice。
+
+Direct Surface backend 的名称是
+`ohcodec-direct-surface-experimental`。它只负责证明 device/decoder/surface
+plumbing，不与 Playback Lab 的 EGL window 共享呈现权；没有独占窗口时明确失败，
+MPV 保留 software decoder fallback。
+
+## 状态与回退
+
+适配器记录 `HWDEC_DISABLED`、`HWDEC_REQUESTED`、`HWDEC_CAPABILITY_CHECK`、
+`HWDEC_DEVICE_CREATED`、`HWDEC_DECODER_CREATED`、`HWDEC_DIRECT_SURFACE`、
+`HWDEC_GPU_INTEROP`、`HWDEC_ACTIVE`、`HWDEC_FALLBACK`、`HWDEC_ERROR`。
+Playback Lab 通过 libmpv 诊断 API 与属性显示 requested/actual decoder、active
+状态、backend、capability、fallback reason 及 hardware/software frame 计数。
+
+capability 查询失败、codec/profile/level 不支持、surface 不可用、device/decoder
+创建失败或后续 interop 失败都必须返回失败并回到 software path；不把空 device、
+opaque pointer 或 CPU readback 当成成功的硬件帧。
+
+## Surface 生命周期约束
+
+`ohos_direct_surface` 的引用由 adapter 持有，host 负责提供一个不等于
+Playback Lab EGL window 的独占窗口。Surface 销毁或重建时，host 必须先停止
+decoder/render、等待 AVFrame release，再销毁旧 device 并用新窗口重建；当前代
+码只完成 ownership guard，generation/fence/present 的实体设备验证仍待做。
+
+## GPU interop 边界
+
+`harmony-ohcodec-gl` 默认关闭，仅编译 API probe：API24 可探测
+`OH_AVBuffer_GetNativeBuffer`、NativeWindow wrapper、EGL native-buffer image
+和 GLES external texture 扩展。但 FFmpeg upstream 的硬件分支是 surface-first，
+没有“不 present 到 decoder Surface、直接导出可导入 NativeBuffer”的契约；见
+`DOCS/OHCODEC_GPU_INTEROP_DESIGN.md` 中的 `OHCODEC-BLOCKER-001`。因此当前不
+提交 mapper、不宣称 zero-copy，也不宣称 HDR。
diff --git a/DOCS/PHASE4_STATUS.md b/DOCS/PHASE4_STATUS.md
new file mode 100644
index 0000000000..d4d7bc97a2
--- /dev/null
+++ b/DOCS/PHASE4_STATUS.md
@@ -0,0 +1,42 @@
+# Phase 4 状态
+
+## 结论
+
+**Phase 4 CODE COMPLETE / GPU INTEROP BLOCKED / DEVICE VALIDATION PENDING**
+
+代码完成了 MPV 识别 FFmpeg OHCodec、H.264/HEVC decoder selection、能力检查、
+direct-surface 实验接入、软件回退、诊断和构建矩阵。当前没有实体设备，因此
+不能写成 hardware decode complete、zero-copy complete 或 HDR complete。
+
+## 验证矩阵
+
+| 项目 | 状态 |
+| --- | --- |
+| `AV_PIX_FMT_OHCODEC` → `IMGFMT_OHCODEC` | COMPILE VERIFIED |
+| `AV_HWDEVICE_TYPE_OHCODEC` 独立 backend | COMPILE VERIFIED |
+| H.264 / HEVC selection guard | COMPILE VERIFIED；DEVICE TEST REQUIRED |
+| API24 OHCodec capability 查询 | COMPILE VERIFIED；设备返回值待验 |
+| Direct Surface plumbing | COMPILE VERIFIED；需独占窗口 |
+| GPU interop mapper | BLOCKED：上游无可导入 non-surface output contract |
+| Software decode / OHAudio | CLEAN BUILD VERIFIED |
+| OHCodec-enabled / software / GL-probe | AArch64 BUILD VERIFIED |
+| Playback Lab HAP | BUILD VERIFIED；unsigned |
+| Emulator | APP START + EGL SMOKE VERIFIED；不是硬解验证 |
+| Physical device | PENDING |
+
+## 产物与审计
+
+- `build/ohos-arm64/prefix/lib/libmpv.so.2.5.0` 为 AArch64 ELF，保留 OHCodec、
+  OHAudio 及诊断符号。
+- `scripts/build-mpv-ohos-software.sh` 使用独立 build 目录关闭 OHCodec，避免
+  软件回退配置与硬解构建互相污染。
+- FFmpeg 保持锁定 upstream commit，未复制 SDK/第三方实现；许可证审计见
+  `LICENSE_AUDIT.md`。
+- 当前 blocker、NativeBuffer 生命周期、EGL/fence/crop/stride 待验证项见
+  `DOCS/OHCODEC_GPU_INTEROP_DESIGN.md` 与 `DOCS/HDR_PIPELINE_NOTES.md`。
+
+## 下一阶段最大风险
+
+实体设备上的 codec capability、surface recreate、output buffer ownership、
+acquire/release fence、crop/stride/color metadata，以及如何在不修改 FFmpeg
+surface contract 的前提下把硬件帧交给 MPV GPU composition。