系列导读：第四篇停在CCodecBufferChannel::queueInputBufferInternal里那一行mComponent->queue(&items)——一个C2Work列表打过去，HAL 那边解完通过onWorkDone回来。这一篇接着拆开这条线：

• C2Work到底装了什么、为什么是这个形状？
• mComponent->queue()这一下从 App 进程到 vendor 进程到底走过哪些环节？
• 解出来的 YUV 是怎么跨进程零拷贝交回来的？

Codec2 的几个核心数据结构会先用一节快速过完，主线放在C2Work的来回与跨进程机制。

Codec2 数据结构速览

后面追queue / onWorkDone这条线时会反复用到这几个名字，这里先一张表对齐：

层级上C2Work套C2FrameData套C2Buffer套C2Block，越往里越接近物理内存。C2BlockPool在外侧管分配，C2Fence横在中间管时序，C2Param独立成另一条线管配置。

后面真正要追的就两条：C2Work在queue / onWorkDone这条来回上是怎么填、怎么对回来的，以及它内部那几个shared_ptr<C2Buffer>是怎么跨进程不丢内存的。

C2Work 长什么样

打开C2Work.h，结构体本身只有四五个字段：

struct C2Work {
    C2FrameData input;                                 // 输入：一帧压缩数据
    std::list<std::unique_ptr<C2Worklet>> worklets;    // 输出占位

    uint32_t   workletsProcessed = 0;                  // 完成的 worklet 数
    c2_status_t result = C2_OK;                        // 处理结果

    C2WorkOrdinalStruct input_ordinal;
};

struct C2FrameData {
    uint32_t flags;                                       // EOS / CODEC_CONFIG / DROP_FRAME ...
    C2WorkOrdinalStruct ordinal;                          // 时间戳 / 帧号
    std::vector<std::shared_ptr<C2Buffer>> buffers;       // 实际数据
    std::vector<std::unique_ptr<C2Param>> configUpdate;   // 动态配置（如 bitrate 调整）
    std::vector<std::shared_ptr<C2InfoBuffer>> infoBuffers;
};

第四篇queueInputBufferInternal那段填的就是这两个结构。先记三条，后面跨进程时还会回来用：

输入和输出共用同一种容器C2FrameData。input是一份C2FrameData，每个worklet->output也是一份C2FrameData。差别只在装的内容：input 装压缩码流（Linear C2Buffer），output 装解码 YUV（Graphic C2Buffer）。这种对称让 HAL 那边写代码很省事——同一套 buffer 处理逻辑两边都能用。

worklets是输出占位，不是预先填好的输出。CCodecBufferChannel 在queueInputBufferInternal里只emplace_back(new C2Worklet)塞了一个空 worklet 进去，里面什么都没有。HAL 解完一帧后，把 YUV C2Buffer填到worklet->output.buffers里再回传——这个”留位 → 回填”的设计是异步路径的关键。

input_ordinal三个字段各管各的：

struct C2WorkOrdinalStruct {
    c2_cntr64_t timestamp;       // PTS（纳秒），可以不单调（B 帧重排）
    c2_cntr64_t frameIndex;      // 全局单调递增的帧号
    c2_cntr64_t customOrdinal;   // 客户端自定义
};

timestamp是 PTS，给 A/V 同步看的；frameIndex是 BufferChannel 自己维护的单调递增序号——HAL 处理完回调时只带这个 index，BufferChannel 拿它在内部映射表里查”这条 work 是哪一帧、对应哪个 input slot”。第四篇那行mFrameIndex++填的就是这个字段。customOrdinal这里就是 PTS 的副本，给上层做去重用。

为什么不直接拿timestamp认领？因为 B 帧场景下 PTS 不单调、可能重复（seek 后两帧 PTS 相同），靠它做主键会撞车。frameIndex保证一帧一个 ID，认领时不会出歧义。

一次 queue 的进程内调用

mComponent->queue()这行后面，从 App 进程到 vendor 进程之间隔着两个明显的边界：一个是 HAL 客户端代理Codec2Client，一个是 Binder 内核调用。

两个边界各自承担一件不同的事：

• Codec2Client这一层做的是类型转换——把 App 进程内部用的 C++ 对象C2Work（带std::list、std::shared_ptr<C2Buffer>、虚表指针这些没法跨进程的东西）翻译成 HIDL/AIDL 定义的、纯数据的WorkBundle。这一步只在 App 进程内做，不涉及内核。
• Binder 这一层做的是搬运——把上面那个WorkBundle走 binder 驱动送到 vendor 进程，期间内核负责 fd 的复制和数据拷贝。

为什么要拆成两层？因为 HIDL/AIDL 自动生成的 binder proxy 只认 IDL 里声明的纯数据类型，而CCodecBufferChannel手里拿的是 C++ 业务对象。中间这层Codec2Client就是”业务对象 ↔ IDL 数据”的翻译层——上层永远拿C2Work写代码，下层永远收WorkBundle传 binder，互不打扰。

先看 App 进程这一侧从 BufferChannel 走到代理为止的路径。

flowchart TB    A["CCodecBufferChannel::queueInputBufferInternal
构造 C2Work、填 frameIndex、切 C2Buffer 视图"]    B["std::list<unique_ptr<C2Work>> items"]    C["mComponent->queue(&items)
(Codec2Client::Component 客户端代理)"]    D["objcpy(C2Work -> WorkBundle)
把 shared_ptr<C2Buffer> 序列化成可跨进程的形式"]    E["IComponent::queue(workBundle)
(HIDL/AIDL proxy)"]    F["binder driver"]    A --> B --> C --> D --> E --> F

最关键的一步是objcpy这个序列化函数，对应Codec2Client::Component::queue大致是这样：

c2_status_t Codec2Client::Component::queue(
        std::list<std::unique_ptr<C2Work>> *const items) {
    // 1. 把 C2Work 列表打包成跨进程能传的 WorkBundle
    WorkBundle workBundle;
    Status status = objcpy(&workBundle, *items, &mBufferPoolSender);

    // 2. Binder 调用，把 workBundle 投给 vendor
    Return<Status> transStatus = mBase->queue(workBundle);

    // 3. 清空原列表——所有权已经过去了
    items->clear();
    return /* ... */;
}

WorkBundle是 HIDL/AIDL 自动生成的可序列化结构，对应C2Work但只装可跨进程传的字段（POD 数据 + handle）。objcpy做的事情就是把每个C2Work里的shared_ptr<C2Buffer>拆开、把底层C2Block的native_handle（也就是 ION/dma-buf 的 fd）抽出来塞进WorkBundle。

std::shared_ptr<C2Buffer>本身没法跨进程——它是 App 进程里的 C++ 引用计数对象。能跨过去的只有里面那个 fd。Binder 跨进程传 fd 时，内核会在目标进程里复制出一个新 fd 编号，但指向同一块物理内存。WorkBundle这一头是”原料清单”，到 vendor 那头objcpy再反向走一遍——根据 fd 重建一个本地的C2Buffer/C2Block对象。两边都拿着各自的shared_ptr管自己的引用计数，不互相干扰。

flowchart LR    subgraph App["App 进程"]        direction TB        A1["C2Buffer"]        A2["C2Block"]        A3["C2Handle
fd = 42"]        A1 --> A2 --> A3    end    subgraph Vendor["vendor 进程"]        direction TB        V1["C2Buffer"]        V2["C2Block"]        V3["C2Handle
fd = 78"]        V1 --> V2 --> V3    end    DMA[("同一块
ION / dma-buf")]    A3 -. Binder 传 fd .-> V3    A3 --> DMA    V3 --> DMA

但只靠 fd 还有一个问题没解决：生产侧什么时候 free 这块内存？App 进程把shared_ptr一释放，本地引用计数归零，但 vendor 那边可能还在用。这事归 BufferPool 管。

BufferPool：跨进程的引用计数

android.hardware.media.bufferpool@2.0是一个独立的 HAL 服务，专门做一件事——让一块共享内存的引用计数能跨进程算清楚。

机制概括成一句：每块 buffer 有一个全局唯一的 BufferID，所有持有者通过 BufferPool 注册和注销，BufferPool 数到 0 才真正释放。

sequenceDiagram    participant App as App 进程    participant Pool as BufferPool 服务    participant V as vendor 进程    V->>Pool: register(fd, BufferID=X)    V->>App: queue WorkBundle (含 BufferID=X)    App->>Pool: receive(BufferID=X)    Note over App: refcount(X) = 2    App->>App: 用户 releaseOutputBuffer    App->>Pool: postSendMessage(release, X)    Note over Pool: refcount(X) = 1    V->>Pool: postSendMessage(release, X)    Note over Pool: refcount(X) = 0 → 真正释放

之所以要单独做这层，是因为 Binder 自己的 fd 复制语义不带”全局引用计数”概念——A 关 fd 不影响 B 那边的 fd，但物理内存到底还在不在用，只看 fd 是不够的（fd 能复制无数份）。BufferPool 就在这上面补了一层全局账本。

第四篇queueInputBuffer走到这里能看到的是：releaseBuffer(buffer, &c2buffer, /*release*/ false)切出来的c2buffer一旦塞进WorkBundle，跨过 Binder 后 vendor 那边会收到一份”已注册的”C2Buffer——背后就是 BufferPool 在管着。

跨进程之后：vendor 进程的处理

前面三节分别讲了 App 进程内部的序列化、BufferPool 的引用计数、跨过 binder 之后的解封装——这些片段拼起来才是一帧完整的”App → vendor”路径。先把它们叠成一张端到端的时序图，再回来看 vendor 这一侧的细节：

sequenceDiagram    participant CC as CCodecBufferChannel
(App 进程)    participant CL as Codec2Client::Component
(App 进程)    participant BD as binder driver
(kernel)    participant ST as BnComponent stub
(vendor 进程)    participant CI as ComponentImpl::queue
(vendor 进程)    participant WT as vendor 工作线程    CC->>CC: 构造 C2Work、填 frameIndex
切 C2Buffer 视图    CC->>CL: queue(&items)    CL->>CL: objcpy(C2Work → WorkBundle)
抽出 native_handle (fd)    CL->>BD: IComponent::queue(workBundle)    BD->>BD: 复制 fd 到目标进程    BD->>ST: onTransact(QUEUE)    ST->>CI: Component::queue(workBundle)    CI->>CI: objcpy(WorkBundle → C2Work)
按 fd 重建 C2Buffer    CI->>WT: queue_nb(入队后立即返回)    CI-->>BD: Status::OK    BD-->>CL: 同步返回    CL-->>CC: c2_status_t = C2_OK    Note over WT: 异步：取 work、调 VPU
填 worklet->output、回调 onWorkDone

图里的关键节点对应前面三节：objcpy两次（去程一次拆、vendor 一次装）来自”一次 queue 的进程内调用”；binder driver 复制 fd 的语义在”BufferPool”那节展开；queue_nb和异步工作线程就是这一节要讲的重点。

接着看 vendor 这一侧调用栈大致是：

[kernel: binder driver]
    ↓
BnComponent::onTransact          // HIDL/AIDL 自动生成的 stub
    ↓
Component::queue                 // HAL 接口实现层
    ↓
ComponentImpl::queue (vendor 实现) // 厂商私有逻辑
    ↓
C2Component::queue_nb            // 真正的组件入口（non-blocking）
    ↓
入队组件内部 work queue，立即返回

注意最后是queue_nb——non-blocking。vendor 这边收到WorkBundle、反序列化回C2Work列表、塞进自己的内部队列，整条链就立即沿着 Binder 返回了。真正的解码动作发生在 vendor 进程的另一条工作线程上：那条线程从队列里取C2Work，调 VPU 驱动 ioctl，硬件解码完成后，从输出 BlockPool 里分配一块 Graphic Block，构造C2Buffer填到worklet->output.buffers，置workletsProcessed = 1，然后通过 Listener 把这条C2Work回传。

这个分裂——“queue同步返回 + 解码异步进行 + onWorkDone异步回调”——是第四篇里反复说的”comp->queue()是 fire-and-forget”在协议这一层的具体形状。

onWorkDone 的回路

输出方向有一个不太直觉的点：onWorkDone这条回调链是 vendor 主动调 App，方向反过来。

flowchart TB    V["vendor 进程
解码完成、填好 worklet->output"]    L["IComponentListener::onWorkDone
(server->client 回调，HIDL/AIDL 都支持)"]    K["binder driver"]    P["App 进程
BnComponentListener::onTransact"]    O["objcpy(WorkBundle -> C2Work)
反序列化，重建 shared_ptr<C2Buffer>"]    C["CCodecBufferChannel::onWorkDone(workItems)"]    V --> L --> K --> P --> O --> C

要让 vendor 能”反过来”调 App，初始化时 App 这一侧得先把一个Listener注册过去。第四篇CCodec::start里那条不起眼的注释”订阅事件”做的就是这件事——App 进程构造一个BufferPoolSender + Listener远端对象，通过 HIDL/AIDL 发到 vendor 那边，vendor 拿着这个 binder proxy 在解完一帧后回调。

输出 buffer 的零拷贝分配也是这一步的关键。回想一下第四篇CCodec::configure第 6 步：mChannel->setSurface(surface)。它干的事是创建一个BUFFERQUEUE 类型的C2BlockPool，把 Surface 的IGraphicBufferProducer挂上去。这个 pool 的 handle 跨进程发到 vendor 之后，vendor 解码出每帧 YUV 时，从这个 pool 里fetchGraphicBlock——内部直接走到 SurfaceFlinger 的 BufferQueue，dequeue 出一个真正的GraphicBuffer slot。

也就是说，vendor 解码出来的那块 YUV 内存，物理上一开始就分配在 SurfaceFlinger 的 BufferQueue 里。C2Buffer只是它在 vendor 进程里的一个引用视图。onWorkDone回到 App 那一刻，BufferChannel 拿到的是同一块内存的另一个视图。等到renderOutputBuffer把它queueBuffer给 BufferQueue 时，Consumer 那边发现”这块 slot 我之前给出去过、现在又回来了”，直接 latch 即可——全程没有一次内存拷贝。

vendor 解码 → SurfaceFlinger 显示，三个进程之间走的是同一块物理内存的不同视图，靠 fd + BufferPool + BufferQueue 三套机制接力。

总结

这一篇沿着第四篇结尾mComponent->queue()那行，跨过进程边界把整条协议链拆开来看：

• C2Work是 HAL 唯一的输入单元，input + worklets两段、各自一个C2FrameData，靠frameIndex认领回路。worklets是预留的输出占位，由 vendor 回填。
• 跨进程靠的是WorkBundle序列化——shared_ptr<C2Buffer>本身不能传，能传的只有底层 ION/dma-buf 的native_handle。objcpy两端各做一次拆装，内存不动，引用计数靠 BufferPool 跨进程算。
• 解码输出的零拷贝靠 BUFFERQUEUE pool：configure阶段把 Surface 的 BufferQueue 包成C2BlockPool发给 vendor，vendor 解码时直接从 BufferQueue 拿 slot，物理内存全程不动，三个进程拿的都是同一块内存的不同视图。
• onWorkDone是 server→client 反向回调，依赖 App 注册的 Listener proxy。queue同步返回 + vendor 内部异步处理 + onWorkDone异步回传——这一对组合是 fire-and-forget 在协议层的具体形状。

MediaCodec 整条管线在 native 这一层的”零拷贝”不是一个孤立技巧，是C2BlockPool + BufferPool + BufferQueue三套机制叠出来的——前者管”内存来自哪”，中间管”还有谁在用”，后者管”显示端怎么接”。三层都用 fd 作为跨进程的硬通货，C++ 对象只是各自进程里的视图。

系列导读：第三篇把视角停在了MediaCodec.cpp的状态机，所有动作最后都落在一个sp<CodecBase> mCodec上。这一篇接着往下走，回答两个问题：

• mCodec 到底是 CCodec 还是 ACodec？谁来选、什么时候选？
• 进了 CCodec 以后，状态切换、buffer 进出、Surface 渲染——为什么要拆给两个类来做？

主角是CCodec与CCodecBufferChannel，加上贯穿全文的BufferChannelBase这个抽象。

CCodec 和 ACodec

第三篇里反复出现的mCodec，类型是抽象基类sp<CodecBase>

// MediaCodec.h
class MediaCodec : public AHandler {
    sp<CodecBase> mCodec;     // 状态机的所有动作最终都作用在它身上
    // ...
};

CodecBase在 AOSP 里有两个实现：旧路径的ACodec（OMX）和新路径的CCodec（Codec2）。具体走哪条由组件名决定：

// MediaCodec.cpp::GetCodecBase（约 L2358）
sp<CodecBase> MediaCodec::GetCodecBase(const AString &name, const char *owner) {
    if (owner) {
        if (strncmp(owner, "default", 8) == 0) {
            return new ACodec;                // 旧路径：OMX
        } else if (strncmp(owner, "codec2", 6) == 0) {
            return CreateCCodec();            // 新路径：Codec2
        }
    }
    if (name.startsWithIgnoreCase("c2."))   return CreateCCodec();
    if (name.startsWithIgnoreCase("omx."))  return new ACodec;
    return nullptr;
}

规则只有三条：

• 名字以c2.开头（例如c2.android.avc.decoder）走CCodec；
• 名字以omx.开头走ACodec；
• MediaCodecList里的 owner 字段也能直接指定。

Android 10 以后绝大多数 vendor 已经迁到 Codec2，本篇之后只看CCodec这条线。

CCodec 结构

打开mCodec之后，里面也不是一个职责无所不包的CCodec——MediaCodec真正持有的引用其实有两条：

// MediaCodec.h
class MediaCodec : public AHandler {
    sp<CodecBase>                       mCodec;          // CCodec / ACodec
    std::shared_ptr<BufferChannelBase>  mBufferChannel;  // CCodecBufferChannel / ACodecBufferChannel
};

// MediaCodec.cpp（约 L2482，进入 INITIALIZED 时）
mBufferChannel = mCodec->getBufferChannel();

mBufferChannel由CCodec::getBufferChannel()创建并返回，CCodec内部用成员mChannel持有同一个对象。Java 一侧通过 JNI 看到的”一个 codec 实例”，对应到 native 是两个对象、三条引用、一个工厂关系：

flowchart LR    MC["MediaCodec
(状态机)"]    CC["CCodec
(控制面)"]    BC["CCodecBufferChannel
(数据面)"]    HAL["Codec2 HAL
(vendor 进程)"]    MC -- "mCodec
start/stop/flush" --> CC    MC -- "mBufferChannel
queue/render/discard" --> BC    CC -- "mChannel
同一个实例" --> BC    CC -- "下发控制指令" --> HAL    BC -- "queue C2Work / 收 onWorkDone" --> HAL

MediaCodec不会通过mCodec间接搬 buffer——每帧queueInputBuffer直接打到mBufferChannel上；start / stop这种则走mCodec。两层在MediaCodec这里就分开了。

三个名字最容易混，先一次说清：

MediaCodec持有的类型是抽象BufferChannelBase，所以同一段上层代码在 OMX/Codec2 两条路径上是通用的——这条对偶后面会用到。

回到”为什么要拆”。CCodec和CCodecBufferChannel的职责切得很干净：

拆成两个类，背后有三条理由：

1. 变化频率不同。生命周期事件少且粗（一次start、一次stop），buffer 流转高频且细（每帧两次：queue + dequeue）。两者放一起会让加锁、等待、回调逻辑互相挤占。
2. 线程模型不同。CCodec跑在CCodecLooper这条配置线程上；CCodecBufferChannel的onWorkDone来自 HAL 回调线程；queueInputBuffer来自 App 线程。三条线索塞进同一个类里很难管。
3. 可替换性。MediaCodec持有的是BufferChannelBase这个接口，OMX 路径换成ACodecBufferChannel上层不用动一行。

打个比方：CCodec是发动机工厂的厂长，决定开工、停工、招人；CCodecBufferChannel是流水线，负责原料进入、成品产出。MediaCodec是总公司，下指令给厂长的同时，也要直接对接流水线的进出货。

CCodec 的初始化四步

从被构造出来到能跑第一帧，关键是四步：选中、allocate、configure、start。

Step 1：被MediaCodec选中。 GetCodecBase那段已经讲完——名字以c2.开头时返回CreateCCodec()，此后第三篇状态机里所有mCodec->xxx()都作用在该实例上。

Step 2：CCodec::allocate。

void CCodec::allocate(const sp<MediaCodecInfo> &codecInfo) {
    AString componentName = codecInfo->getCodecName();

    // 1. 获取 Codec2Client（单例，连接到 vendor 进程）
    std::shared_ptr<Codec2Client> client;
    std::shared_ptr<Codec2Client::Component> comp =
        Codec2Client::CreateComponentByName(
            componentName, mClientListener, &client);

    // 2. 把组件句柄交给 BufferChannel
    mChannel->setComponent(comp);

    // 3. 回调给 MediaCodec：onComponentAllocated
    mCallback->onComponentAllocated(componentName.c_str());
}

Codec2 路径上有四个名字会在后面反复出现，这里先简单介绍：

• C2 HAL：Android 8.0 以后编解码器实现搬出 mediaserver，住进独立 vendor 进程android.hardware.media.c2。这套跨进程接口就是 Codec2 HAL。
• Codec2Client：mediaserver 这一侧的 HAL 客户端代理，负责跨进程握手、查询 vendor 那边可用的 codec 列表。
• Codec2Client::Component：通过Codec2Client拿到的”远端句柄”，对应 vendor 进程里某个具体 codec。CCodec后续所有start / queue / flush都通过它转发过去。
• C2Component：上面那个句柄对应的、住在 vendor 进程里的真正实例，是干活的对象。

知道这四个名字，Step 2 这一步做的事就清楚了：通过Codec2Client跨进程连上 vendor 的 C2 HAL 服务 → 让 vendor 按名字（如c2.android.avc.decoder）创建C2Component → mediaserver 这边拿回Codec2Client::Component句柄交给mChannel持有 → 回调onComponentAllocated，MediaCodec状态机推到INITIALIZED。

Step 3：CCodec::configure。 大头工作集中在这里，一次调用要做 10 件事：

1. 把 Java MediaFormat翻成C2Param（几十个字段）；
2. 写入 width / height / color format 等基础参数；
3. 解析并设置色彩元数据（C2StreamColorAspectsInfo）；
4. 解析 HDR 静态/动态元数据；
5. 处理 SPS/PPS csd-0 / csd-1；
6. 设置输出 Surface（mChannel->setSurface）；
7. 反向查询组件实际配置（vendor 可能改写）；
8. 创建输入/输出 BlockPool；
9. 处理 low-latency / tunneling 等特殊模式；
10. 回调onComponentConfigured。

源码位置：CCodec.cpp::configure，约从 L1400 开始的 600 多行。这里只点一条最容易踩的：第 7 步会把组件回填后的格式重新写回outputFormat，所以 Java 侧getOutputFormat()拿到的不是用户原始MediaFormat，而是 vendor 协商后的版本。

Step 4：CCodec::start。

void CCodec::start() {
    // 1. 启动组件（让 vendor 进程开始干活）
    c2_status_t err = comp->start();

    // 2. 启动 BufferChannel：分配 buffer pool、把 input/output 的 slot 备好
    mChannel->start(inputFormat, outputFormat, buffersBoundToCodec);

    // 3. 订阅事件：C2Component 通过 Listener 回调 onWorkDone / onError / onTripped
    //    这三条回调走的是 BufferChannel 不是 CCodec

    // 4. 回调 MediaCodec
    mCallback->onStartCompleted();
}

到这一步，控制面（CCodec）的工作基本就交完了。后面每帧的 queue/dequeue/render 跟CCodec不再发生关系，MediaCodec直接打到mBufferChannel上。

CCodecBufferChannel 结构

CCodecBufferChannel内部状态分成Input和Output两块，各自带一把锁：

class CCodecBufferChannel : public BufferChannelBase {
    std::shared_ptr<Codec2Client::Component> mComponent;   // HAL 组件句柄

    Mutexed<Input>  mInput;     // 输入管道
    Mutexed<Output> mOutput;    // 输出管道

    std::shared_ptr<C2BlockPool> mInputAllocator;
    std::shared_ptr<C2BlockPool> mOutputSurfacePool;

    std::atomic_uint64_t mFrameIndex;   // 单调递增帧号，HAL 回调用它来配对
};

struct Input {
    std::unique_ptr<InputBuffers> buffers;
    size_t numSlots;
    std::shared_ptr<LocalBufferPool> bufferPool;
    sp<MemoryDealer> memoryDealer;
};

struct Output {
    std::unique_ptr<OutputBuffers> buffers;
    size_t numSlots;
    sp<Surface> surface;
    sp<IGraphicBufferProducer> bufferProducer;
};

几个抽象先一一对上：

Input和Output各自被Mutexed<>包了一层，是因为queueInputBuffer来自 App 线程，onWorkDone来自 HAL 回调线程，renderOutputBuffer来自 App 线程，三条入口可能并发踩到同一份 slot 表。

输入路径：queueInputBuffer

App 调一帧queueInputBuffer(index, ...)后，进到CCodecBufferChannel：

status_t CCodecBufferChannel::queueInputBufferInternal(
        sp<MediaCodecBuffer> buffer,
        std::shared_ptr<C2BlockPool> encryptedBlockPool,
        sp<AMessage> outputFormat) {

    int64_t timeUs;
    buffer->meta()->findInt64("timeUs", &timeUs);

    // 1. 构造 C2Work：Codec2 框架里"一次编解码任务"的描述对象，由 input（数据 + 时间戳 +
    //    序号 + 配置更新）和 worklets（HAL 回填的输出占位）两部分组成。
    std::unique_ptr<C2Work> work(new C2Work);
    work->input.ordinal.timestamp     = timeUs;
    work->input.ordinal.frameIndex    = mFrameIndex++;   // 给 HAL 回调认领用
    work->input.ordinal.customOrdinal = timeUs;

    // 2. 把 MediaCodecBuffer 视图切到 C2Buffer 视图（同一块共享内存，零拷贝）
    if (eos) work->input.flags = C2FrameData::FLAG_END_OF_STREAM;
    if (csd) work->input.flags = C2FrameData::FLAG_CODEC_CONFIG;

    std::shared_ptr<C2Buffer> c2buffer;
    mInput.lock()->buffers->releaseBuffer(buffer, &c2buffer, /*release*/ false);
    if (c2buffer) work->input.buffers.push_back(c2buffer);

    // 3. 加一个空 worklet，HAL 处理完后会把输出回填进来
    work->worklets.emplace_back(new C2Worklet);

    // 4. 跨进程投递给 vendor 进程
    std::list<std::unique_ptr<C2Work>> items;
    items.push_back(std::move(work));
    c2_status_t err = mComponent->queue(&items);

    return err == C2_OK ? OK : UNKNOWN_ERROR;
}

四步里有三个细节决定了后续路径：

• mFrameIndex++给的就是配对凭证。HAL 回来时只带这个 frameIndex，BufferChannel 拿它和发出去时记下的映射表对一下，才能找回当时是哪个 input buffer、对应哪个 output slot。
• releaseBuffer不释放内存。它做的事是把MediaCodecBuffer切成C2Buffer视图——底层是同一块 ION/dmabuf，MediaCodecBuffer是给 Java/Native 客户端读写用的视图，C2Buffer是给 HAL 跨进程用的视图。第二个参数release=false表示这次只是”借”出去给 HAL，不归还 slot。
• comp->queue()是 fire-and-forget。Binder 调过去就返回，不等结果。HAL 处理完通过 Listener 回调onWorkDone，在另一条线程上。这条 fire-and-forget 是状态机能保持流畅的关键——queueInputBuffer不会被 vendor 慢解码拖住。

输出路径：onWorkDone

vendor 解完一帧，通过 Listener 回调到 BufferChannel：

void CCodecBufferChannel::onWorkDone(std::list<std::unique_ptr<C2Work>> workItems) {
    for (auto &work : workItems) {
        handleWork(std::move(work), outputFormat, initData);
    }
    feedInputBufferIfAvailable();   // 顺便看 input 还有没有空 slot 可以喂
}

void CCodecBufferChannel::handleWork(std::unique_ptr<C2Work> work, ...) {
    const auto &worklet = work->worklets.front();
    const auto &output  = worklet->output;

    if (output.buffers.size() > 0) {
        // 1. 拿到解码后的 C2Buffer（YUV graphic / 压缩 NAL linear）
        std::shared_ptr<C2Buffer> buffer = output.buffers[0];

        // 2. 反向切视图：注册到 OutputBuffers，分配 index 和 MediaCodecBuffer
        sp<MediaCodecBuffer> outBuffer;
        size_t index;
        mOutput.lock()->buffers->registerBuffer(buffer, &index, &outBuffer);

        // 3. 回调上层
        mCallback->onOutputBufferAvailable(index, outBuffer);
    }
}

这里的mCallback->onOutputBufferAvailable容易和 Java 层的MediaCodec.Callback.onOutputBufferAvailable同名打架——两个不是同一个东西：

• 这个mCallback类型是BufferCallback，是BufferChannel → MediaCodec的内部回调。无论同步还是异步模式都会触发。
• 它干的事只有一件：把index / buffer包成kWhatDrainThisBuffer消息，丢到MediaCodec自己的 Looper。

同步与异步的分叉发生在MediaCodec处理kWhatDrainThisBuffer时：

第三篇里讲过dequeueOutputBuffer怎么用PostAndAwaitResponse阻塞 + 条件变量唤醒——onWorkDone这条路径正好对接到那一头：HAL 回调线程把 buffer 写进可用队列后，给阻塞中的dequeueOutputBuffer线程发 reply，那边醒过来拿到 index 返回 Java。两层联动起来才是完整的同步语义。

渲染路径：renderOutputBuffer

Java 侧调releaseOutputBuffer(index, true)走的就是这一段：

status_t CCodecBufferChannel::renderOutputBuffer(
        const sp<MediaCodecBuffer> &buffer, int64_t timestampNs) {

    // 1. 反向切视图：从 MediaCodecBuffer 拿回 C2Buffer，并把这个 slot 还给 OutputBuffers
    std::shared_ptr<C2Buffer> c2Buffer;
    mOutput.lock()->buffers->releaseBuffer(buffer, &c2Buffer, /*release*/ true);

    // 2. 提取 HDR 元数据（C2StreamHdrStaticInfo / C2StreamHdr10PlusInfo）
    HdrStaticInfo  hdrStatic;
    HdrDynamicInfo hdrDynamic;
    // ...

    // 3. 从 C2 ColorAspects 读出 dataspace / crop / transform
    android_dataspace dataSpace = /* ... */;
    Rect              cropRect  = /* ... */;
    uint32_t          transform = /* ... */;

    // 4. 装进 BufferQueue 的 QueueBufferInput
    IGraphicBufferProducer::QueueBufferInput input(
        timestampNs,
        /*isAutoTimestamp=*/false,
        dataSpace,
        cropRect,
        NATIVE_WINDOW_SCALING_MODE_SCALE_TO_WINDOW,
        transform,
        Fence::NO_FENCE);     // 也可能从 C2Fence 提取
    input.setHdrMetadata(hdrMetadata);
    input.setSurfaceDamage(Region());

    // 5. 投递给 Surface（也就是 BufferQueue 的 Producer 端）
    IGraphicBufferProducer::QueueBufferOutput output;
    mOutputSurface->queueBuffer(slot, input, &output);
    return OK;
}

这一步是 MediaCodec 系列与图形管线系列的衔接点：左手收 vendor 解出来的 YUV GraphicBuffer，右手以 Producer 身份投给 SurfaceFlinger。HDR/crop/transform/fence 这些 side band 看起来杂，背后逻辑只有一句——BufferQueue 那边的 Consumer 不读C2Buffer，所有 vendor 想传给显示链的元信息，都得在这一步翻译成QueueBufferInput字段。

总结

本篇沿着第三篇结尾的mCodec，往下钻了一层，讲清三件事：

• CCodec 是怎么被选中的——名字以c2.开头就走CreateCCodec()，否则走ACodec；MediaCodecList的 owner 字段也能直接指定。
• CCodec 内部为什么再拆出 BufferChannel——变化频率、线程模型、可替换性三条理由都指向”控制面和数据面分开”。MediaCodec同时持有mCodec和mBufferChannel，控制走mCodec，每帧数据直接走mBufferChannel。
• 一帧解码在 BufferChannel 上的三段路径——queueInputBuffer把MediaCodecBuffer切成C2Buffer视图、打frameIndex后 fire-and-forget 投给 HAL；onWorkDone收到 HAL 回填、反向切回MediaCodecBuffer，再交给MediaCodec Looper 决定走同步还是异步路径；renderOutputBuffer把 HDR/crop/transform 翻成QueueBufferInput，以 Producer 身份接到 BufferQueue。

一句话收束：CCodec管开关，CCodecBufferChannel管搬运，BufferChannelBase是它们之间和 OMX 老路径之间唯一不变的契约——MediaCodec 在 native 这一侧的”控制 / 数据 / 抽象”三角，到这里就齐了。

系列导读：第二篇结尾留下一个钩子——真正的状态机在 Native 层，Java 侧只是个薄壳。这一篇沿着 codec.start()、dequeueOutputBuffer() 这种”看上去同步”的调用一路下钻，回答一个问题：

Java 的同步调用，在 JNI 之下到底是怎么落到 Native、又是怎么”原地等回结果”的？

主角是 AOSP foundation 库里那套 ALooper / AHandler / AMessage，加上 android_media_MediaCodec.cpp 这一层 JNI 桥。本篇刻意只聚焦同步 API 这一条链——异步 Callback（setCallback / onOutputBufferAvailable）不进行介绍。

1. 为什么 Native 不复用 Java 的 Looper

翻开 MediaCodec.cpp，start() 长这样：

status_t MediaCodec::start() {
    sp<AMessage> msg = new AMessage(kWhatStart, this);
    sp<AMessage> response;
    return PostAndAwaitResponse(msg, &response);
}

三行代码，三个问题：

• AMessage 不是 android.os.Message，那是什么？
• “同步调用”为什么长得像异步？
• 系统已经有 Java Looper 了，为什么还要在 Native 再造一套？

第三个问题先回答：AOSP 的 foundation 库早于 ART 存在，很多系统组件（mediaserver、cameraserver）跑在根本没有 JVM 的进程里。Java 的 Handler/Looper 需要 ART 支撑，Native 用不了。所以 AOSP 在 frameworks/av/media/libstagefright/foundation/ 下维护了自己的一套，名字都加了 A 前缀：

两套有一个关键差异：AMessage 不用 arg1 / arg2 / obj，用的是字典——setInt32("index", 3)/setInt64("timeUs", 100)/setObject("buffer", buffer)。好处是参数多了不用扩字段，坏处是取值要查表。

更重要的另一个差异：AMessage 原生支持同步等待，Java Handler 不支持。这是 PostAndAwaitResponse 能存在的基础。

2. CodecLooper：每个 codec 实例独享一条线程

每个 MediaCodec 实例在 Native 侧独享一个 Looper。初始化时会看到：

mCodecLooper = new ALooper;
mCodecLooper->setName("CodecLooper");
mCodecLooper->start(
    /* runOnCallingThread = */ false,   // 起新线程
    /* canCallJava        = */ false,
    ANDROID_PRIORITY_AUDIO);            // 优先级 -16
mCodecLooper->registerHandler(this);    // MediaCodec 自己是 AHandler

三个细节值得记：

3. PostAndAwaitResponse：同步感从哪里来

start() 内部投了一条消息就返回了，外层却”同步”拿到了结果。机制是这样的：

// 调用方：投完消息就在 token 上睡觉
PostAndAwaitResponse(msg, &response);

// 处理方：onMessageReceived 里干完活 postReply 唤醒对方
response->postReply(replyToken);

3.1 AReplyToken：一次调用的”信箱”

核心数据结构叫 AReplyToken，一个调用对应一个，只有三个字段：

token 自己不带锁。整个进程里所有 token 共用一把全局锁和一个全局条件变量，都挂在 gLooperRoster 单例上。唤醒时用 broadcast，被唤醒的线程自己检查 mReplied 是不是轮到自己。

3.2 核心逻辑

// 调用方
status_t ALooper::awaitResponse(const sp<AReplyToken> &replyToken, sp<AMessage> *response) {
    Mutex::Autolock autoLock(mRepliesLock);   // ① 锁住"回复"专用锁
    CHECK(replyToken != NULL);                // ② 校验 token 合法
    while (!replyToken->retrieveReply(response)) {   // ③ 循环尝试取回复
        {
            Mutex::Autolock autoLock(mLock);  // ④ 加另一把锁，检查 Looper 状态
            if (mThread == NULL) {
                return -ENOENT;               // ⑤ Looper 已停止 → 失败返回
            }
        }
        mRepliesCondition.wait(mRepliesLock); // ⑥ 条件变量阻塞，等待被唤醒
    }
    return OK;                                // ⑦ 成功拿到回复

// 处理方（在 Looper 线程 onMessageReceived 内）
status_t ALooper::postReply(const sp<AReplyToken> &replyToken, const sp<AMessage> &reply) {
    Mutex::Autolock autoLock(mRepliesLock);
    status_t err = replyToken->setReply(reply);     
    if (err == OK) {
        mRepliesCondition.broadcast();              // 唤醒
    }
    return err;
}

status_t AReplyToken::setReply(const sp<AMessage> &reply) {
    if (mReplied) {
        ALOGE("trying to post a duplicate reply");
        return -EBUSY;
    }
    mReply = reply;
    mReplied = true;
    return OK;
}

两个细节：

• broadcast 而不是 signal：一把条件变量看守所有 token，被唤醒的线程要自己检查 mReplied，不是自己就接着睡
• while 而不是 if：Condition::wait 从睡眠中返回，不代表”回复一定到了”——一方面 POSIX 允许虚假唤醒（没有任何 signal/broadcast 也可能自己醒），另一方面这里用的是 broadcast，别人收到回复时我也会被一起叫醒。所以必须用 while 包住 wait，醒来后重新检查 mReplied，没轮到自己就继续睡

3.3 一次 codec.start() 的完整时序

sequenceDiagram    participant App as App 线程    participant JNI as JNI (JMediaCodec)    participant Q as Looper Queue    participant L as CodecLooper 线程    App->>JNI: native_start()    JNI->>JNI: new AMessage(kWhatStart)    JNI->>JNI: createReplyToken + setReplyToken    JNI->>Q: msg.post()    JNI->>JNI: wait on mRepliesCondition    Q->>L: 取出 msg    L->>L: onMessageReceived: 推状态机到 STARTED    L->>L: postReply: 写信箱 + broadcast    L-->>JNI: 唤醒    JNI->>JNI: 读 mReply 得到 status_t    JNI-->>App: start() 返回 OK

注意整条链路上没有任何一把锁保护 mState：所有入口（App 线程、底层回调线程、Looper 自己）都只 post 消息，状态机只在 CodecLooper 这一条线程上读写——这是后面状态机能”无锁”的根本原因，第四篇会展开。

4. JMediaCodec：JNI 桥的薄壳

Java 侧 codec.start() 走的不是直接下 Native，而是经过一层 JMediaCodec：

Java: codec.start()
  └─ native_start()                          // JNI 入口
       └─ JMediaCodec::start()               // 持有 sp<MediaCodec>
            └─ mCodec->start()               // 真正的 Native 实现
                 └─ PostAndAwaitResponse     // 跨 Looper 线程

4.1 三层对象：谁是谁

讨论”codec.start() 在 JNI 之下发生了什么”之前，先把整条链路上到底有几个对象、各自归谁管画清楚——这张图后面整篇文章都会反复用到：

%%{init: {'flowchart': {'subGraphTitleMargin': {'top': 14, 'bottom': 14}, 'nodeSpacing': 50, 'rankSpacing': 70}}}%%flowchart LR    subgraph J["Java 层（ART）"]        JM["MediaCodec.java
mNativeContext: long"]    end    subgraph B["JNI 桥
android_media_MediaCodec.cpp"]        JNI["JMediaCodec
: public RefBase
sp<MediaCodec> mCodec"]    end    subgraph N["Native 层（libstagefright）"]        MC["MediaCodec.cpp
真正的状态机
持有 CodecLooper"]    end    JM -. "mNativeContext
存 JMediaCodec*" .-> JNI    JNI == "sp<> 强引用" ==> MC    classDef java fill:#BBDEFB,stroke:#1565C0,stroke-width:2px,color:#0D47A1    classDef jni fill:#FFF59D,stroke:#F57F17,stroke-width:2px,color:#3E2723    classDef native fill:#FFCC80,stroke:#E65100,stroke-width:2px,color:#BF360C    class JM java    class JNI jni    class MC native    style J fill:#E3F2FD,stroke:#1976D2,stroke-width:1.5px,color:#0D47A1    style B fill:#FFF9C4,stroke:#F9A825,stroke-width:1.5px,color:#5D4037    style N fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#BF360C

三个对象，一一对应不会变：

绑定关系靠 Java 侧的一个 private long mNativeContext 字段——里面存的就是 JMediaCodec* 指针的整数值（64-bit 系统下 8 字节）。native_setup 时通过 SetLongField 写入；之后每个 JNI 入口的第一步都是 getMediaCodec(env, thiz) 把这个 long 强转回 JMediaCodec* 用：

sp<JMediaCodec> codec = getMediaCodec(env, thiz);
if (codec == NULL) {
    throwExceptionAsNecessary(env, INVALID_OPERATION);
    return;
}
codec->start();   // 同步路径上 JNI 做的几乎就是这一件事

整个 android_media_MediaCodec.cpp 里 95% 的 JNI 入口都是这个模板：取 JMediaCodec → 调一次方法 → 把 status_t 翻成 Java 异常或返回值。本篇主线讲的”Java 同步调用怎么落到 Native”，这一层就是承接点，但本身没有任何业务逻辑。

4.2 唯一一把 sLock：与前文”无锁”形成对照

第 3 节强调过：Native 那一层的 mState 是无锁的，依靠 CodecLooper 单线程串行避免竞争。但翻开 JNI 文件，会看到一把全局静态锁：

static Mutex sLock;

static sp<JMediaCodec> getMediaCodec(JNIEnv *env, jobject thiz) {
    Mutex::Autolock _l(sLock);
    return (JMediaCodec*)env->GetLongField(thiz, gFields.context);
}

static sp<JMediaCodec> setMediaCodec(
        JNIEnv *env, jobject thiz, const sp<JMediaCodec> &codec) {
    Mutex::Autolock _l(sLock);
    sp<JMediaCodec> old = (JMediaCodec*)env->GetLongField(thiz, gFields.context);
    if (codec != NULL)  codec->incStrong(thiz);
    if (old != NULL)    old->decStrong(thiz);
    env->SetLongField(thiz, gFields.context, (jlong)codec.get());
    return old;
}

为什么 Native 都做到无锁了，JNI 这一薄层反而要加锁？因为这两层面对的调用者根本不一样：

具体的并发场景就是 release vs 其他方法。假设没有 sLock，两条线程会这样交错：

sequenceDiagram    participant A as 线程 A（release）    participant F as mNativeContext
（Java 字段）    participant B as 线程 B（queueInputBuffer）    A->>F: 读出 old 指针    B->>F: 读出同一个 old 指针    A->>A: old->decStrong()
JMediaCodec 析构    A->>F: 写入 nullptr    Note over B: B 手里的指针已经悬空    B->>B: codec->queueInputBuffer(...)
use-after-free

问题点很清楚：A 还没把字段清空、对象还没析构之前，B 已经把指针读走了；等 A 析构完，B 手上那份指针就成了野指针。

sLock 把 getMediaCodec 和 setMediaCodec 串起来后，B 只可能看到两种结果：

• 要么 A 还没开始：B 拿到一个完整的 sp<JMediaCodec>，sp<> 一旦构造就持有强引用，A 那边的 decStrong 至多让引用计数减 1，对象不会在 B 手里被析构；
• 要么 A 已经做完：B 拿到 nullptr，提前返回错误。

两种结果都安全，不会出现”拿到一个正在死的对象” 这种中间态。

注意这把锁只保护 mNativeContext 这一个 8 字节字段——一进一出粒度极小，对吞吐几乎没影响。真正的状态机仍然在下层用消息驱动维持无锁。可以这样记：

JNI 这一层的 sLock，护的是”Java 对象 ↔ Native 对象的指针绑定”；
Native 那一层的无锁，靠的是”所有改动都走 Looper 串行”。
两层各管各的，组合起来就是 MediaCodec 那种”看上去多线程随便调，实际从不出竞争”的体验。

（JMediaCodec 还承担第二件事——把 Native 事件反向转回 Java Callback——那是异步 API 的路径，涉及 Global Ref、AttachCurrentThread、jmethodID 缓存等一整套 JNI 跨语言回调技巧，本篇不展开。）

5. 一次完整闭环：dequeueOutputBuffer

看一次 dequeueOutputBuffer 这个带 timeout 的同步 API 的完整来回，把前面所有零件串起来：

sequenceDiagram    participant App as App 线程    participant JNI as JMediaCodec    participant MC as MediaCodec.cpp    participant CL as CodecLooper    App->>JNI: dequeueOutputBuffer(timeout)    JNI->>MC: mCodec->dequeueOutputBuffer    MC->>CL: post kWhatDequeueOutputBuffer    MC->>MC: PostAndAwaitResponse 阻塞    Note over CL: 队列里没有可用 buffer 就先不回    Note right of CL: 底层数据准备好后
另一条消息入队    CL->>CL: 把 buffer 放进 mAvailPortBuffers    CL->>CL: 取出之前 pending 的 dequeue msg 处理    CL->>MC: postReply（携带 index）    MC-->>JNI: 条件变量唤醒    JNI-->>App: 返回 index

两条关键：

• 带 timeout 的同步等待：PostAndAwaitResponse 内部走条件变量的 timed wait——超时直接返回 INFO_TRY_AGAIN_LATER，不等到天荒地老
• 消息按 FIFO 串行处理：dequeue msg 投早了没数据就先挂着，等数据到位的消息进来后被一并取出来回复。整条同步语义不依赖任何锁保护字段，全靠 CodecLooper 单线程串行 + token 唤醒

总结

本篇沿着一次”看上去同步”的 Java 调用下钻到 Native 侧，讲清了四件事：

• AOSP 为什么自造 A 系列原语（ALooper / AHandler / AMessage），以及和 Java Handler 的关键差异——原生支持同步等待
• CodecLooper 如何用”每实例一条线程串行处理”换来状态机的天然无锁
• PostAndAwaitResponse 怎样通过 AReplyToken + 条件变量，把异步消息包装成 Java 看到的”同步调用”
• JMediaCodec / sLock 为什么只锁 mNativeContext 一个字段，就能避免 release 与并发调用之间的 use-after-free

一句话收束：下层 Looper 串行做到无锁，上层 JNI 只锁一个字段防悬空——这就是 MediaCodec 同步 API 在 Native 侧的全部秘密。

一句话理解 MediaCodec

MediaCodec 是一台带缓冲池的状态机：

• 状态机决定”你现在能做什么”——错了就抛 IllegalStateException；
• 缓冲池是 App 与底层 codec 之间的传送带——你租一个 buffer、填数据、还回去；底层处理完再租一个 buffer、拿数据、你还回去。

MediaCodec 状态机

用一张官方的图来展示 MediaCodec 的声明周期：

当通过任一工厂方法创建编解码器时，编解码器处于未初始化状态。首先需要通过 configure(…) 完成配置，该方法会将其切换至已配置状态；随后调用 start()，便可进入执行状态。在执行状态下，你就可以通过前文所述的缓冲区队列操作来进行数据处理。

执行状态包含三个子状态：刷新态（Flushed）、运行态（Running）和流结束态（End-of-Stream）。调用 start() 后，解码器会立即进入刷新子状态，此时它持有所有缓冲区。一旦取出第一个输入缓冲区，编解码器就会切换至运行子状态，这也是其最主要的工作状态。当你向输入缓冲区带入流结束标记并送入队列时，编解码器会切换到流结束子状态。在此状态下，编解码器不再接收新的输入缓冲区，但仍会持续生成输出缓冲区，直到输出端数据流收尾完成。对于解码器而言，只要处于执行状态下，随时都可以调用 flush() 回到刷新子状态。

调用 stop() 可将编解码器回归未初始化状态，之后可重新对其进行配置。使用完毕后，必须调用 release() 释放编解码器资源。

详细的内容可以查看MediaCodec#states一节。

完整状态图

stateDiagram-v2    [*] --> Uninitialized: new / createByXxx()    Uninitialized --> Configured: configure()    Uninitialized --> Released: release()    Configured --> Uninitialized: reset()    Configured --> Released: release()    Configured --> Executing: start()    state Executing {        [*] --> Flushed        Flushed --> Running: queueInputBuffer()        Running --> Running: queue/dequeue        Running --> EndOfStream: queueInputBuffer(EOS)        EndOfStream --> Flushed: flush()        Running --> Flushed: flush()        Flushed --> Flushed: flush()    }    Executing --> Uninitialized: stop()    Executing --> Released: release()    Executing --> Error: 任何调用失败    Error --> Uninitialized: reset()    Error --> Released: release()    Released --> [*]

一个被忽略的细节：真正的状态机在 Native 层 (MediaCodec.cpp)，Java 侧只是个”薄壳”。这也是为什么 MediaCodec.CodecException 会带上 errorCode——错误是从 native 甚至 HAL 层反射上来的。

一个最小闭环 MediaCodec 示例（解码 + 渲染到 Surface，同步模式）

先给个能跑的代码，脑子里有个整体印象再往下看，后续所有 native 的相关的解释都与下面的代码有关。

val extractor = MediaExtractor().apply { setDataSource(path) }
val trackIdx = (0 until extractor.trackCount).first {
    extractor.getTrackFormat(it).getString(MediaFormat.KEY_MIME)!!.startsWith("video/")
}
extractor.selectTrack(trackIdx)
val format = extractor.getTrackFormat(trackIdx)

val codec = MediaCodec.createDecoderByType(format.getString(MediaFormat.KEY_MIME)!!).apply {
    configure(format, outputSurface, null, 0)   // 渲染到 Surface
    start()
}

val info = MediaCodec.BufferInfo()
var inputDone = false
val startNs = System.nanoTime()

while (true) {
    // 1. 喂输入
    if (!inputDone) {
        val inIdx = codec.dequeueInputBuffer(10_000)
        if (inIdx >= 0) {
            val buf = codec.getInputBuffer(inIdx)!!
            val size = extractor.readSampleData(buf, 0)
            if (size < 0) {
                codec.queueInputBuffer(inIdx, 0, 0, 0, MediaCodec.BUFFER_FLAG_END_OF_STREAM)
                inputDone = true
            } else {
                codec.queueInputBuffer(inIdx, 0, size, extractor.sampleTime, 0)
                extractor.advance()
            }
        }
    }

    // 2. 取输出
    when (val outIdx = codec.dequeueOutputBuffer(info, 10_000)) {
        MediaCodec.INFO_TRY_AGAIN_LATER -> { /* 继续转 */ }
        MediaCodec.INFO_OUTPUT_FORMAT_CHANGED -> {
            Log.d(TAG, "output format = ${codec.outputFormat}")
        }
        else -> if (outIdx >= 0) {
            // 按 PTS 精确送显，实现音画同步
            val renderAtNs = startNs + info.presentationTimeUs * 1000L
            codec.releaseOutputBuffer(outIdx, renderAtNs)

            if (info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0) break
        }
    }
}

codec.stop(); codec.release()
extractor.release()

不到 40 行，就是一个能用的硬解播放内核。编码器的骨架和它镜像——把 extractor 换成 GPU 画 Surface，把 releaseOutputBuffer 换成 MediaMuxer 写流。

API 全景：一个生命周期流水线

把所有常用 API 按调用顺序串起来，就是下面这张流水线：

flowchart TB    S1["1. 创建
createDecoderByType / createEncoderByType
createByCodecName"]    S2["2. 注册回调（可选）
setCallback
异步模式必调，且必须在 configure 之前"]    S3["3. 配置
configure(format, surface, crypto, flags)"]    S4["4. 启动
start()"]    subgraph LOOP["5. 运行循环"]        direction LR        IN["喂输入
dequeueInputBuffer
↓
getInputBuffer
↓
queueInputBuffer"]        OUT["取输出
dequeueOutputBuffer
↓
getOutputBuffer
↓
releaseOutputBuffer"]        MID["中途可调
flush · setParameters
getOutputFormat
signalEndOfInputStream"]        IN -.并行.- OUT        OUT -.-> MID    end    S6["6. 清理
stop() / reset() / release()"]    S1 --> S2 --> S3 --> S4 --> LOOP --> S6    classDef phase fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#000    classDef ioBox fill:#FFF9C4,stroke:#F9A825,stroke-width:1.5px,color:#000    classDef midBox fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#000    classDef endBox fill:#FFCDD2,stroke:#C62828,stroke-width:2px,color:#000    class S1,S2,S3,S4 phase    class IN,OUT ioBox    class MID midBox    class S6 endBox

Flush / Stop / Reset / Release

同步 vs 异步模式

规则很硬：setCallback 之后，同步的 dequeueXxx 就禁用了，调一次抛一次 IllegalStateException。

总结

回到开篇那句话——MediaCodec 是一台带缓冲池的状态机。

状态机决定你”现在能调什么”：configure → start → queue/dequeue → stop/release 是主干，flush 在 Executing 内部腾挪，reset/release 负责兜底和终结。调错顺序 → IllegalStateException。
缓冲池决定你”怎么交换数据”：dequeue → get → queue/release 是三步闭环，每租必还，PTS 单调，EOS 用 flag 而不是 API。忘了 release → buffer 枯竭卡死。

系列导读：本系列将从 Kotlin/Java 应用层出发，一路向下，穿越 JNI、Native framework、Codec2、HAL、驱动，直至 SoC 内部的 VPU/GPU/NPU 硬件电路，完整拆解一帧视频从磁盘到屏幕的代码链路与数据流转。

本文是第 1 篇 · 开篇总览，不涉及具体代码细节，目的是建立一张「全景地图」，让你知道自己在下面哪一层、该往哪个方向挖。

一、为什么要写这个系列

过去这些年，我对 MediaCodec 的理解基本停留在 API 使用层面——知道怎么在多个线程间（音频解码线程、视频解码线程、UI线程）串起整个流程，能理解与 MediaExtractor、AudioTrack、MediaMuxer 之间的协作，也了解 H264 的理论原理相关，但一旦有比较深入地问下去，我就答不上来了：

• queueInputBuffer 之后，那段 H.264 码流到底经过了几个进程？
• “硬解”到底是谁在解？ACodec、CCodec、OMX、Codec2 它们是什么关系、又是怎么演化出来的？
• 为什么 Surface 输出可以”零拷贝”？这个”零”是真的零，还是营销话术？
• DMA-BUF、fence、Gralloc、BufferQueue 这些名词我都听过，但它们到底怎么咬合在一起？
• 走到最底下，VPU 这颗硬件电路，是怎么被 App 的一行 Kotlin 代码”遥控”起来的？

这些问题或者遇到疑难 bug（偶现花屏、特定机型掉帧、跨设备兼容性），没有底层视角，只能靠猜；遇到性能优化，没有全链路认知，也只能做一些表面功夫。

去翻市面上的 MediaCodec 文章，大多数是”十分钟入门”的——贴一段 demo 代码、列一下状态机、讲讲同步 vs 异步模式，就结束了。这些内容对刚入门的人有用，但对已经写了几年音视频的人，信息密度低到几乎为零，而且彼此之间高度同质化。
真正能把「App 代码 → JNI → Native framework → HAL → 驱动 → 硬件」这条链路一路贯通的文章比较少。毕竟很少人对这所有的方面都了解，做底层硬件的可能不太了解上层的应用，做应用的不太了解硬件底层的逻辑。好在当前 AI 的发展帮忙能够比较好地去学习了解这些问题了，本系列文章很多资源内容也是借助 AI 搜集整理资料的能力完成的。

本系列试图做的事：不讲解如何使用 MediaCodec，只讲解原理相关。把安卓音视频碎片串成一条完整的链路，从 App 代码一行一行地跟踪到硬件寄存器，知其然更知其所以然。

适合读这个系列的人

前置要求：

• 对音视频编码基础了解，强烈推荐这个项目提供的内容 digital_video_introduction
• 能读懂中等难度的 C/C++
• 熟悉 Kotlin/Java 语法，了解 MediaCodec 的基本使用
• 对”线程”、”IPC”、”进程”有基本概念

一个直击灵魂的提问

在正式展开之前，先做一个思想实验。假设你写了如下最朴素的播放代码：

val extractor = MediaExtractor().apply { setDataSource("/sdcard/demo.mp4") }
val format = extractor.getTrackFormat(videoTrackIndex)
val codec  = MediaCodec.createDecoderByType("video/avc").apply {
    configure(format, surfaceView.holder.surface, null, 0)
    start()
}
// ... queueInputBuffer / releaseOutputBuffer ...

点击运行，屏幕上出现了画面。

问题来了：从你调用 releaseOutputBuffer(index, true) 那一刻算起，到这一帧的像素真正点亮 LCD 的某一行，中间发生了多少次进程切换、多少次内存拷贝、多少次 CPU ↔ GPU ↔ VPU 协同？

答案是：

0 次像素拷贝（理想情况）、3 次跨进程、7 次关键跳跃、至少 4 种硬件单元参与。

看不懂这些数字没关系——整个系列就是用来解释它们的。为什么要知道这些？

《SICP》里面的核心思想 “程序即数据，数据即程序，二者边界模糊，所有计算机程序存在的目的都是为了处理、转换或构造数据，最终达到对复杂系统进行抽象和模拟的目的”。对于我们来讲只要能理解各个数据的流向就能理解整个系统。

二、MediaCodec 的真实身份

4.1 它是什么？

MediaCodec 不是一个解码器，而是 Android 为你提供的”访问解码/编码硬件”的统一 API 门面。

更准确地说：MediaCodec 是一个字节流的状态机 + 缓冲池的调度器。

它自己不懂 H.264，不懂 HEVC，不懂 AV1。它做的事情是：

1. 接管你塞进来的一段输入字节（可能是 H.264 的一个 NAL、也可能是 AAC 的一帧）；
2. 把它交给真正懂这种格式的后端实现（ACodec/OMX 或 CCodec/Codec2）；
3. 后端再通过 HAL 把数据推给硬件电路（VPU）或软件库（如 libavcodec）；
4. 拿回解码好的 YUV，通过输出 Buffer 或 Surface 交还给你。

4.2 它不是什么？

4.3 一个比喻

把 MediaCodec 想象成麦当劳的点餐柜台：

• 你（App）只管点一个”巨无霸”（送入 H.264 码流）
• 柜台（MediaCodec）把订单传到后厨（Codec2/ACodec）
• 后厨可能让烤箱（VPU）或者人工厨师（CPU 软解）来做
• 做好的汉堡（YUV 帧）通过传送带（BufferQueue）送到你面前
• 整个过程你看不见厨房内部，但知道下单的 API 长什么样

系列后续的工作，就是掀开厨房的帘子，逐个工位讲清楚。

三、MediaCodec 全链路

六层架构速览

flowchart TB    subgraph L1["🟦 L1 · Java API"]        A1["📱 App 进程
━━━━━━━━━━━━━━
MediaCodec.java
MediaExtractor · MediaMuxer
Surface · SurfaceTexture"]    end    subgraph L2["🟩 L2 · JNI 桥接"]        B1["📱 App 进程
━━━━━━━━━━━━━━
android_media_MediaCodec.cpp
JMediaCodec 包装对象
ByteBuffer · Surface 跨界"]    end    subgraph L3["🟨 L3 · Native Framework"]        direction LR        C1["ACodec
━━━━━━━━
OMX 路径
legacy"]        C0["⚙️ mediacodec 进程
━━━━━━━━━━━━━━
MediaCodec.cpp
ALooper + AHandler
状态机"]        C2["CCodec
━━━━━━━━
Codec2 路径
modern"]        C0 -.-> C1        C0 -.-> C2    end    subgraph L4["🟧 L4 · HAL 层"]        direction LR        D1["🔧 vendor 进程
━━━━━━━━━━━━
OMX HAL
IOMX.hal"]        D2["🔧 vendor 进程
━━━━━━━━━━━━
Codec2 HAL
IComponentStore.aidl"]    end    subgraph L5["🟥 L5 · Kernel 驱动"]        E1["🐧 内核态
━━━━━━━━━━━━━━━━━━━━
V4L2 · ION · DMA-BUF · iommu"]    end    subgraph L6["🖤 L6 · SoC 硬件"]        direction LR        F1["💻 CPU
━━━━
控制
软解"]        F2["🎬 VPU
━━━━
硬件
编解码"]        F3["🎨 GPU
━━━━
OES 纹理
Shader"]        F4["🧠 NPU/DSP
━━━━━━
AI 超分
插帧"]        F5["📺 DPU/HWC
━━━━━━
屏幕合成"]    end    A1 --> B1    B1 --> C0    C1 --> D1    C2 --> D2    D1 --> E1    D2 --> E1    E1 --> F1    E1 --> F2    E1 --> F3    E1 --> F4    E1 --> F5    classDef l1 fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#000    classDef l2 fill:#E8F5E9,stroke:#388E3C,stroke-width:2px,color:#000    classDef l3 fill:#FFF9C4,stroke:#F9A825,stroke-width:2px,color:#000    classDef l4 fill:#FFE0B2,stroke:#EF6C00,stroke-width:2px,color:#000    classDef l5 fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,color:#000    classDef l6 fill:#FFCDD2,stroke:#C62828,stroke-width:2px,color:#000    class A1 l1    class B1 l2    class C0,C1,C2 l3    class D1,D2 l4    class E1 l5    class F1,F2,F3,F4,F5 l6

各层职责一览

三个最昂贵的跨越（对性能影响最大）：

1. L2 → L3 — App 进程 → mediacodec 进程（Binder IPC）
2. L3 → L4 — mediacodec 进程 → vendor 进程（HIDL/AIDL 跨进程）
3. L4 → L5 — 用户态到内核态（ioctl/syscall）

一个隐藏知识点：Android 8.0（Treble）之后，MediaCodec 被拆到独立进程 mediacodec 中运行，这是为了应对 StageFright 漏洞（CVE-2015-1538）的历史教训——用进程沙箱换安全性，代价是多一次 Binder 调用。

一帧数据的”七次跳跃”

用一张”一帧生命周期”时序图来串联上面六层：

sequenceDiagram    autonumber    participant App as App 线程    participant JNI as JNI 层    participant MC as mediacodec 进程    participant HAL as vendor HAL 进程    participant VPU as VPU 硬件    participant GPU as GPU    participant SF as SurfaceFlinger    participant HWC as HWC/DPU    App ->> JNI: 1. queueInputBuffer(H.264 NAL)    JNI ->> MC: 2. Binder IPC（kWhatQueueInputBuffer）    MC ->> HAL: 3. HIDL/AIDL（c2_queue）    HAL ->> VPU: 4. ioctl + DMA-BUF 描述符    Note over VPU: 硬件解码（几毫秒）
产出 YUV 到 DMA-BUF    VPU -->> HAL: 5. 中断 + dma-fence    HAL -->> MC: 6. 输出 GraphicBuffer    MC -->> JNI: 7. onOutputBufferAvailable    JNI -->> App: releaseOutputBuffer(true)    App ->> GPU: (可选) 特效渲染到 FBO    GPU ->> SF: queueBuffer 到 BufferQueue    SF ->> HWC: 合成（GPU 或 DPU 直出）    HWC -->> App: VSYNC · 像素点亮屏幕

对应的「7 次关键跳跃」是：

关键秘密：跳跃 3/4/5 是控制信号（很小，几百字节），跳跃 7 是像素数据（很大，Full HD 一帧 YUV420 约 3MB）——控制路径多次跨界没关系，像素路径一次拷贝都不能多。

这就是为什么 Android 花了十年打磨 Gralloc + BufferQueue + DMA-BUF + fence 这一整套”零拷贝基础设施”——我们会在 M6/M9 详细拆解。

硬件协同：一颗 SoC 是如何”开派对”的

很多人以为视频播放只是”解码 → 显示”两步。真实情况要热闹得多：

flowchart LR    MP4[MP4 文件] -->|demux| CPU1[CPU
解封装]    CPU1 -->|H.264 NAL| VPU[VPU
硬件解码]    VPU -->|YUV 帧| GPU[GPU
特效/色彩空间转换]    GPU -->|RGB 纹理| NPU[NPU
超分/插帧]    NPU -->|增强帧| DPU[DPU/HWC
合成]    DPU -->|扫描行| LCD[📺 屏幕]    CPU2[CPU
全局调度与 fence 等待] -. 控制 .- VPU    CPU2 -. 控制 .- GPU    CPU2 -. 控制 .- NPU    CPU2 -. 控制 .- DPU    style CPU1 fill:#E3F2FD,stroke:#1976D2    style CPU2 fill:#E3F2FD,stroke:#1976D2    style VPU fill:#FFCDD2,stroke:#C62828    style GPU fill:#FFF9C4,stroke:#F9A825    style NPU fill:#E8F5E9,stroke:#388E3C    style DPU fill:#FFE0B2,stroke:#EF6C00

五大硬件单元的「戏份」

关键洞察：

• 稳态播放时 CPU 几乎不干活 — 因为 VPU→GPU→DPU 之间通过 DMA-BUF + fence 自治流转
• GPU 有三种角色 — 特效处理（App 用）、色彩转换（SF 用）、合成 fallback（HWC 不能直出时兜底）
• NPU 是近 3 年才加入的新玩家 — 超分、插帧是最典型的业务

这些内容将在 M9 硬件分工全景 中用两万字铺开讲，包括为什么 HWC 能直出 NV12 而 App 层却必须经过 GPU。

解码与编码：两条相反的路

特效视频的核心链路是「解码 → 特效 → 编码」的一个完整闭环：

flowchart LR    A[MP4 输入] --> B[MediaExtractor]    B --> C[MediaCodec 解码器
硬解 → YUV]    C --> D[SurfaceTexture
OES 外部纹理]    D --> E[GPU Shader
LUT/滤镜/贴纸]    E --> F[MediaCodec 编码器
输入 Surface]    F --> G[H.264 码流]    G --> H[MediaMuxer]    H --> I[MP4 输出]    style C fill:#FFF9C4,stroke:#F9A825    style F fill:#FFF9C4,stroke:#F9A825    style E fill:#FFCDD2,stroke:#C62828

关键技巧：编码器的输入 Surface + 解码器的输出 SurfaceTexture 构成一条纯 GPU 零拷贝管线，整个路径 CPU 几乎不参与像素搬运。这是现代短视频 App 性能的秘密武器。

总结

MediaCodec 不是解码器，而是六层架构的门面：上层 API 一次调用，背后是 3 次跨进程、7 次关键跳跃、4 种硬件协同。其中前六跳传的是控制信号，最后一跳靠 DMA-BUF + fence 完成像素零拷贝——这正是 Android 花十年打磨出的护城河。看懂了这张地图，就能解释”硬解为何变软解”、”同样 1080p60 为何别人更省电”这类表层 API 问题。

接入前： 有清晰的文档能告诉我这个SDK 的环境要求，比如 minSdkVersion compileSdkVersion 这些硬性配置，明确列出所有直接 / 间接依赖的第三方库及版本，以及包大小、申请权限等。

接入中：接入需要足够简单，在 dependencies 中一行搞定；如果有初始化操作也尽量简洁，一行搞定；对应 SDK 调用 ，提供一个单例类或者某个接口，在这个类/接口里面能够看到最核心的 Api；使用的接口对各种异常处理有足够多的错误提示信息；针对输出日志能够有配置开关等。

接入后： SDK 由于功能需要更新，需提供详尽的 CHANGELOG，接入者只用更新版本号；

上面是站在接入者的角度去考虑的，作为SDK的开发者则应该遵循以下的规则。

先前原则

核心原则：以接入方体验为中心

在开发一个SDK的时候，把接入者当作“小白”，不寄希望于他能点进SDK内部，去了解内部的实现；把接入者视作“懒人”，他不想做太多事，他赖得看你代码里面的各种注释，只想看一份接入文档就搞定所有事情。

最小化原则：只暴露必要的内容

对外仅暴露核心入口类 + 必要数据类 + 统一结果类，内部工具类、中间逻辑、私有方法全部标记为private（Java）/internal（Kotlin），杜绝接入方依赖内部逻辑。

稳定性原则：避免崩溃，容错兜底

不要将你的SDK视为一个可以随时更新的应用程序，而应将其看作一旦上线就无法实时更新的后端服务。避免崩溃是第一前提，但不可能万无一失，会由于设备兼容性问题，没法在上线将所有情况全考虑到，那么需要SDK能够有兜底操作，比如某个开关能够关闭掉该功能，或者针对特定机型Android系统等进行屏蔽（需服务端配合）。

开发阶段

详细的文档

接入需要清晰、详细的文档，了解如何充分发挥 SDK 的能力。一份全面的文档需要包含：

• SDK开发环境要求

• SDK安装和配置的详细流程

• 核心 Api 使用的代码示例

• 有一个可进行索引的目录

安装和初始化

使用Maven Publish Plugin将 SDK 发布到 Maven 仓库，配置groupId/artifactId/version，确保接入方仅需一行implementation即可引入；

避免在 AndroidManifest.xml 中配置冗余内容，如需一些动态配置，提供Gradle 插件自动注入这些能力，无需接入方手动修改。

初始化的时候一行搞定，比如：XxxSdk.Builder().appKey("your_app_key").debugMode(true).build()

极简 API 设计

设计良好的 API 确保接入者能够轻松集成并使用你的 SDK 功能，避免不必要的复杂性。用 Kochava SDK 工程总监 Nathan Darst 的话说：

The developer wants to solve a problem, and the API should facilitate solving this problem quickly and intuitively with as few lines of code as possible. A good API prioritizes and focuses on the most common use cases; it is not muddied up with unnecessary, ambiguous, redundant, or rarely used functionality likely to confuse the user.

开发者的核心诉求是解决实际问题，而 API 的设计初衷，应是助力开发者用最少的代码、最直观的方式，快速解决问题。一个优质的 API，会优先聚焦并打磨最常用的核心使用场景；不会掺杂无关、模糊、冗余或极少用到的功能 —— 这类功能只会让使用者产生困惑。

更多的代码准则应参考谷歌官方：Android API 准则

轻量级 SDK

尽量减少外部依赖，尤其是核心功能方面。如果非得用第三方库（Gson、okhttp等），就把它们隔离出来，或者更好的是，让接入者选择排除或替换这些工具，或者参考koin，采用模块化架构允许仅集成所需的组件。

错误处理、调试、测试

当出现错误时，清晰且可作的响应帮助接入者快速识别并修复问题，减少挫败感，节省集成和故障排除的时间。尽可能将详细的错误返回或者在日志里面输出出来，不要只展示“未知错误”、”-1”、“errros”这些表达不明确的错误。

除了明确的错误信息提示外，还需要提供一些详细详细日志，且可配置。以视频渲染SDK为例，由于有多个线程参与，还有 GPU 参与，断点调试几乎不太可能，如果在每一帧都打印日志的话，又会得到大量冗余的信息，所以这里就需要日志输出可配置化。

为了更好地测试你的库，建议使用 依赖注入，这里以一份网络请求做对比->使用依赖注入和不使用依赖注入的两种实现对比

依赖注入通过解耦被测试类与具体依赖，实现依赖的灵活替换与精准模拟，让单元测试更可控、快速且用例间相互独立。

前后的兼容性

当 SDK 更新破坏现有 API 实现时，接入者会面临不必要的返工，通过保持向后兼容性，使接入者能够无缝采用新的 SDK 版本，同时不影响他们的工作流程。实现这一目标的一种广泛采用的策略是语义版本控制（SemVer）， 它采用三部分版本控制方案，清晰传达变更的范围和影响：

以 4.3.2 为例，4 是主版本号，其变更代表 SDK 出现了向后不兼容的破坏性修改，需适配调整才能使用；3 是次版本号，其变更为新增兼容式功能 / 特性，无需改动原有代码即可升级；2 是补丁版本号，其变更仅为兼容式 bug 修复，是最无风险的小版本升级。

其他

这里主要是一些琐碎点，或者能提供一些在SDK 开发过程中的帮助

多利用语言特性

目前我遇到的利用 kotlin 特性最好的开源库是 koin，使用了大量的高阶函数 & Lambda 表达式，比如：高阶函数 / Lambda实现简洁的 DSL 模块定义（module { … }），委托属性实现by inject() 延迟获取依赖，协程支持协程作用域、挂起函数创建依赖等

演示代码片段：koin使用到 kotlin 的一些特性

善于使用脚本

脚本可以帮助开发者实现很多重复工作，包括不限于：Android SDK 一键编译打包（AAR/JAR）、多版本编译（测试不同 Kotlin/AGP 版本）、自动更新 SDK 版本号、生成版本日志（结合 Git 提交记录）、测试自动化等，这里面有很多可以使用 Gradle脚本，有的也可使用 Shell 脚本。

其他持续补充……

总结

本人结合个人Android SDK开发经验，好用的SDK需围绕接入方体验、稳定性设计：接入前有清晰文档，接入中极简便捷，接入后无缝升级。开发者需遵循接入方体验为中心、最小化暴露、稳定性兜底三大原则，开发中做好文档、安装初始化、API设计等核心工作，善用Kotlin特性与自动化脚本。本文为个人经验总结，因SDK开发场景多样，不适用于所有情况，仅供学习参考。

参考

Building great SDKs

SDK Development; The Good, The Bad, The Ugly

SDK design best practices

Mobile SDK Development Guidelines

Android SDK开发艺术探索（一）开篇与设计

Building Better SDKs

一维离散余弦变换

一维 DCT 将一个长度为 N 的信号序列（例如一行像素值）从空间域转换到频域。最常用的是 DCT-II 类型，这也是 JPEG 标准所使用的。

正变换： 从空间域到频域

其中：

• $f(x)$ 是输入信号在位置 $x$ 的值（例如，像素亮度）。
• $F(u)$ 是变换后得到的第 $u$ 个频率分量（DCT 系数）。
• $N$ 是信号的长度（在 JPEG 中，通常是 8）。
• $u$ 是频率索引，$u = 0, 1, \dots, N-1$。
• $x$ 是空间位置索引，$x = 0, 1, \dots, N-1$。
• $C(u)$ 是一个归一化系数，定义为：

关键点：

• 当 $u = 0$ 时，$F(0)$ 被称为 直流系数。它实际上是整个信号块的平均值。
• 当 $u > 0$ 时，$F(u)$ 被称为 交流系数。它们代表了信号中不同频率的振荡模式。$u$ 越大，代表的频率越高。

二维离散余弦变换

JPEG 将图像分割成 8x8 的小块，然后对每个块独立进行二维 DCT。二维 DCT 可以看作先对每一行进行一维 DCT，然后再对每一列进行一维 DCT（顺序可互换）。

正变换： 从空间域到频域

其中：

• $f(x, y)$ 是 8x8 图像块中在位置 $(x, y)$ 的像素值。在计算前，通常会先将像素值减去 128（即 -128 到 127 的范围），使其围绕零对称。
• $F(u, v)$ 是变换后得到的在频率 $(u, v)$ 上的 DCT 系数。
• $N = 8$（对于标准的 JPEG）。
• $u, v$ 是频率索引，$u, v = 0, 1, \dots, 7$。
• $x, y$ 是空间位置索引，$x, y = 0, 1, \dots, 7$。
• $C(u)$ 和 $C(v)$ 的定义与一维情况相同：

同理于 $C(v)$。

关键点：

• $F(0, 0)$ 是 直流系数，代表整个 8x8 块的平均亮度。
• 所有其他的 $F(u, v)$ 都是 交流系数。
• 系数 $F(u, v)$ 的 $u$ 和 $v$ 值越大，代表在水平和垂直方向上的频率越高。
• 在变换后的 8x8 系数矩阵中，左上角是低频系数，右下角是高频系数。图像的大部分能量（信息）都集中在低频区域，这是 JPEG 能够实现高压缩比的关键。

逆离散余弦变换

为了从频域数据重建图像，需要使用逆 DCT。

逆变换： 从频域回到空间域

公式中的各项含义与正变换完全相同。

简单理解

DCT的本质与核心直觉

DCT可以看作离散傅里叶变换（DFT）的一种特殊形式，主要处理实数信号，并且有很好的能量集中特性。

它的核心思想是：任何一个8x8的像素块，都可以看作是64种不同频率的标准余弦波（即“基础图案”）按照特定权重（也就是DCT系数）叠加而成的。

在这些基础图案中：

• 低频成分（对应于系数矩阵左上角，u和v值较小的部分）代表了图像块的大致轮廓和平滑变化的背景。

• 高频成分（对应于系数矩阵右下角，u和v值较大的部分）代表了图像块的细节、锐利边缘和纹理。

图像的大部分视觉能量（信息） 通常都集中在低频区域。这意味著，我们往往只需要少数几个大的低频系数，就能大致描述出图像块的主要样貌。

用二进制分解来类比DCT的能量集中

如果我们将所有的0系数也补上

那么对应的系数数组为：[1,0,1,0,1,0,1,1]

如果我们简单将数组低索引称之为”低频”，高索引为”高频”,将数据压缩只包含”低频”系数
[1,0,0,0,0,0,0,0]=>2^7=128 大概丢了25%的信息
[1,0,1,0,0,0,0,0]=>2^7+2^5=160 大概丢了6%的信息
[1,0,1,0,1,0,0,0]=>2^7+2^5=160 大概丢了1%的信息
……

可以看到“高频”信号对整个数据的影响比较小，这与DCT的思想不谋而合：我们保留对整体影响大的主要成分（低频系数），而舍弃或粗略表示那些影响细微的成分（高频系数），从而实现压缩。

总结 JPEG 压缩的流程

1. 颜色空间转换：将图像从 RGB 转换到 YCbCr。
2. 分块：将每个分量（Y, Cb, Cr）图像分割成 8x8 的块。
3. 前向 DCT：对每个 8x8 块应用上述的二维 DCT 公式，得到频率系数。
4. 量化：将 DCT 系数除以一个对应的量化步长（来自量化表），并四舍五入到整数。这一步是有损的，是信息丢失的主要来源。高频系数通常会被量化为 0。
5. 熵编码：对量化后的系数进行 Zigzag 扫描、差分脉冲编码调制和霍夫曼编码，生成最终的 .jpg 文件。

当解码时，过程是反过来的：熵解码 -> 反量化 -> 逆 DCT -> 合并块 -> 转换回 RGB。

参考

《影像算法解析——JPEG 压缩算法》
《白话文理解DCT离散余弦变换》
《离散余弦变换》
视频
The Unreasonable Effectiveness of JPEG: A Signal Processing Approach
中文翻译版本《离散余弦变换可视化讲解》

宏观结构：从文件到帧

一个H.264原始码流（.h264或.264文件）并不是一个简单的“视频文件”，它不包含音频、字幕等元信息。它是一个纯粹的、编码后的视频数据比特流。这个流的结构可以看作一个分层模型，如下图所示，理解这个结构是理解H.264的关键：

网络抽象层单元 (NAL Unit)

H.264设计的一个核心思想是网络友好性。为了实现这一目标，整个码流被分割成一个个独立的包，称为 NAL Unit（网络抽象层单元）。每个NAL Unit都是一个自包含的数据包，包含一个头部和负载数据。这种设计使得H.流非常适合在容易产生包丢失和延迟的网络（如RTP/UDP）中传输，因为一个NAL Unit的丢失通常不会导致整个视频无法解码。

关键概念：帧 (Frame) 与片 (Slice)

在视频编码中，一帧（Frame） 通常对应一张静态图片。H.264对一帧图像进行编码后，其数据可能会被装进一个或多个NAL Unit中。

为什么是一或多个？这是因为一帧数据可以被分割成多个片（Slice）。每个Slice都是一个独立的编码单元，包含了一帧图像中的一部分宏块（Macroblock）。将一帧分割成多个Slice主要有两个好处：

1. 错误恢复：在网络传输中，如果一个Slice丢失了，解码器仍然可以利用错误隐藏技术来近似恢复图像，而不是丢失整帧。
2. 并行处理：多个Slice可以并行编码或解码，提高效率。

微观结构：NAL Unit的内部世界

现在，让我们打开一个NAL Unit，看看它里面到底有什么。

NAL Unit Header（头部）

每个NAL Unit都以一个1字节（可扩展为2字节）的头部开始。这个头部虽然小，但信息量巨大：

• 禁止位（F）：通常为0，如果为1表示该单元出错。
• 重要性指示位（NRI）：表示这个NAL Unit的重要性。值越大，解码器越需要优先保护它（如SPS/PPS的NRI值最高）。
• 类型（Type）：这是最关键的部分！它定义了该单元负载数据的类型。主要分为两大类：
  • VCL（视频编码层）单元：真正携带编码视频数据的单元（如Slice）。
  • Non-VCL（非视频编码层）单元：携带元数据和控制信息的单元，是解码的“说明书”。

NAL Unit Payload（负载）

负载部分的数据内容完全由头部中的类型（Type） 决定。

关键的Non-VCL单元（元数据）

这些单元不包含图像像素数据，但没有它们，VCL单元根本无法被解码。它们通常在视频流开始时发送一次，但如果解码器中途加入，也需要重新获取。

SPS（序列参数集 - Type 7）
作用：包含了适用于整个视频序列的全局参数。它是解码器的“总纲”。
包含信息：视频的档次、级别、分辨率（pic_width_in_mbs_minus1等）、帧率、色深、比特深度等。没有SPS，解码器连图像该解码成多大都不知道。

PPS（图像参数集 - Type 8）
作用：包含了适用于一幅或多幅图像的解码参数。它更像是“章节细则”。
包含信息：熵编码模式（CAVLC或CABAC）、量化参数等。PPS可以改变，从而在序列中实现不同的编码配置。

IDR（即时解码刷新 - 属于VCL，但特殊）
作用：一个特殊的Slice（通常是I-Slice），它告诉解码器：“从这里开始，可以独立解码，不再需要参考之前的帧了。”
意义：IDR帧是随机访问和 seeking 的关键点。当你拖动视频进度条时，播放器总是在寻找最近的IDR帧开始解码，因为它能清空之前的参考帧缓冲区，保证解码正确。

VCL单元（核心数据）

这些单元携带了实际的压缩视频数据，即Slice。

Slice Header（切片头）
每个Slice都有自己的头，其中包含了当前Slice解码所需的信息：
引用哪个PPS（从而间接引用SPS）。
帧类型（I, P, B）。
量化参数。
根据帧类型，包含运动向量预测所需的信息。

Slice Data（切片数据）
这是压缩数据的核心，由一系列宏块（Macroblock） 组成。
宏块通常是16x16像素的编码单元，它包含了：
预测信息：对于I帧，是帧内预测模式；对于P/B帧，是运动向量（描述当前块是从参考帧的哪个位置移动过来的）。
残差数据：经过预测后，当前块与预测块之间的差值。这部分数据会经过变换（DCT）、量化、熵编码（CAVLC/CABAC），从而获得极高的压缩率。

特殊设计点

3.1 参数集（SPS/PPS）机制

这是H.264一个非常巧妙的设计。它将很少改变但至关重要的信息（SPS/PPS）与频繁变化的数据（Slice）分离开。
优点一：鲁棒性：即使丢失了一些Slice，只要SPS/PPS还在，解码器就能继续工作。
优点二：效率：无需在每一个Slice中都重复这些头部信息，大大节省了码流。
优点三：灵活性：一个码流中可以存在多个PPS，并在不同场景下切换使用。

3.2 I, P, B帧与GOP（图像组）

I帧（Intra）：自包含帧，仅使用本帧内的信息进行编码，不参考其他帧。它是压缩率最低但最关键的帧，是P帧和B帧的锚点。
P帧（Predicted）：参考前面的I帧或P帧进行运动补偿预测编码，压缩率高于I帧。
B帧（Bi-directional）：可以同时参考前面和后面的帧，获得最高的压缩率，但会带来编码延迟。
一个GOP就是从上一个IDR帧到下一个IDR帧之前的所有帧序列。GOP长度越长，B/P帧越多，压缩率越高，但随机访问的间隔也越长。

3.3 熵编码：CAVLC 与 CABAC

这是压缩过程中的最后一步，将数据转换为二进制码流。
CAVLC（上下文自适应变长编码）：相对简单，压缩效率一般，用于Baseline等档次。
CABAC（上下文自适应二进制算术编码）：非常复杂，但压缩效率比CAVLC高出10%-20%，是Main和High档次效率高的主要原因之一。

总结

H.264的结构是一个分层、模块化的杰作：
整体：码流由一个个NAL Unit组成，适合网络传输。
局部：NAL Unit分为VCL（携带Slice数据）和Non-VCL（携带SPS/PPS等元数据）。
核心：Slice数据由宏块组成，宏块包含了预测信息和残差数据，通过预测和变换编码实现压缩。
精妙设计：参数集分离、IDR帧、Slice划分和CABAC等特性共同造就了H.264在效率、鲁棒性和灵活性上的完美平衡。

理解H.264的结构，不仅能帮助我们更好地处理视频数据（如封装、传输、解码问题定位），更能让我们体会到工程师们在标准制定中的智慧和远见。尽管如今H.265/HEVC、AV1等更先进的编码器已经出现，但H.264的基本设计思想和结构仍然深刻地影响着它们。

本文代码基于 Koin 源码思想实现，仅用于学习核心原理，并非 Koin官 方代码。

核心概念与项目结构

下图是基于 koin 4.1 解析的 主要类UML图，可以比较清晰地看看各个类之间的关系

power by mermaidchart

主要类：

• KoinApplication: Koin启动的入口，负责初始化容器和加载模块。
• Koin: 核心容器，持有实例注册表 InstanceRegistry 和作用域注册表 ScopeRegistry。
• Module: 定义依赖的地方，存放了所有的 bean 定义 BeanDefinition 与 InstanceFactory。
• BeanDefinition: 对一个依赖项的定义，包括其类型、限定符、所属作用域以及创建它的 lambda 表达式。
• InstanceFactory: 负责根据 BeanDefinition 创建实例的核心工厂，分为 SingleFactory (单例)、FactoryFactory (工厂模式) 和 ScopeFactory (作用域内单例)。
• Scope: 作用域，用于管理特定生命周期内的实例。
• ParametersHolder: 参数容器，用于在获取实例时动态传递参数。

手写 koin 代码介绍

基于对源码的理解和参考，实现了 koin 的基本功能，整体分成三部分：简单 single 数据存取、包含 scope 能力、动态参数能力，分成三个文件夹，顺序123是基于前面带代码累加的。

简单 single 数据存取
代码实现在：KoinWithoutScope.kt

这是一份最简单的代码，大概200行不到，基本上包含了 koin 的核心思想：启动时注册组件定义。解析时，先查作用域缓存，命中则直接返回。未命中则递归解析其依赖项，调用工厂函数创建实例，最后返回实例。

从这也能看出来 koin 的缺点：Koin 启动时 (startKoin) 需要将所有模块的定义 (BeanDefinition) 注册到容器中。实例数量过多会显著增加启动注册过程的耗时，影响应用启动速度。由于每个实例都会对应一个 BeanDefinition 以及 Factory ，内存占用会相应地上升。

整个流程简单来讲就是生成一个 map，通过 key 获取对于的数据。

Scope 能力
代码实现在：KoinWithScope.kt

这一份是在之前的能力上进行添加，此前将所有的数据都注册到 “root” 这个容器内，全局通用，但为了将不同作用域分开，需要引入 scope 的概念。

简单理解就是在通过 key 获取的 map 里面的数据的时候，这个 key 是有一定的规则的，核心逻辑在这里：

 inline fun indexKey(clazz: KClass<*>, typeQualifier: String?, scopeQualifier: String): String {
    return buildString {
        append(clazz.java.name)
        append(':')
        append(typeQualifier ?: "")
        append(':')
        append(scopeQualifier)
    }
}

动态参数能力
代码实现在：KoinWithParameter.kt

最后在 scope 的基础上实现了一个比较重要的能力-动态参数能力，通过这个能力可以让有实例能够在运行的时候根据参数动态创建。这个能力也是像在安卓 Activity/Fragment 里面 viewmodel() 实现依赖注入的必要实现。

简单理解就是在 get() 的时候将参数传入到获取实例的调用链中，在运行时执行注册的 Lambda 函数invoke时候将作为参数传递到构造方法中去。这里单独拎出来实现是因为这个参数传递影响到整个流程的逻辑，为了上上面的两个能力逻辑更简单清晰，单独在这一部分实现。

Koin 的注册流程（Declaration）

注册是DI容器工作的第一步。通过 startKoin 和 module DSL来声明依赖。

启动 Koin 与模块加载

整个启动加载流程将 kotlin 的语法糖用到了极致，也就使得整个代码看起来是如此的简洁。

val myApp = startKoin {
    modules(appModule)
}

// 定义一个模块
val appModule = module {
    // 注册一个单例，其构造需要一個 Int 参数
    single { (data: Int) -> ComponentInt(data) }
    // 注册一个工厂（每次获取都是新实例），其构造需要 Int 和 Float 参数
    factory { (data1: Int, data2: Float) -> ComponentIntFloat(data1, data2) }
}

流程剖析：

startKoin
这是一个顶级函数，它调用 GlobalContext.startKoin，创建并初始化一个 KoinApplication 对象。

modules(...)
KoinApplication 的方法，它将传入的 Module 列表交给 Koin 实例的 loadModels 方法处理。

module { ... }
DSL函数，它创建一个 Module 对象，并执行其中的配置lambda。

single/factory/scope
Module 的扩展函数。它们的作用是：

• 使用 _createDefinition 将 lambda 表达式包装成一个 BeanDefinition对象。
• 使用 _InstanceFactory 将 BeanDefinition 包装成对应的 InstanceFactory。
• 调用 indexPrimaryType，生成一个唯一的Key（格式：类名:限定符:作用域），并将 Factory 存入 Module.mappings 这个 HashMap 中。

最终存储
Koin 的 InstanceRegistry 会遍历所有 Module，将它们 mappings 中的全部 Factory 都合并到自己的 _instances（一个 ConcurrentHashMap）中。

至此，所有依赖的定义都已注册到容器中，静待获取。

Koin的实例获取流程（Retrieval）

// 获取无参依赖（普通方式）
val component = get<Component>()

// 通过 scope 作用域限定进行获取
val scope = koin.createScope("scope", scopeQualifier)
val component = scope.get<Component>()

// 通过需要动态参数的获取
val componentWithArgs = get<ComponentInt> { parametersOf(42) }
val componentWithMultiArgs = get<ComponentIntFloat> { parametersOf(101, 3.14f) }

流程剖析

Scope.get<T>

这是 Scope 的一个扩展函数。它首先创建一个 ResolutionContext，封装了当前作用域、要解析的类型、限定符以及最重要的——参数持有器 ParametersHolder（由 parametersOf 函数创建）。

解析上下文（ResolutionContext）

这个上下文对象包含了解析一个实例所需的所有信息。

核心解析器（CoreResolver）
get 操作会委托给 Koin 的 CoreResolver进行处理。源码里面对于查找顺序有非常清晰的层次体现：

override fun <T> resolveFromContext(scope : Scope, instanceContext: ResolutionContext): T {
      return resolveFromContextOrNull(scope,instanceContext) ?: throwNoDefinitionFound(instanceContext)
  }

  private fun <T> resolveFromContextOrNull(scope : Scope, instanceContext: ResolutionContext, lookupParent : Boolean = true): T? {
      return resolveFromInjectedParameters(instanceContext)
          ?: resolveFromRegistry(scope,instanceContext)
          ?: resolveFromStackedParameters(scope,instanceContext)
          ?: resolveFromScopeSource(scope,instanceContext)
          ?: resolveFromScopeArchetype(scope,instanceContext)
          ?: if (lookupParent) resolveFromParentScopes(scope,instanceContext) else null
          ?: resolveInExtensions(scope,instanceContext)
  }

查找工厂

• Resolver 会调用 InstanceRegistry.resolveDefinition。

• 该方法使用和注册时相同的算法生成Key（类名:限定符:作用域），然后从 _instances 中查找对应的 InstanceFactory。

  创建实例

• 找到 Factory 后，调用其 get(context: ResolutionContext) 方法。

• Factory 会调用自己的 create 方法。关键一步来了：在 create 方法中，会执行 BeanDefinition.definition.invoke(context.scope, parameters)。这其实就是执行了之前注册的 lambda：{ (data: Int) -> ComponentInt(data) }。

• 参数传递：这里的 parameters 就是在 get 时传入的 ParametersHolder。Lambda 的参数 (data: Int) 会从 ParametersHolder 中按顺序（或使用解构）取出值

返回实例

工厂将创建好的实例返回给调用者。

对于 SingleFactory，它会将第一次创建出来的实例缓存起来，后续调用直接返回缓存实例。FactoryFactory 则每次都会执行 create 方法。

其他技术

@DslMarker 的作用

在实现的过程中发现如下图所示：koin 的代码有颜色分层，能比较清晰地看到各个 block 之间的差异，自己写的代码全部是白色。

代码开头定义了三个注解：@KoinApplicationDslMarker, @KoinDslMarker, @OptionDslMarker。这是Kotlin DSL的安全卫士。

@DslMarker
annotation class KoinDslMarker

@KoinDslMarker
class Module {
    fun single(...) { ... } // 这个single在DSL里
}

@KoinDslMarker
class KoinApplication {
    fun modules(...) { ... } // 这个modules在DSL里
}

fun test() {
    startKoin {
        modules(...) // 正确：在 KoinApplication 的 lambda 里
        single { ... } // 编译错误！@DslMarker 阻止了隐式地使用外部 Receiver (Module)
    }
}

@DslMarker 实际的作用是防止在嵌套的DSL Lambda中，意外地调用到外层 Receiver 的方法，从而让DSL书写更加清晰和安全。代码颜色是由 IDE 提供的效果。在代码中加上几个注解之后，效果如图所示：

跟 koin 的颜色不太一致，不过能明显看到代码有分层，应该是由于 koin 对 annotation 也有处理，这里没有再深入研究。

2. 优雅的参数传递与解构

这个逻辑复刻了Koin的动态参数特性。

• ParametersHolder：一个轻量的参数容器，内部用一个 List<Any?> 存储参数。
• parametersOf：辅助函数，优雅地创建 ParametersHolder。
• 解构声明（Destructuring Declaration）：ParametersHolder 重写了 component1() 到 component5() 操作符。这使得在定义lambda时，可以直接用 (a: A, b: B) 的形式来接收参数，而不是手动调用 parameters.get<X>(0)。

// 注册端：看起来就像普通函数
single { (id: Int, name: String) -> User(id, name) }

// 获取端：传递参数非常直观
val user = get<User> { parametersOf(123, "Julius") }

这种设计极大地提升了API的简洁性和可读性。

总结

通过这个手写的迷你Koin，可以深刻地理解到，一个现代DI容器的核心无非是解决两个问题：

1. 如何注册（Declaration）：通过DSL将依赖的创建方式（Lambda）以键值对的形式保存到一个全局的注册表中。
2. 如何获取（Retrieval）：根据请求的类型、限定符和作用域生成Key，从注册表中找到对应的创建工厂，并调用它来生成实例。支持通过参数容器实现动态传参。

除此之外，诸如 @DslMarker 保证DSL安全、解构实现参数优雅传递，都是构建一个健壮、易用框架的关键技术。

虽然这个实现省略了Koin的许多高级功能（如完整的Scope生命周期管理、属性注入、Android特定支持等），但它已经囊括了最核心、最精妙的设计思想，再理解其他的模块也会简单很多。

实现的所有源码位于：JProject/source/koin

在追求高效开发的时代，跨平台技术已成为移动应用开发的主流选择，此前基于鸿蒙的开发平台开发 blog_harmony，将自己博客文章进行展示。本文将介绍基于 CMP(Compose Multiplatform) 构建的开源博客应用 blog_kmp，展示如何用 Kotlin 实现跨平台的应用开发。

Compose Multiplatform

Compose Multiplatform 是 JetBrains 推出的声明式 UI 框架，基于 Jetpack Compose 扩展而来：

• 核心优势：用同一套 Kotlin 代码构建 Android、iOS、Desktop 和 Web 应用
• 开发效率：实时预览、热重载加速开发迭代
• 原生性能：通过 Skia 渲染引擎实现接近原生体验
• 共享逻辑：业务逻辑、网络请求、状态管理可 100% 复用

项目架构与技术栈

blog_kmp 采用分层架构设计，核心模块包括：

shared/
├── src/commonMain/kotlin/  # 共享业务逻辑
│   ├── data/               # 数据层
│   ├── domain/             # 领域模型
│   └── presentation/       # UI状态管理
├── src/androidMain/        # Android 平台代码
└── src/iosMain/            # iOS 平台适配
├── composeApp
│   ├── build.gradle.kts
│   └── src
│       ├── androidMain     # Android 平台代码
│       ├── commonMain      # 共享业务逻辑
│            ├── App.kt     # 界面展示入口
│            ├── data       # 数据层
│            │   ├── api        # 网络请求
│            │   ├── di         # koin 依赖注入
│            │   ├── model      # model 数据
│            │   └── repository # 数据缓存管理
│            │
│            ├── navigation  # 页面间导航管理
│            ├── platform    # 通过对各个平台抽象的接口 
│            └── ui          # 通用 UI 逻辑
│
│       ├── desktopMain     # Desktop 平台适配
│       └── iosMain         # iOS 平台适配

功能预览

Android

深色模式

iOS

Desktop

主要技术栈

1. Ktor 客户端 - 网络请求

   val httpClient = HttpClient { install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) } } suspend fun loadPosts(): List<Post> = httpClient.get("https://cdn.julis/api/posts").body()

2. DataStore - 跨平台数据库

   val dataKey = stringPreferencesKey(key) val result = dataStore.data .catch { exception -> // dataStore.data throws an IOException when an error is encountered when reading data if (exception is IOException) { emit(emptyPreferences()) } else { throw exception } } .map { preferences -> val data: String? = preferences[dataKey] if (data == null) { null } else { if (isJson) Json.decodeFromString<T>(data) else (data as T) } }

3. Koin - 依赖注入

   val sharedModule = module { single<PostRepository> { PostRepositoryImpl(get()) } viewModel { PostViewModel(get()) } }

4. Kotlinx.Serialization - JSON 解析

   @Serializable data class Post( val id: String, val title: String, val content: String )

5. compose-webview-multiplatform - WebView 浏览器
   使用的第三方开发compose-webview-multiplatform基于 java-cef开发，不过这个library 在 desktop 平台表现不是太好，待完善。

   val state = rememberWebViewState(postUrl) WebView(state = state,modifier = Modifier.fillMaxSize())

平台特定实现

UI 层面三端能够使用同一份代码，但为了体验，可能需要针对不同的设计，在桌面端可以设计更好地体验UI。这里避免不了 if-else 的UI逻辑，以及一些依赖各种系统的 api 需要单独实现，比如：深色模式监听、资源存储路径、系统信息、状态栏颜色等。

Android 端
Android 特定的功能结合使用起来非常的简单，毕竟都是有血缘关系的。可以使用 AndroidView 直接渲染原生的 UI 页面。

AndroidView(
      modifier = Modifier.fillMaxSize(),
      factory = { context ->
          MyView(context) }
      },
      update = { view ->}
  )

iOS 端
iOS端主要需要 XCode 进行配合，还需要关注开发者账号相关的信息等，其他与 Android 端实现没有太大的差异。

桌面端
利用 Compose Desktop 的窗口管理，可以实现窗口多开。

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        DesktopAppTheme { AppContent() }
    }
}

🚀 性能优化实践

1. 分页加载：实现懒加载防止长列表卡顿

   LazyColumn { itemsIndexed(posts) { _, post -> PostItem(post) } item { if (loading) LoadingIndicator() } }

2. 本地缓存：DataStore 离线存储 + Ktor 缓存策略

   HttpClient { install(HttpCache) // 启用 HTTP 缓存 }

3. 图像处理：搭配 Coil 实现高效图片加载

   AsyncImage( modifier = Modifier.size(80.dp) .shadow( elevation = 5.dp, shape = CircleShape, spotColor = Color.Black ) .clip(CircleShape) .clickable { }, model = AppConfig.AVATAR, contentDescription = AppConfig.AVATAR, )

   开发经验总结

4. UI界面
   使用 Compose 进行界面布局开发，声明性编程范式相比于传统的 xml 布局开发，高效很多，使用也很方便。使用了这种方式，传统的 UI 开发方式再也回不去了。

5. 状态管理
   使用 mutableStateOf 实现响应式更新，或者使用 derivedStateOf 实现派生状态的处理。

   var pagIndex by remember { mutableStateOf(0) } var errorState by remember { mutableStateOf<String?>(null) } val themeState by mineViewModel.appTheme.collectAsState() val uiChecked by remember(themeState) { derivedStateOf { themeState == ThemeConstants.DARK } }

1. 导航

实现 Compose Navigator 统一路由管理

val gotoDebug: () -> Unit = {
    navController.navigate(Routes.Debug())
}

val goToPostDetail: (Post) -> Unit = { it ->
    navController.navigate(Routes.PostDetail(title = it.title, it.url))
}

1. Kotlin Flow
   简化异步编程，让网络请求的代码看起来更直观

   fun loadAllPost(): Flow<List<PostV2>> = load("allPosts") { postApi.getAllPost()?.data ?: emptyList() } suspend fun getAllPost(): SearchResponse? = request<SearchResponse>(getUrl("api/search.json")) private suspend inline fun <reified T> request(url: String): T? { return try { client.get(url).body() } catch (e: Exception) { if (e is CancellationException) throw e e.printStackTrace() null } }

总结

经过一番各种折腾，将很多在工作上无法使用的能力（Koin、Flow、DataStore……）都体验使用了一下，在业余的时间完成了基于博客文章构建的 App 在三个平台上的开发，实际上最初我也想搭建 WebJs 的平台的，后面删除掉了，因为涉及到 web 平台开发的各种库相比客户端少很多，兼容起来也比较费劲。KMP/CMP 这块技术确实是能很大地节省开发人力，多端使用同一份UI逻辑代码，部分逻辑也可以用 kotlin 统一进行封装，后续维护也会方便很多。但这里有个缺点就是涉及到的库所需要的 kotlin/Java 版本要求比较高，除非开发一些独立的 App，否则公司里的项目想基于这些技术去实现不太大可能。以及如果所需要的能力比较依赖与原生，比如音视频领域就有一定的局限性，总体来讲更适合偏交互业务的开发。

项目源码: https://github.com/VomPom/blog_kmp

App 简介

后台数据来自 Hexo 生成的博客文章，利用 hexo-generator-wxapi 生成 api .json 文件，再利用 七牛云 提供对图片和 .json 文件 CDN。

实现的功能

• 博客列表分页加载
• 文章详情加载
• 文章按分类/标签展示
• 文章内容统计
• 深色/浅色模式切换
• 数据本地缓存

功能预览

依赖项

Hexo

• Hexo 快速、简洁且高效的博客框架
• hexo-generator-wxapi 用于将 Hexo 博客内容生成 api 风格的.json文件
• 七牛云 提供对图片和.json文件 CDN加速

HarmonyOS

• ArkTS ArkTS在TypeScript（简称TS）生态基础上做了进一步扩展，保持了TS的基本风格，同时通过规范定义强化开发期静态检查和分析，提升代码健壮性，并实现更好的程序执行稳定性和性能。
• ArkUI ArkUI（方舟UI框架）为应用的UI开发提供了完整的基础设施，包括简洁的UI语法、丰富的UI功能（组件、布局、动画以及交互事件），以及实时界面预览工具等，可以支持开发者进行可视化界面开发。
• ohos_pull_to_refresh 列表加载/刷新控件(没有’No more’的状态)
• MMKV 是基于 mmap 内存映射的 key-value 组件

鸿蒙开发总结

ArkTs 语言

ArkTS 是 TypeScript 的超集，TypeScript 又是 JavaScript 的超集，所以对于基本数据类型使用的是 TypeScript 语法。他们三者的关系如下图所示：

相关的差异可以参考社区话题讨论 ArkTS与Typescript的区别？

这里主要记录一下自己使用过程中踩过的坑：

基本语言类型

Number 和 number 是两个不同的类型，Number 是 JavaScript 中的一个全局对象，可以使用 new Number() 来创建一个 Number 对象。同理对于 String 和 string，Boolean 和 boolean 也是一样的，大写开头的是包装对象类型，小写的是原始类型，这点Java/kotlin也有类似的包装对象比较好理解，但 Object 居然也有大小写之区分相比难理解点，写代码的时候好几次忽略了这个事，Object 是所有对象的基类，object 表示非原始类型（即不是 number、string、boolean、symbol、null 或 undefined 的所有类型）。可以是任何对象、数组、函数、类实例等。

let obj: object;
obj = { a: 1 };         // ✅ 正确：普通对象
obj = [1, 2, 3];        // ✅ 正确：数组
obj = () => {};         // ✅ 正确：函数
obj = new Date();       // ✅ 正确：类实例

obj = 42;               // ❌ 错误：原始类型 number
obj = "hello";          // ❌ 错误：原始类型 string

Map 等集合类当作普通 JavaScript 对象来操作

let map = new Map<string, object>();
map["key"] = value;            // ❌ 错误用法！
console.log(map.get("biz"));   // ❌ 输出 undefined

最开始挺奇怪的 map 明明设置了值，但是对应的 map size 为0，遍历 map 也没有数据。后来才发现是这种方式 不会 触发 Map 的内部机制，而是绕过了 Map 的方法，直接操作对象的属性，赋值后，键值对 不会 被存入 Map 的真实存储中，而是作为对象的普通属性存在。正确的用法是：

let map = new Map<string, object>();
map.set["key"] = value;        //  ✅ 正确用法！
console.log(map.get("biz"));   //  ✅ 输出 value

struct 的困扰

在 js 里面是没有 struct 这个关键词的，从刚接触到现在它唯一的作用就是：和 @Component绑定声明一个UI控件。例如：

@Component
export struct ToolBar{}

@Component 和 struct 两则缺一不可，既然必须有 @Component来标注这是一个UI控件，为什么不能下面这样呢？能省掉一个关键字。

@Component
export class ToolBar {}

struct和class的区别是什么?

struct只在自定义组件中使用，@Component装饰的struct就是自定义组件，自定义组件和class是两个概念，自定义组件没有类型，也不能等同于class。如果开发者需要使用组件作为参数在组件之间传递，可以使用自定义占位节点。

我猜测这样是为了省掉对@Component装饰器编译的工作量，如果使用 class 声明，那么声明的UI控件就有“面向对象”的能力，实际上只希望它是一个UI控件声明，不需要它有其他的能力。难道不能对 @Component 装饰过的对象收回“面向对象”的能力么？当然能啊，估计要做很多编译检查的事儿。另外，从开发理解的层面上来讲，它确实也已经不是”对象”了，它只是一个干巴巴的一个UI结构，所以干脆就搞了一个新的关键词 struct。

ArkUI 框架

整体框架使用的方式和 Jetpack Compose 类似，都是声明式UI框架。compose 里面使用 @Composable来标记某个方法这个方法便成了UI控件，控件里面的状态管理使用 remember+ mutableState来控制。而 ArkUI 通过 @State、@Link、@Prop 等装饰器来控制。了解了这些个装饰器的用法，基本上就能理解 ArkUI 的开发流程了。

构建 UI 的 @Component @Builder

@Component 和 @Builder 组合起来实现的差不多就是 Compose 里面使用 @Composable 装饰某个方法的作用，用于构建 UI 或可复用的逻辑单元。
@Component
用于创建一个自定义组件，组件可以包含独立的 UI 结构、状态管理和生命周期。

@Builder
定义可复用的 UI 片段，用于创建一个UI 构建函数，封装一段可复用的 UI 代码块。不是独立组件，而是嵌入到其他组件或布局中执行，主要作用是复用和逻辑隔离，例如：关于页面，里面的文本是差不多的样式，只是内容不一样，那么只需要保留一个 text 属性出来接收参数。或者某块UI比较复杂，可以抽离一部分UI成为一个独立的UI逻辑模块。

构建 UI 的状态控制装饰器

@State
比较常用的装饰器，和 Compose 里面 remember+mutableStateOf 的作用差不多，对应的值改变之后，对相关的使用到该属性UI的地方进行刷新。

@Prop
@Prop 装饰的变量和父组件建立单向的同步关系，@Prop变量允许在本地修改，但修改后的变化不会同步回父组件。

也就是在某个 @Component 的组件内有一个 @State 装饰的属性，传递到子 @Component 组件 @Prop 修饰的属性。子控件对这个属性修改之后，父控件不会对这个改变感知，父控件UI不会改变。

@Link
子组件中被@Link装饰的变量与其父组件中对应的数据源建立双向数据绑定。
跟 @Prop 的作用类似，不过是双向的，子控件对这个属性修改之后，父控件会感知这个变化，父控件UI会随着这个属性改变而改变。

@BuilderParam
主要用于动态注入 UI 构建逻辑（即 @Builder 函数），实现父组件向子组件传递可定制的 UI 片段，也就是向子控件传递 UI 参数。

基本上比较常用到的就这些，还有很多例如：@LocalBuilder @StorageLink @Styles等，都是为了解决开发过过程中遇到的问题，但是只要掌握了 ArkUI UI组件的声明周期和状态管理的基本原理理解其他装饰器还是比较简单的。

总结

总体开发体验下来，鸿蒙开发学习成本并不是特别高，比较快能上手，但设计的 api 更像一个缝合怪，且使用上不太收敛。很多库还需要再建设，例如音视频开发对应的支持库还不是特别成熟。不过，作为一个从头搞的生态来说能实现成这样已经很不错了，就像此前武磊登陆西甲，以及目前被看好的青年新星王钰栋，都是”自己的孩子”，需要迈出第一步。现在，很多公司也在适配鸿蒙了，期待未来能从 Android 跟 iOS 的生态中争夺出一片大市场。

项目源码：https://github.com/VomPom/blog_harmony

核心设计与原理

在官方的开源工程中可以看到如下的一些介绍

MMKV 是基于 mmap 内存映射的 key-value 组件，底层序列化/反序列化使用 protobuf 实现，性能高，稳定性强。从 2015 年中至今在微信上使用，其性能和稳定性经过了时间的验证。

传统I/O与 mmap

mmap 这个是 mmkv 实现的核心，没有 mmap 那么就没有 mmkv。对于 SharedPreferences的实现来说，每次的数据更新都将操作本地文件，而本地文件的写入是通过传统的I/O实现。要理解两者的实现差异，需要先理解 Linux 用户空间与内核空间设计。

用户空间与内核空间

Linux的进程是相互独立的，一个进程是不能直接操作或者访问别一个进程空间的。每个进程空间还分为用户空间和内核（Kernel）空间，相当于把Kernel和上层的应用程序抽像的隔离开。

用户空间和内核空间，用户空间是用户程序代码运行的地方，内核空间是内核代码运行的地方。为了安全，它们是隔离的，即使用户的程序崩溃了，内核也不受影响。

这里有两个隔离，一个进程间是相互隔离的，二是进程内有用户空间和内核空间的隔离。

进程间，用户空间的数据不可共享，所以用户空间 = 不可共享空间
进程间，内核空间的数据可共享，所以内核空间 = 可共享空间，所以Linux系统的内存通常是MemFree+Cache
所有进程共用1个内核空间。

传统I/O读写流程

常规文件读写操作（调用read/fread等函数）过程如下：

• 进程发起读写文件请求。

• 内核通过查找进程文件符表，定位到内核已打开文件集上的文件信息，从而找到此文件的inode。

• inode 在 address_space 上查找要请求的文件页是否已经缓存在页缓存中。如果存在，则直接返回这片文件页的内容。

• 如果不存在，则通过 inode 定位到文件磁盘地址，将数据从磁盘复制到页缓存。之后再次发起读页面过程，进而将页缓存中的数据发给用户进程。

  什么是 inode ?

  全称为 index node，既存储文件元信息的区域，中文译名“索引节点”。
  包含：文件权限、文件拥有者的UID、文件的大小等等。

  

总结来说，常规文件操作为了提高读写效率和保护磁盘，使用了页缓存机制。这样造成读文件时需要先将文件页从磁盘拷贝到页缓存中，由于页缓存处在内核空间，不能被用户进程直接寻址访问，所以还需要将页缓存中的数据页再次拷贝到用户空间中。这样，通过了两次数据拷贝过程，才能完成进程对文件内容的访问。

mmap基本概念和原理

内存映射（mmap），就是将文件的磁盘扇区映射到进程的虚拟内存空间的过程，即将一个文件映射到进程的虚拟空间，实现文件磁盘地址和进程虚拟空间中一段虚拟地址的一一对应关系。实现这样的映射关系后，进程就可以采用指针的方式读写操作这一段内存，而系统会自动回写脏页面到对应的文件磁盘上，即完成了对文件的操作而不必再调用read,write等系统调用函数。

由上图可知，进程的虚拟地址空间，由多个虚拟内存区域构成。每个虚拟内存区域都是进程在虚拟地址空间中的一个同质区间，即具有同样特性的连续地址范围。上图中所示的text数据段（代码段）、初始数据段、BSS数据段、堆、栈和内存映射，都是一个独立的虚拟内存区域。内存映射的地址空间处在堆栈之间的空余部分。

linux内核使用 vm_area_struct 结构来表示一个独立的虚拟内存区域，由于每个不同质的虚拟内存区域功能和内部机制都不同，因此一个进程使用多个 vm_area_struct 结构来分别表示不同类型的虚拟内存区域。各个 vm_area_struct 结构使用链表或者树形结构链接，方便进程快速访问，如下图所示：

vm_area_struct 结构中包含区域起始和终止地址以及其他相关信息。这样，进程对某一虚拟内存区域的任何操作需要用要的信息，都可以从 vm_area_struct 中获得。mmap函数就是要创建一个新的 vm_area_struct 结构，并将其与文件的物理磁盘地址相连。

mmap内存映射的实现过程，总的来说可以分为三个阶段：

阶段一：进程启动映射过程，并在虚拟地址空间中为映射创建虚拟映射区域

• 进程在用户空间调用mmap库函数

void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);

addr：指定映射的虚拟内存地址，可以设置为 NULL，让内核自动选择合适的虚拟内存地址

length：映射的长度。

prot：映射内存的保护模式，可选值如下：

flags：指定映射的类型

fd：进行映射的文件句柄。

offset：文件偏移量（从文件的何处开始映射）

• 在当前进程的虚拟地址空间中，寻找一段空闲的满足要求的连续的虚拟地址

• 为此虚拟区分配一个 vm_area_struct 结构，接着对这个结构的各个域进行了初始化

• 将新创建的虚拟区结构 vm_area_struct 对象插入到进程的虚拟地址区域链表/树中

阶段二：调用内核空间的mmap函数（不同于用户空间函数），实现文件物理地址和进程虚拟地址的一一映射关系

• 为映射分配了新的虚拟地址区域后，通过待映射的文件指针，在文件描述符表中找到对应的文件描述符，通过文件描述符，链接到内核“已打开文件集”中该文件的文件结构体（struct file），每个文件结构体维护着和这个已打开文件相关各项信息。

• 为映射分配了新的虚拟地址区域后，通过待映射的文件指针，在文件描述符表中找到对应的文件描述符，通过文件描述符，链接到内核“已打开文件集”中该文件的文件结构体（struct file），每个文件结构体维护着和这个已打开文件相关各项信息。

• 通过该文件的文件结构体，链接到 file_operations 模块，调用内核mmap函数，其原型为：

int mmap(struct file *filp, struct vm_area_struct *vma) //不同于用户空间mmap库函数

• 内核mmap函数通过虚拟文件系统inode模块定位到文件磁盘物理地址。

• 通过 remap_pfn_range 函数建立页表，即实现了文件地址和虚拟地址区域的映射关系。此时，这片虚拟地址并没有任何数据关联到物理内存(主存)中。

主存

主存储器（Main memory），简称主存。是计算机硬件的一个重要部件，其作用是存放指令和数据，并能由中央处理器（CPU）直接随机存取

阶段三：进程发起对这片映射地址空间的访问，引发缺页异常，实现文件内容到主存（物理内存）的拷贝

前两个阶段仅在于创建虚拟区间并完成地址映射，但是并没有将任何文件数据的拷贝至主存。真正的文件读取是当进程发起读或写操作时

• 进程的读或写操作访问虚拟地址空间这一段映射地址，通过查询页表，发现这一段地址并不在物理页上。因为目前只建立了地址映射，真正的硬盘数据还没有拷贝到内存中，因此引发缺页异常。

• 缺页异常进行一系列判断，确定无非法操作后，内核发起请求调页过程。

• 调页过程先在交换缓存空间（swap cache）中寻找需要访问的内存页，如果没有则调用nopage函数把所缺的页从磁盘装入到主存中。

• 之后进程即可对这片主存进行读或者写的操作，如果写操作改变了其内容，一定时间后系统会自动回写脏页面到对应磁盘地址，也即完成了写入到文件的过程。

修改过的脏页面并不会立即更新回文件中，而是有一段时间的延迟，可以调用msync()来强制同步, 这样所写的内容就能立即保存到文件里了

常规文件操作需要从磁盘到内核空间页缓存再到用户空间主存的两次数据拷贝。而mmap文件映射，只需要从磁盘到用户空间主存的一次数据拷贝过程。mmap的关键点是实现了用户空间和内核空间的数据直接交互而省去了空间不同数据不通的繁琐过程，因此 mmap 效率更高。

以上是 mmap 的基本概念和原理，搞明白了这些才能看明白整个 mmkv 里面的逻辑处理

mmkv 一次 put 的流程

mmkv初始化比较简单，主要涉及到一些配置的初始化，文件夹创建等，其中最重要的逻辑 mmap 调用被封装到一个 MemoryFile到对象里面

bool MemoryFile::mmap() {
    auto oldPtr = m_ptr;
    auto mode = m_readOnly ? PROT_READ : (PROT_READ | PROT_WRITE);
    m_ptr = (char *) ::mmap(m_ptr, m_size, mode, MAP_SHARED, m_diskFile.m_fd, 0);
    ...
    return true;
}

主要记录一下一次 put 任务的流程，以 mmkv.putInt("int", 1)为例，进过 JNI 的调用到了

native-birdge.cpp

MMKV_JNI jboolean encodeInt(JNIEnv *env, jobject obj, jlong handle, jstring oKey, jint value) {
    MMKV *kv = reinterpret_cast<MMKV *>(handle);
    if (kv && oKey) {
        string key = jstring2string(env, oKey);
        return (jboolean) kv->set((int32_t) value, key);
    }
    return (jboolean) false;
}

进入了MMVK.cpp的

bool MMKV::set(int32_t value, MMKVKey_t key, uint32_t expireDuration) {
    if (isKeyEmpty(key)) {
        return false;
    }
    size_t size = mmkv_unlikely(m_enableKeyExpire) ? Fixed32Size + pbInt32Size(value) : pbInt32Size(value);
    MMBuffer data(size);
    CodedOutputData output(data.getPtr(), size);
    output.writeInt32(value);
    // ... 省略一些校验逻辑
    return setDataForKey(std::move(data), key);
}

这一步主要是准备一下数据，并使用 MMBuffer CodedOutputData将写入的数据进行一次包装（不仅仅是 key-value，还有数据size等等），实际调用在setDataForKey

bool MMKV::setDataForKey(MMBuffer &&data, MMKVKey_t key, bool isDataHolder) {
    checkLoadData(); // 状态同步相关的逻辑
    if (m_crypter) {
      // ... 省略加密的处理逻辑
    } else
    {
        auto itr = m_dic->find(key);
        if (itr != m_dic->end()) {
            // compare data before appending to file
            if (isCompareBeforeSetEnabled()) {
                auto basePtr = (uint8_t *) (m_file->getMemory()) + Fixed32Size;
                MMBuffer oldValueData = itr->second.toMMBuffer(basePtr);
                if (isDataHolder) {
                    CodedInputData inputData(oldValueData.getPtr(), oldValueData.length());
                    try {
                        // read extra holder header bytes and to real MMBuffer
                        oldValueData = CodedInputData::readRealData(oldValueData);
                        if (oldValueData == data) {
                            // MMKVInfo("[key] %s, set the same data", key.c_str());
                            return true;
                        }
                    } catch (std::exception &exception) {
                        MMKVWarning("compareBeforeSet exception: %s", exception.what());
                    } catch (...) {
                        MMKVWarning("compareBeforeSet fail");
                    }
                } else {
                     ...
                }
            }

            bool onlyOneKey = !isMultiProcess() && m_dic->size() == 1;
            if (mmkv_likely(!m_enableKeyExpire)) {
                ...
            } else {
                KVHolderRet_t ret;
                if (onlyOneKey) {
                    ret = overrideDataWithKey(data, key, isDataHolder);
                } else {
                    ret = appendDataWithKey(data, key, isDataHolder);
                }
                if (!ret.first) {
                    return false;
                }
                itr = m_dic->find(key);
                if (itr != m_dic->end()) {
                    itr->second = std::move(ret.second);
                } else {
                    // in case filterExpiredKeys() is triggered
                    m_dic->emplace(key, std::move(ret.second));
                    mmkv_retain_key(key);
                }
            }
        } else {
           ...
        }
    }
    m_hasFullWriteback = false;
    return true;
}

这里面的代码逻辑很长，做了很多 if-else 的逻辑，最终走向两个大分支：

key 是新增的走 appendDataWithKey

key 将会覆盖原来的将会走 overrideDataWithKey

有这两个分支，主要是因为 mmkv 存储采用的 protobuf 协议，另外有一个很重要的方法也在这里执行了：checkLoadData(); 安卓里面的多进程实现，将需要这里的一些逻辑，在 mmkv多进程原理篇进行讲解。

appendDataWithKey 转换为 MMBuffer并继续向下执行

KVHolderRet_t MMKV::appendDataWithKey(const MMBuffer &data, MMKVKey_t key, bool isDataHolder) {
    auto keyData = MMBuffer((void *) key.data(), key.size(), MMBufferNoCopy);
    return doAppendDataWithKey(data, keyData, isDataHolder, static_cast<uint32_t>(keyData.length()));
}

doAppendDataWithKey 里面的代码也很长，不过也就只做一件事：将k-v值写入到文件里面做准备，真正的写入逻辑在 m_output->writeData(keyData);，这里先后调用了两次 writeData,是先写入key再写入了 value。

KVHolderRet_t
MMKV::doAppendDataWithKey(const MMBuffer &data, const MMBuffer &keyData, bool isDataHolder, uint32_t originKeyLength) {
    auto isKeyEncoded = (originKeyLength < keyData.length());
    auto keyLength = static_cast<uint32_t>(keyData.length());
    auto valueLength = static_cast<uint32_t>(data.length());
    if (isDataHolder) {
        valueLength += pbRawVarint32Size(valueLength);
    }
    // size needed to encode the key
    size_t size = isKeyEncoded ? keyLength : (keyLength + pbRawVarint32Size(keyLength));
    // size needed to encode the value
    size += valueLength + pbRawVarint32Size(valueLength);

    SCOPED_LOCK(m_exclusiveProcessLock);

    bool hasEnoughSize = ensureMemorySize(size);
    if (!hasEnoughSize || !isFileValid()) {
        return make_pair(false, KeyValueHolder());
    }
...
    try {
        if (isKeyEncoded) {
            m_output->writeRawData(keyData);
        } else {
            m_output->writeData(keyData);
        }
        if (isDataHolder) {
            m_output->writeRawVarint32((int32_t) valueLength);
        }
        m_output->writeData(data); // note: write size of data
    } 
    ...
    m_actualSize += size;
    updateCRCDigest(ptr, size);
    return make_pair(true, KeyValueHolder(originKeyLength, valueLength, offset));
}

writeData 进行了两步先写入数据的 长度信息，再写入真实的数据，这里还是因为 protobuf 协议设计相关

void CodedOutputData::writeData(const MMBuffer &value) {
    this->writeRawVarint32((int32_t) value.length());
    this->writeRawData(value);
}

最终走到了writeRawData 关键代码

void CodedOutputData::writeRawData(const MMBuffer &data) {
    size_t numberOfBytes = data.length();
    if (m_position + numberOfBytes > m_size) {
       ...
    }
    
    memcpy(m_ptr + m_position, data.getPtr(), numberOfBytes);
    m_position += numberOfBytes;
}

核心逻辑使用 memcpy 将数据直接通过 memcpy 直接在内存层面进行拷贝，而这里的 m_ptr就是最开始通过mmap创建出来的指针！！到这里一次写入基本上就结束了。

mmkv 一次 get 的流程

依然先通过 JNI走到

MMKV_JNI jint decodeInt(JNIEnv *env, jobject obj, jlong handle, jstring oKey, jint defaultValue) {
    MMKV *kv = reinterpret_cast<MMKV *>(handle);
    if (kv && oKey) {
        string key = jstring2string(env, oKey);
        return (jint) kv->getInt32(key, defaultValue);
    }
    return defaultValue;
}

再到 mmkv getInt32

int32_t MMKV::getInt32(MMKVKey_t key, int32_t defaultValue, bool *hasValue) {
  ...
    SCOPED_LOCK(m_lock);
    SCOPED_LOCK(m_sharedProcessLock);
    auto data = getDataForKey(key);
    if (data.length() > 0) {
        try {
            CodedInputData input(data.getPtr(), data.length());
            if (hasValue != nullptr) {
                *hasValue = true;
            }
            return input.readInt32();
        } 
        ...
    return defaultValue;
}

getRawDataForKey方法，主要有两个分支，一种是加密逻辑，另一种是非加密逻辑，但他们流程都差不多从一个 map 里面根据 key 获取一个对象（这个对象暂时并不是 get 最终的返回值），那这个 map 是从哪里来的呢？

MMBuffer MMKV::getRawDataForKey(MMKVKey_t key) {
    checkLoadData();
#ifndef MMKV_DISABLE_CRYPT
    if (m_crypter) {
        auto itr = m_dicCrypt->find(key);
        if (itr != m_dicCrypt->end()) {
            auto basePtr = (uint8_t *) (m_file->getMemory()) + Fixed32Size;
            return itr->second.toMMBuffer(basePtr, m_crypter);
        }
    } else
#endif
    {
        auto itr = m_dic->find(key);
        if (itr != m_dic->end()) {
            auto basePtr = (uint8_t *) (m_file->getMemory()) + Fixed32Size;
            return itr->second.toMMBuffer(basePtr);
        }
    }
    MMBuffer nan;
    return nan;
}

从源码里面溯源m_dicCrypt和 m_dic 是在 MMKV 初始化的时候生成的，主要逻辑在 MMKV_IO .cpp里面的 loadFromFile方法内：

void MMKV::loadFromFile() {
    loadMetaInfoAndCheck();
...
    if (!m_file->isFileValid()) {
        m_file->reloadFromFile(m_expectedCapacity);
    }
    if (!m_file->isFileValid()) {
        MMKVError("file [%s] not valid", m_path.c_str());
    } else {
        bool loadFromFile = false, needFullWriteback = false;
        checkDataValid(loadFromFile, needFullWriteback);
        ...
        auto ptr = (uint8_t *) m_file->getMemory();
        // loading
        if (loadFromFile && m_actualSize > 0) {
...
            MMBuffer inputBuffer(ptr + Fixed32Size, m_actualSize, MMBufferNoCopy);
            if (m_crypter) {
                clearDictionary(m_dicCrypt);
            } else {
                clearDictionary(m_dic);
            }
            if (needFullWriteback) {
#ifndef MMKV_DISABLE_CRYPT
                if (m_crypter) {
                    MiniPBCoder::greedyDecodeMap(*m_dicCrypt, inputBuffer, m_crypter);
                } else
#endif
                {
                    MiniPBCoder::greedyDecodeMap(*m_dic, inputBuffer);
                }
            } else {
#ifndef MMKV_DISABLE_CRYPT
                if (m_crypter) {
                    MiniPBCoder::decodeMap(*m_dicCrypt, inputBuffer, m_crypter);
                } else
#endif
                {
                    MiniPBCoder::decodeMap(*m_dic, inputBuffer);
                }
            }
            m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
            m_output->seek(m_actualSize);
            if (needFullWriteback) {
                fullWriteback();
            }
        } else {
            // file not valid or empty, discard everything
            SCOPED_LOCK(m_exclusiveProcessLock);

            m_output = new CodedOutputData(ptr + Fixed32Size, m_file->getFileSize() - Fixed32Size);
            if (m_actualSize > 0) {
                writeActualSize(0, 0, nullptr, IncreaseSequence);
                sync(MMKV_SYNC);
            } else {
                writeActualSize(0, 0, nullptr, KeepSequence);
            }
        }
...
    }

    m_needLoadFromFile = false;
}

总统来说就是在初始化的时候就会将基于protobuf协议的本地文件里面的数据加载到内存，并将其放在一个 map 内，方便后续使用。

回到 int32_t MMKV::getInt32()通过 getDataForKey(key)获取到一个MMBuffer对象，并通过 CodedInputData进行反序列化操作，读取 Varint32 的 valueSize 值，随后不断循环通过 CodedInputData 读取到value 值。

int32_t MMKV::getInt32(MMKVKey_t key, int32_t defaultValue, bool *hasValue) {
    ...
    auto data = getDataForKey(key);
    if (data.length() > 0) {
        try {
            CodedInputData input(data.getPtr(), data.length());
            if (hasValue != nullptr) {
                *hasValue = true;
            }
            return input.readInt32();
        } 
        ...
    }
  ...
    return defaultValue;
}

mmkv 与 SharedPreferences

以下是 MMKV 与 SharedPreferences 的优劣势对比总结，结合性能、安全性、功能支持等核心维度进行分析：

性能对比

安全性与稳定性

功能支持

从上面的对比看看，mmkv 在很多层面都是领先 SharedPreferences 的，那么 mmkv 是否有缺陷呢？答案是有的。

任何的操作系统、任何的软件，在往磁盘写数据的过程中如果发生了意外——例如程序崩溃，或者断电关机——磁盘里的文件就会以这种写了一半的、不完整的形式被保留。写了一半的数据怎么用啊？没法用，这就是文件的损坏。这种问题是不可能避免的，MMKV 虽然由于底层机制的原因，在程序崩溃的时候不会影响数据往磁盘的写入，但断电关机之类的操作系统级别的崩溃，MMKV 就没办法了，文件照样会损坏。对于这种文件损坏，SharedPreferences 和 DataStore 的应对方式是在每次写入新数据之前都对现有文件做一次自动备份，这样在发生了意外出现了文件损坏之后，它们就会把备份的数据恢复过来；而 MMKV，没有这种自动的备份和恢复，那么当文件发生了损坏，数据就丢了，之前保存的各种信息只能被重置。也就是说，MMKV 是唯一会丢数据的方案。

在 mmkv 里面有 CRC 校验，如果不通过的话，将会废弃掉之前所有的数据。在 mmkv 里面也有人反馈：https://github.com/Tencent/MMKV/issues/729 在写入的过程中因为一些特殊情况写入失败，会导致本地的文件损坏且不可recovery。

那有什么办法避免这个问题呢？有大佬开源另一个 KV 框架 FastKV对这个问题进行了处理，采用通过double-write等方法确保数据的完整性，原理是数据依次写入A/B两个文件，如果写入A过程中崩溃，B仍是完整的，如果A完整写入了，则B写入时崩溃也不要紧。这种实现方式理论上是不错的，不太清楚 mmkv 为什么没有采取这样的逻辑。不过这个库并没有经过大量业务进行验证，只能作为一个学习的方案先看看。

另外谷歌已经开发了新的KV存储框架DataStore，SharedPreferences也将渐渐地退出历史的舞台了。不过 DataStore 的性能目前仍然没有 mmkv 的好。关于这三者的比较可以查看： 《Android 的键值对存储有没有最优解？》

总结

这篇文章深入剖析了 MMKV（腾讯开源的高性能键值存储组件）的核心设计与实现原理，重点对比了传统 I/O 与 mmap 内存映射的差异，并详细分析了 MMKV 的读写流程以及和 SharedPreferences 的各方面对比。

参考

《Android 的键值对存储有没有最优解？》

《mmap原理与应用》

《文件内存映射和传统I/O机制》

Android 内存映射mmap浅谈

最近终于有点精力能够去研究研究源码了， 真的是写的一个非常好的的开源库，以前刚接触安卓的时候扒拉过相关的源码，但是随着工作了几年之后，经验的积累，让我对源码里面的东西能够体会更深刻，自己也尝试去手写里面的核心实现，看完源码对整体的架构理解了之后，以为自己能很顺利的写下来，实则不然。
知识还是需要知行合一，这篇文章主要记录 retrofit 的一些知识点。

retrofit 的设计模式

retrofit 里面中使用了多种设计模式，以实现其灵活、可扩展和高性能的特性：

retrofit 的动态代理模式

retrofit 用了诸多的设计模式，其中最经典的莫过于动态代理模式了，在了解 retrofit 之前，我一直以为这样的网络请求形式是最直观的，参考以前写的基于Volley框架的返回数据的范型处理

Request.get(
    url = url,
    params = param,
    listener = object : OnRequestListener<Data> {
        override fun onSuccess(commonData: CommonData?, data: Data?) {}
        override fun onFailure(errorCode: Int, errorMessage: String?) {}
    })

以为这样很直观，逻辑也很清晰，实则 代码冗余，回调嵌套，如果有多个连续的请求，代码会变得难以维护，而 retrofit 搭配上协程能这样实现：

val data = apiService.getXXX(params)

简单到不能再简单，动态代理功不可没，上面的 apiService 是一个接口，由：retrofit.create(ApiInterface::class.java) 生成其实例，动态代理其核心实现：

public <T> T create(final Class<T> service) {
    validateServiceInterface(service);
    return (T)
        Proxy.newProxyInstance(
            service.getClassLoader(),
            new Class<?>[] {service},
            new InvocationHandler() {
              private final Platform platform = Platform.get();
              private final Object[] emptyArgs = new Object[0];

              @Override
              public @Nullable Object invoke(Object proxy, Method method, @Nullable Object[] args) throws Throwable {
                // ....
                return platform.isDefaultMethod(method)
                    ? platform.invokeDefaultMethod(method, service, proxy, args)
                    : loadServiceMethod(method).invoke(args);
              }
            });
  }

由loadServiceMethod(method).invoke(args) 负责将接口方法（通过 Java 反射获取的 Method 对象）解析并转换为一个可执行的 HTTP 请求。

Proxy.newProxyInstance 方法，参数：

• ClassLoader loader 用于加载代理类的类加载器。

• Class<?>[] interfaces 代理类需要实现的接口数组，代理对象将实现这些接口，并拦截对这些接口方法的调用。只能代理实现了接口的类，不能代理没有接口的类。

• InvocationHandler h
  调用处理器，负责处理代理对象上的方法调用。每次调用代理对象的方法时，都会调用 InvocationHandler 的 invoke 方法。对于 Retrofit 的接口我们并没有去“实现”它的方法，所有的逻辑都由` retrofit.create()方法里面返回的 InvocationHandler实现的 invoke方法实现的。

核心实现逻辑

协程的支持

Retrofit 支持多种异步编程模型，包括回调、RxJava 和协程等，这里主要记录一下对协程的支持。普通方法和异步逻辑的分叉在：

if (!isKotlinSuspendFunction) {
      return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
    } else if (continuationWantsResponse) {
      //noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
      return (HttpServiceMethod<ResponseT, ReturnT>)
          new SuspendForResponse<>(
              requestFactory,
              callFactory,
              responseConverter,
              (CallAdapter<ResponseT, Call<ResponseT>>) callAdapter);
    } else {
      //noinspection unchecked Kotlin compiler guarantees ReturnT to be Object.
//...
    }

上面代码关键变量isKotlinSuspendFunction ，用于判断是否为协程方法（suspend修饰），判断逻辑很简单，只需要判定方法最后一个参数是否为Continuation.class 即可。这里的分叉逻辑都继承自HttpServiceMethod<T>实现 ReturnT adapt(Call<ResponseT> call, Object[] args)这个抽象方法，这也是 retrofit 使用 适配器模式的地方，把不同的调用方式进行统一。对于协程方式的调用有实现：

protected Object adapt(Call<ResponseT> call, Object[] args) {
      call = callAdapter.adapt(call);

      //noinspection unchecked Checked by reflection inside RequestFactory.
      Continuation<Response<ResponseT>> continuation =
          (Continuation<Response<ResponseT>>) args[args.length - 1];

      // See SuspendForBody for explanation about this try/catch.
      try {
        return KotlinExtensions.awaitResponse(call, continuation);
      } catch (Exception e) {
        return.suspendAndThrow(e, continuation);
      }
    }

suspend fun <T> Call<T>.awaitResponse(): Response<T> {
  return suspendCancellableCoroutine { continuation ->
    continuation.invokeOnCancellation {
      cancel()
    }
    enqueue(object : Callback<T> {
      override fun onResponse(call: Call<T>, response: Response<T>) {
        continuation.resume(response)
      }

      override fun onFailure(call: Call<T>, t: Throwable) {
        continuation.resumeWithException(t)
      }
    })
  }
}

这里就一切都明朗了，实现了 Call的扩展方法，这里的 Call并不是 okhttp3.Call，它只是 retrofit okhttp3.Call为方便框架整体逻辑的处理而定义的，比如 retrofit 的 Call 是泛型化的，可以直接返回解析后的对象，enqueue同理。

suspendCancellableCoroutine方法是实现协程方法的关键，它可以将基于回调的异步操作封装成一个挂起函数，怎么理解呢？对 扩展方法awaitResponse反编译可以看到方法定义是这样的：

public static final Object await(@NotNull Call $this$await, @NotNull Continuation $completion) 

其实这里跟定义一个 listener去监听方法的回调有点像，这个方法改写成 listener的实现话大概就是这样：

fun <T> Call<T>.awaitResponse(listener:Listener<T>): Response<T> {
        enqueue(object : Callback<T> {
            override fun onResponse(call: Call<T>, response: Response<T>) {
                Listener.resume(response)
            }

            override fun onFailure(call: Call<T>, t: Throwable) {
                Listener.resumeWithException(t)
            }
        })
    }
}

可看到改造实现需要传递一个 listener，哪这个 listener是什么？前面其有如何判断一个方法是否为协程的方法的逻辑：判定方法最后一个参数是否为Continuation.class 即可。这里的 listener 其实可以等价于 一个 Continuation实例，kotlin 的协程库帮我们实现了对应的封装，对于使用我们不会直观地感受Continuation的存在，实际它贯穿整个协程。关于协程这里不再赘述，可以查看 《带着问题分析Kotlin协程原理》了解。

返回数据格式的解析

对于Converter,在协程和普通方法调用分叉逻辑的前面点：

Converter<ResponseBody, ResponseT> responseConverter = createResponseConverter(retrofit, method, responseType);

createResponseConverter之后一路走到

public <T> Converter<ResponseBody, T> nextResponseBodyConverter(
    @Nullable Converter.Factory skipPast, Type type, Annotation[] annotations) {
  Objects.requireNonNull(type, "type == null");
  Objects.requireNonNull(annotations, "annotations == null");

  int start = converterFactories.indexOf(skipPast) + 1;
  for (int i = start, count = converterFactories.size(); i < count; i++) {
    Converter<ResponseBody, ?> converter =
        converterFactories.get(i).responseBodyConverter(type, annotations, this);
    if (converter != null) {
      //noinspection unchecked
      return (Converter<ResponseBody, T>) converter;
    }
  }
}

converterFactories 的值就是在 retrofit 初始化的时候进行使用 public Builder addConverterFactory(Converter.Factory factory)添加的值。可以看到是按添加到List<Converter.Factory> converterFactories里面的顺序进行选择的，默认GsonConverterFactory实现了利用 Gson进行数据转化 ，如果我们自己实现Converter.Factory的接口的话，那么可以根据一定的规则判断是否要返回我们自定义的 Converter，如果不需要使用就返回 null，会自动匹配下一个能使用的 Converter。注意这里并不会因为前一个 Converter 解析失败而自动尝试使用下一个Converter（当然，你可以在自定义的Converter里面做类似这样的尝试策略）。

总结

• 这篇文章深入剖析了 Retrofit 框架的核心设计模式、动态代理机制、协程支持以及数据解析逻辑，通过源码分析和手写实现，帮助读者更好地理解 Retrofit 的工作原理，并强调了理论与实践结合的重要性。

• 为加深对 retrofit 的理解，可以尝试手写核心实现，自己尝试的的代码在 vmfit

• 附一张 retrofit 的全流程图，来源：https://cloud.tencent.com/developer/article/1683334

一、背景和疑问

在Android中，当我们谈到 布局优化、卡顿优化 时，通常都知道 需要减少布局层级、减少主线程耗时操作，这样可以减少丢帧。如果丢帧比较严重，那么界面可能会有明显的卡顿感。我们知道 通常手机刷新是每秒60次，即每隔16.6ms刷新一次。 问题来了：

1. 丢帧(掉帧) ，是说 这一帧延迟显示 还是丢弃不再显示 ？
2. 布局层级较多/主线程耗时 是如何造成 丢帧的呢？
3. 16.6ms刷新一次 是啥意思？是每16.6ms都走一次 measure/layout/draw ？
4. measure/layout/draw 走完，界面就立刻刷新了吗?
5. 如果界面没动静止了，还会刷新吗？
6. 可能你知道VSYNC，这个具体指啥？在屏幕刷新中如何工作的？
7. 可能你还听过屏幕刷新使用 双缓存、三缓存，这又是啥意思呢？
8. 可能你还听过神秘的Choreographer，这又是干啥的？

二、显示系统基础知识

在一个典型的显示系统中，一般包括CPU、GPU、Display三个部分， CPU负责计算帧数据，把计算好的数据交给GPU，GPU会对图形数据进行渲染，渲染好后放到buffer(图像缓冲区)里存起来，然后Display（屏幕或显示器）负责把buffer里的数据呈现到屏幕上。如下图：

单缓存，从缓存映射到屏幕。

2.1 基础概念

• 屏幕刷新频率 一秒内屏幕刷新的次数（一秒内显示了多少帧的图像），单位 Hz（赫兹），如常见的 60 Hz。刷新频率取决于硬件的固定参数（不会变的）。
• 逐行扫描 显示器并不是一次性将画面显示到屏幕上，而是从左到右边，从上到下逐行扫描，顺序显示整屏的一个个像素点，不过这一过程快到人眼无法察觉到变化。以 60 Hz 刷新率的屏幕为例，这一过程即 1000 / 60 ≈ 16ms。
• 帧率 （Frame Rate） 表示 GPU 在一秒内绘制操作的帧数，单位 fps。例如在电影界采用 24 帧的速度足够使画面运行的非常流畅。而 Android 系统则采用更加流程的 60 fps，即每秒钟GPU最多绘制 60 帧画面。帧率是动态变化的，例如当画面静止时，GPU 是没有绘制操作的，屏幕刷新的还是buffer中的数据，即GPU最后操作的帧数据。
• 画面撕裂（tearing） 一个屏幕内的数据来自2个不同的帧，画面会出现撕裂感，如下图

明显看出画面错位的位置，这就是画面撕裂。

2.2 双缓存

2.2.1 画面撕裂 原因

屏幕刷新频是固定的，比如每16.6ms从buffer取数据显示完一帧，理想情况下帧率和刷新频率保持一致，即每绘制完成一帧，显示器显示一帧。但是CPU/GPU写数据是不可控的，所以会出现buffer里有些数据根本没显示出来就被重写了，即buffer里的数据可能是来自不同的帧的， 当屏幕刷新时，此时它并不知道buffer的状态，因此从buffer抓取的帧并不是完整的一帧画面，即出现画面撕裂。

简单说就是Display在显示的过程中，buffer内数据被CPU/GPU修改，导致画面撕裂。

2.2.2 双缓存

那咋解决画面撕裂呢？答案是使用 双缓存。

由于图像绘制和屏幕读取 使用的是同个buffer，所以屏幕刷新时可能读取到的是不完整的一帧画面。

双缓存，让绘制和显示器拥有各自的buffer：GPU 始终将完成的一帧图像数据写入到 Back Buffer，而显示器使用 Frame Buffer，当屏幕刷新时，Frame Buffer 并不会发生变化，当Back buffer准备就绪后，它们才进行交换。如下图：

双缓存，CPU/GPU写数据到Back Buffer，显示器从Frame Buffer取数据

2.2.3 VSync

问题又来了：什么时候进行两个buffer的交换呢？

假如是 Back buffer准备完成一帧数据以后就进行，那么如果此时屏幕还没有完整显示上一帧内容的话，肯定是会出问题的。看来只能是等到屏幕处理完一帧数据后，才可以执行这一操作了。

当扫描完一个屏幕后，设备需要重新回到第一行以进入下一次的循环，此时有一段时间空隙，称为VerticalBlanking Interval(VBI)。那，这个时间点就是我们进行缓冲区交换的最佳时间。因为此时屏幕没有在刷新，也就避免了交换过程中出现 screen tearing的状况。

VSync(垂直同步)是VerticalSynchronization的简写，它利用VBI时期出现的vertical sync pulse（垂直同步脉冲）来保证双缓冲在最佳时间点才进行交换。另外，交换是指各自的内存地址，可以认为该操作是瞬间完成。

所以说V-sync这个概念并不是Google首创的，它在早年的PC机领域就已经出现了。

三、Android屏幕刷新机制

3.1 Android4.1之前的问题

具体到Android中，在Android4.1之前，屏幕刷新也遵循 上面介绍的 双缓存+VSync 机制。如下图：

双缓存会在VSync脉冲时交换，但CPU/GPU绘制是随机的

以时间的顺序来看下将会发生的过程：

1. Display显示第0帧数据，此时CPU和GPU渲染第1帧画面，且在Display显示下一帧前完成
2. 因为渲染及时，Display在第0帧显示完成后，也就是第1个VSync后，缓存进行交换，然后正常显示第1帧
3. 接着第2帧开始处理，是直到第2个VSync快来前才开始处理的。
4. 第2个VSync来时，由于第2帧数据还没有准备就绪，缓存没有交换，显示的还是第1帧。这种情况被Android开发组命名为“Jank”，即发生了丢帧。
5. 当第2帧数据准备完成后，它并不会马上被显示，而是要等待下一个VSync 进行缓存交换再显示。

所以总的来说，就是屏幕平白无故地多显示了一次第1帧。

原因是 第2帧的CPU/GPU计算 没能在VSync信号到来前完成 。

我们知道，双缓存的交换 是在Vsyn到来时进行，交换后屏幕会取Frame buffer内的新数据，而实际 此时的Back buffer 就可以供GPU准备下一帧数据了。如果 Vsyn到来时 CPU/GPU就开始操作的话，是有完整的16.6ms的，这样应该会基本避免jank的出现了（除非CPU/GPU计算超过了16.6ms）。 那如何让 CPU/GPU计算在 Vsyn到来时进行呢？

3.2 drawing with VSync

为了优化显示性能，Google在Android 4.1系统中对Android Display系统进行了重构，实现了Project Butter（黄油工程）：系统在收到VSync pulse后，将马上开始下一帧的渲染。即一旦收到VSync通知（16ms触发一次），CPU和GPU 才立刻开始计算然后把数据写入buffer。如下图：

VSync脉冲到来：双缓存交换，且开始CPU/GPU绘制 CPU/GPU根据VSYNC信号同步处理数据，可以让CPU/GPU有完整的16ms时间来处理数据，减少了jank。

一句话总结，VSync同步使得CPU/GPU充分利用了16.6ms时间，减少jank。

问题又来了，如果界面比较复杂，CPU/GPU的处理时间较长 超过了16.6ms呢？如下图：

虽然CPU/GPU开始在VSync，但超过16.6ms

1. 在第二个时间段内，但却因 GPU 还在处理 B 帧，缓存没能交换，导致 A 帧被重复显示。
2. 而B完成后，又因为缺乏VSync pulse信号，它只能等待下一个signal的来临。于是在这一过程中，有一大段时间是被浪费的。
3. 当下一个VSync出现时，CPU/GPU马上执行操作（A帧），且缓存交换，相应的显示屏对应的就是B。这时看起来就是正常的。只不过由于执行时间仍然超过16ms，导致下一次应该执行的缓冲区交换又被推迟了——如此循环反复，便出现了越来越多的“Jank”。

为什么 CPU 不能在第二个 16ms 处理绘制工作呢？

原因是只有两个 buffer，Back buffer正在被GPU用来处理B帧的数据， Frame buffer的内容用于Display的显示，这样两个buffer都被占用，CPU 则无法准备下一帧的数据。那么，如果再提供一个buffer，CPU、GPU 和显示设备都能使用各自的buffer工作，互不影响。

3.3 三缓存

三缓存就是在双缓冲机制基础上增加了一个 Graphic Buffer 缓冲区，这样可以最大限度的利用空闲时间，带来的坏处是多使用的一个 Graphic Buffer 所占用的内存。

三缓存

1. 第一个Jank，是不可避免的。但是在第二个 16ms 时间段，CPU/GPU 使用 第三个 Buffer 完成C帧的计算，虽然还是会多显示一次 A 帧，但后续显示就比较顺畅了，有效避免 Jank 的进一步加剧。
2. 注意在第3段中，A帧的计算已完成，但是在第4个vsync来的时候才显示，如果是双缓冲，那在第三个vynsc就可以显示了。

三缓冲有效利用了等待vysnc的时间，减少了jank，但是带来了延迟。 所以，是不是 Buffer 越多越好呢？这个是否定的，Buffer 正常还是两个，当出现 Jank 后三个足以。

以上就是Android屏幕刷新的原理了。

四、Choreographer

4.1 概述

上面讲到，Google在Android 4.1系统中对Android Display系统进行了优化：在收到VSync pulse后，将马上开始下一帧的渲染。即一旦收到VSync通知，CPU和GPU就立刻开始计算然后把数据写入buffer。本节就来讲 “drawing with VSync” 的实现——Choreographer。

• Choreographer，意为 舞蹈编导、编舞者。在这里就是指 对CPU/GPU绘制的指导—— 收到VSync信号 才开始绘制，保证绘制拥有完整的16.6ms，避免绘制的随机性。
• Choreographer，是一个Java类，包路径android.view.Choreographer。类注释是“协调动画、输入和绘图的计时”。
• 通常 应用层不会直接使用Choreographer，而是使用更高级的API，例如动画和View绘制相关的ValueAnimator.start()、View.invalidate()等。
• 业界一般通过Choreographer来监控应用的帧率。

4.2 源码分析

学习 Choreographer 可以帮助理解 每帧运行的原理，也可加深对 Handler机制、View绘制流程的理解，这样再去做UI优化、卡顿优化，思路会更清晰。

好了，下面开始源码分析了~

4.2.1 入口 和 实例创建

在《Window和WindowManager》、《Activity的启动过程详解》中介绍过，Activity启动 走完onResume方法后，会进行window的添加。window添加过程会 调用ViewRootImpl的setView()方法，setView()方法会调用requestLayout()方法来请求绘制布局，requestLayout()方法内部又会走到scheduleTraversals()方法，最后会走到performTraversals()方法，接着到了我们熟知的测量、布局、绘制三大流程了。

另外，查看源码发现，当我们使用 ValueAnimator.start()、View.invalidate()时，最后也是走到ViewRootImpl的scheduleTraversals()方法。（View.invalidate()内部会循环获取ViewParent直到ViewRootImpl的invalidateChildInParent()方法，然后走到scheduleTraversals()，可自行查看源码 ）

即 所有UI的变化都是走到ViewRootImpl的scheduleTraversals()方法。

那么问题又来了，scheduleTraversals() 到 performTraversals() 中间 经历了什么呢？是立刻执行吗？答案很显然是否定的，根据我们上面的介绍，在VSync信号到来时才会执行绘制，即performTraversals()方法。下面来瞅瞅这是如何实现的：

//ViewRootImpl.java
void scheduleTraversals() {
    if (!mTraversalScheduled) {
        //此字段保证同时间多次更改只会刷新一次，例如TextView连续两次setText(),也只会走一次绘制流程
        mTraversalScheduled = true;
        //添加同步屏障，屏蔽同步消息，保证VSync到来立即执行绘制
        mTraversalBarrier = mHandler.getLooper().getQueue().postSyncBarrier();
        //mTraversalRunnable是TraversalRunnable实例，最终走到run()，也即doTraversal();
        mChoreographer.postCallback(
                Choreographer.CALLBACK_TRAVERSAL, mTraversalRunnable, null);
        if (!mUnbufferedInputDispatch) {
            scheduleConsumeBatchedInput();
        }
        notifyRendererOfFramePending();
        pokeDrawLockIfNeeded();
    }
}

final class TraversalRunnable implements Runnable {
    @Override
    public void run() {
        doTraversal();
    }
}
final TraversalRunnable mTraversalRunnable = new TraversalRunnable();

void doTraversal() {
    if (mTraversalScheduled) {
        mTraversalScheduled = false;
        //移除同步屏障
        mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
        ...
        //开始三大绘制流程
        performTraversals();
        ...
    }
}

主要有以下逻辑：

1. 首先使用mTraversalScheduled字段保证同时间多次更改只会刷新一次，例如TextView连续两次setText()，也只会走一次绘制流程。
2. 然后把当前线程的消息队列Queue添加了同步屏障，这样就屏蔽了正常的同步消息，保证VSync到来后立即执行绘制，而不是要等前面的同步消息。后面会具体分析同步屏障和异步消息的代码逻辑。
3. 调用了mChoreographer.postCallback()方法，发送一个会在下一帧执行的回调，即在下一个VSync到来时会执行TraversalRunnable—>doTraversal()—->performTraversals()—>绘制流程。

接下来，就是分析的重点——Choreographer。我们先看它的实例mChoreographer，是在ViewRootImpl的构造方法内使用Choreographer.getInstance()创建：

Choreographer mChoreographer;

//ViewRootImpl实例是在添加window时创建
public ViewRootImpl(Context context, Display display) {
    ...
    mChoreographer = Choreographer.getInstance();
    ...
}

我们先来看看Choreographer.getInstance()：

public static Choreographer getInstance() {
    return sThreadInstance.get();
}

private static final ThreadLocal<Choreographer> sThreadInstance =
        new ThreadLocal<Choreographer>() {
    @Override
    protected Choreographer initialValue() {
        Looper looper = Looper.myLooper();
        if (looper == null) {
            //当前线程要有looper，Choreographer实例需要传入
            throw new IllegalStateException("The current thread must have a looper!");
        }
        Choreographer choreographer = new Choreographer(looper, VSYNC_SOURCE_APP);
        if (looper == Looper.getMainLooper()) {
            mMainInstance = choreographer;
        }
        return choreographer;
    }
};

看到这里 如你对Handler机制中looper比较熟悉的话，应该知道 Choreographer和Looper一样 是线程单例的。且当前线程要有looper，Choreographer实例需要传入。接着看看Choreographer构造方法：

private Choreographer(Looper looper, int vsyncSource) {
    mLooper = looper;
    //使用当前线程looper创建 mHandler
    mHandler = new FrameHandler(looper);
    //USE_VSYNC 4.1以上默认是true，表示 具备接受VSync的能力，这个接受能力就是FrameDisplayEventReceiver
    mDisplayEventReceiver = USE_VSYNC
            ? new FrameDisplayEventReceiver(looper, vsyncSource)
            : null;
    mLastFrameTimeNanos = Long.MIN_VALUE;

    // 计算一帧的时间，Android手机屏幕是60Hz的刷新频率，就是16ms
    mFrameIntervalNanos = (long)(1000000000 / getRefreshRate());

    // 创建一个链表类型CallbackQueue的数组，大小为5，
    //也就是数组中有五个链表，每个链表存相同类型的任务：输入、动画、遍历绘制等任务（CALLBACK_INPUT、CALLBACK_ANIMATION、CALLBACK_TRAVERSAL）
    mCallbackQueues = new CallbackQueue[CALLBACK_LAST + 1];
    for (int i = 0; i <= CALLBACK_LAST; i++) {
        mCallbackQueues[i] = new CallbackQueue();
    }
    // b/68769804: For low FPS experiments.
    setFPSDivisor(SystemProperties.getInt(ThreadedRenderer.DEBUG_FPS_DIVISOR, 1));
}

代码中都有注释，创建了一个mHandler、VSync事件接收器mDisplayEventReceiver、任务链表数组mCallbackQueues。FrameHandler、FrameDisplayEventReceiver、CallbackQueue后面会一一说明。

4.2.2 安排任务—postCallback

回头看mChoreographer.postCallback(Choreographer.CALLBACK_TRAVERSAL, mTraversalRunnable, null)方法，注意到第一个参数是CALLBACK_TRAVERSAL，表示回调任务的类型，共有以下5种类型：

//输入事件，首先执行
public static final int CALLBACK_INPUT = 0;
//动画，第二执行
public static final int CALLBACK_ANIMATION = 1;
//插入更新的动画，第三执行
public static final int CALLBACK_INSETS_ANIMATION = 2;
//绘制，第四执行
public static final int CALLBACK_TRAVERSAL = 3;
//提交，最后执行，
public static final int CALLBACK_COMMIT = 4;

五种类型任务对应存入对应的CallbackQueue中，每当收到 VSYNC 信号时，Choreographer 将首先处理 INPUT 类型的任务，然后是 ANIMATION 类型，最后才是 TRAVERSAL 类型。

postCallback()内部调用postCallbackDelayed()，接着又调用postCallbackDelayedInternal()，来瞅瞅：

private void postCallbackDelayedInternal(int callbackType,
        Object action, Object token, long delayMillis) {
    ...
    synchronized (mLock) {
        // 当前时间
        final long now = SystemClock.uptimeMillis();
        // 加上延迟时间
        final long dueTime = now + delayMillis;
        //取对应类型的CallbackQueue添加任务
        mCallbackQueues[callbackType].addCallbackLocked(dueTime, action, token);

        if (dueTime <= now) {
            //立即执行
            scheduleFrameLocked(now);
        } else {
            //延迟运行，最终也会走到scheduleFrameLocked()
            Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_CALLBACK, action);
            msg.arg1 = callbackType;
            msg.setAsynchronous(true);
            mHandler.sendMessageAtTime(msg, dueTime);
        }
    }
}

首先取对应类型的CallbackQueue添加任务，action就是mTraversalRunnable，token是null。CallbackQueue的addCallbackLocked()就是把 dueTime、action、token组装成CallbackRecord后 存入CallbackQueue的下一个节点，具体代码比较简单，不再跟进。

然后注意到如果没有延迟会执行scheduleFrameLocked()方法，有延迟就会使用 mHandler发送MSG_DO_SCHEDULE_CALLBACK消息，并且注意到 使用msg.setAsynchronous(true)把消息设置成异步，这是因为前面设置了同步屏障，只有异步消息才会执行。我们看下mHandler的对这个消息的处理：

private final class FrameHandler extends Handler {
    public FrameHandler(Looper looper) {
        super(looper);
    }
    @Override
    public void handleMessage(Message msg) {
        switch (msg.what) {
            case MSG_DO_FRAME:
                // 执行doFrame,即绘制过程
                doFrame(System.nanoTime(), 0);
                break;
            case MSG_DO_SCHEDULE_VSYNC:
                //申请VSYNC信号，例如当前需要绘制任务时
                doScheduleVsync();
                break;
            case MSG_DO_SCHEDULE_CALLBACK:
                //需要延迟的任务，最终还是执行上述两个事件
                doScheduleCallback(msg.arg1);
                break;
        }
    }
}

直接使用doScheduleCallback方法，看看：

void doScheduleCallback(int callbackType) {
    synchronized (mLock) {
        if (!mFrameScheduled) {
            final long now = SystemClock.uptimeMillis();
            if (mCallbackQueues[callbackType].hasDueCallbacksLocked(now)) {
                scheduleFrameLocked(now);
            }
        }
    }
}

发现也是走到这里，即延迟运行最终也会走到scheduleFrameLocked()，跟进看看：

private void scheduleFrameLocked(long now) {
    if (!mFrameScheduled) {
        mFrameScheduled = true;
        //开启了VSYNC
        if (USE_VSYNC) {
            if (DEBUG_FRAMES) {
                Log.d(TAG, "Scheduling next frame on vsync.");
            }

            //当前执行的线程，是否是mLooper所在线程
            if (isRunningOnLooperThreadLocked()) {
                //申请 VSYNC 信号
                scheduleVsyncLocked();
            } else {
                // 若不在，就用mHandler发送消息到原线程，最后还是调用scheduleVsyncLocked方法
                Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_VSYNC);
                msg.setAsynchronous(true);//异步
                mHandler.sendMessageAtFrontOfQueue(msg);
            }
        } else {
            // 如果未开启VSYNC则直接doFrame方法（4.1后默认开启）
            final long nextFrameTime = Math.max(
                    mLastFrameTimeNanos / TimeUtils.NANOS_PER_MS + sFrameDelay, now);
            if (DEBUG_FRAMES) {
                Log.d(TAG, "Scheduling next frame in " + (nextFrameTime - now) + " ms.");
            }
            Message msg = mHandler.obtainMessage(MSG_DO_FRAME);
            msg.setAsynchronous(true);//异步
            mHandler.sendMessageAtTime(msg, nextFrameTime);
        }
    }
}

1. 如果系统未开启 VSYNC 机制，此时直接发送 MSG_DO_FRAME 消息到 FrameHandler。注意查看上面贴出的 FrameHandler 代码，此时直接执行 doFrame 方法。
2. Android 4.1 之后系统默认开启 VSYNC，在 Choreographer 的构造方法会创建一个 FrameDisplayEventReceiver，scheduleVsyncLocked 方法将会通过它申请 VSYNC 信号。
3. isRunningOnLooperThreadLocked 方法，其内部根据 Looper 判断是否在原线程，否则发送消息到 FrameHandler。最终还是会调用 scheduleVsyncLocked 方法申请 VSYNC 信号。

到这里，FrameHandler的作用很明显里了：发送异步消息（因为前面设置了同步屏障）。有延迟的任务发延迟消息、不在原线程的发到原线程、没开启VSYNC的直接走 doFrame 方法取执行绘制。

4.2.3 申请和接受VSync

好了， 接着就看 scheduleVsyncLocked 方法是如何申请 VSYNC 信号的。猜测肯定申请 VSYNC 信号后，信号到来时也是走doFrame() 方法，doFrame()后面再看。先跟进scheduleVsyncLocked():

private void scheduleVsyncLocked() {
    mDisplayEventReceiver.scheduleVsync();
}

很简单，调用mDisplayEventReceiver的scheduleVsync()方法，mDisplayEventReceiver是Choreographer构造方法中创建，是FrameDisplayEventReceiver 的实例。FrameDisplayEventReceiver是 DisplayEventReceiver 的子类，DisplayEventReceiver 是一个 abstract class：

public DisplayEventReceiver(Looper looper, int vsyncSource) {
    if (looper == null) {
        throw new IllegalArgumentException("looper must not be null");
    }

    mMessageQueue = looper.getQueue();
    // 注册VSYNC信号监听者
    mReceiverPtr = nativeInit(new WeakReference<DisplayEventReceiver>(this), mMessageQueue,
            vsyncSource);

    mCloseGuard.open("dispose");
}

在 DisplayEventReceiver 的构造方法会通过 JNI 创建一个 IDisplayEventConnection 的 VSYNC 的监听者。

FrameDisplayEventReceiver的scheduleVsync()就是在 DisplayEventReceiver中：

public void scheduleVsync() {
    if (mReceiverPtr == 0) {
        Log.w(TAG, "Attempted to schedule a vertical sync pulse but the display event "
                + "receiver has already been disposed.");
    } else {
        // 申请VSYNC中断信号，会回调onVsync方法
        nativeScheduleVsync(mReceiverPtr);
    }
}

那么scheduleVsync()就是使用native方法nativeScheduleVsync()去申请VSYNC信号。这个native方法就看不了了，只需要知道VSYNC信号的接受回调是onVsync()，我们直接看onVsync()：

/**
 * 接收到VSync脉冲时 回调
 * @param timestampNanos VSync脉冲的时间戳
 * @param physicalDisplayId Stable display ID that uniquely describes a (display, port) pair.
 * @param frame 帧号码，自增
 */
@UnsupportedAppUsage
public void onVsync(long timestampNanos, long physicalDisplayId, int frame) {
}

具体实现是在FrameDisplayEventReceiver中：

private final class FrameDisplayEventReceiver extends DisplayEventReceiver
        implements Runnable {
    private boolean mHavePendingVsync;
    private long mTimestampNanos;
    private int mFrame;

    public FrameDisplayEventReceiver(Looper looper, int vsyncSource) {
        super(looper, vsyncSource);
    }

    @Override
    public void onVsync(long timestampNanos, long physicalDisplayId, int frame) {
        // Post the vsync event to the Handler.
        // The idea is to prevent incoming vsync events from completely starving
        // the message queue.  If there are no messages in the queue with timestamps
        // earlier than the frame time, then the vsync event will be processed immediately.
        // Otherwise, messages that predate the vsync event will be handled first.
        long now = System.nanoTime();
        if (timestampNanos > now) {
            Log.w(TAG, "Frame time is " + ((timestampNanos - now) * 0.000001f)
                    + " ms in the future!  Check that graphics HAL is generating vsync "
                    + "timestamps using the correct timebase.");
            timestampNanos = now;
        }

        if (mHavePendingVsync) {
            Log.w(TAG, "Already have a pending vsync event.  There should only be "
                    + "one at a time.");
        } else {
            mHavePendingVsync = true;
        }

        mTimestampNanos = timestampNanos;
        mFrame = frame;
        //将本身作为runnable传入msg， 发消息后 会走run()，即doFrame()，也是异步消息
        Message msg = Message.obtain(mHandler, this);
        msg.setAsynchronous(true);
        mHandler.sendMessageAtTime(msg, timestampNanos / TimeUtils.NANOS_PER_MS);
    }

    @Override
    public void run() {
        mHavePendingVsync = false;
        doFrame(mTimestampNanos, mFrame);
    }
}

onVsync()中，将接收器本身作为runnable传入异步消息msg，并使用mHandler发送msg，最终执行的就是doFrame()方法了。

注意一点是，onVsync()方法中只是使用mHandler发送消息到MessageQueue中，不一定是立刻执行，如何MessageQueue中前面有较为耗时的操作，那么就要等完成，才会执行本次的doFrame()。

4.2.4 doFrame

和上面猜测一样，申请VSync信号接收到后确实是走 doFrame()方法，那么就来看看Choreographer的doFrame()：

void doFrame(long frameTimeNanos, int frame) {
    final long startNanos;
    synchronized (mLock) {
        if (!mFrameScheduled) {
            return; // no work to do
        }

        ...
        // 预期执行时间
        long intendedFrameTimeNanos = frameTimeNanos;
        startNanos = System.nanoTime();
        // 超时时间是否超过一帧的时间（这是因为MessageQueue虽然添加了同步屏障，但是还是有正在执行的同步任务，导致doFrame延迟执行了）
        final long jitterNanos = startNanos - frameTimeNanos;
        if (jitterNanos >= mFrameIntervalNanos) {
            // 计算掉帧数
            final long skippedFrames = jitterNanos / mFrameIntervalNanos;
            if (skippedFrames >= SKIPPED_FRAME_WARNING_LIMIT) {
                // 掉帧超过30帧打印Log提示
                Log.i(TAG, "Skipped " + skippedFrames + " frames!  "
                        + "The application may be doing too much work on its main thread.");
            }
            final long lastFrameOffset = jitterNanos % mFrameIntervalNanos;
            ...
            frameTimeNanos = startNanos - lastFrameOffset;
        }

        ...

        mFrameInfo.setVsync(intendedFrameTimeNanos, frameTimeNanos);
        // Frame标志位恢复
        mFrameScheduled = false;
        // 记录最后一帧时间
        mLastFrameTimeNanos = frameTimeNanos;
    }

    try {
        // 按类型顺序 执行任务
        Trace.traceBegin(Trace.TRACE_TAG_VIEW, "Choreographer#doFrame");
        AnimationUtils.lockAnimationClock(frameTimeNanos / TimeUtils.NANOS_PER_MS);

        mFrameInfo.markInputHandlingStart();
        doCallbacks(Choreographer.CALLBACK_INPUT, frameTimeNanos);

        mFrameInfo.markAnimationsStart();
        doCallbacks(Choreographer.CALLBACK_ANIMATION, frameTimeNanos);
        doCallbacks(Choreographer.CALLBACK_INSETS_ANIMATION, frameTimeNanos);

        mFrameInfo.markPerformTraversalsStart();
        doCallbacks(Choreographer.CALLBACK_TRAVERSAL, frameTimeNanos);

        doCallbacks(Choreographer.CALLBACK_COMMIT, frameTimeNanos);
    } finally {
        AnimationUtils.unlockAnimationClock();
        Trace.traceEnd(Trace.TRACE_TAG_VIEW);
    }
}

上面都有注释了很好理解，接着看任务的具体执行doCallbacks 方法：

void doCallbacks(int callbackType, long frameTimeNanos) {
    CallbackRecord callbacks;
    synchronized (mLock) {

        final long now = System.nanoTime();
        // 根据指定的类型CallbackkQueue中查找到达执行时间的CallbackRecord
        callbacks = mCallbackQueues[callbackType].extractDueCallbacksLocked(now / TimeUtils.NANOS_PER_MS);
        if (callbacks == null) {
            return;
        }
        mCallbacksRunning = true;

        //提交任务类型
        if (callbackType == Choreographer.CALLBACK_COMMIT) {
            final long jitterNanos = now - frameTimeNanos;
            if (jitterNanos >= 2 * mFrameIntervalNanos) {
                final long lastFrameOffset = jitterNanos % mFrameIntervalNanos
                        + mFrameIntervalNanos;
                if (DEBUG_JANK) {
                    Log.d(TAG, "Commit callback delayed by " + (jitterNanos * 0.000001f)
                            + " ms which is more than twice the frame interval of "
                            + (mFrameIntervalNanos * 0.000001f) + " ms!  "
                            + "Setting frame time to " + (lastFrameOffset * 0.000001f)
                            + " ms in the past.");
                    mDebugPrintNextFrameTimeDelta = true;
                }
                frameTimeNanos = now - lastFrameOffset;
                mLastFrameTimeNanos = frameTimeNanos;
            }
        }
    }
    try {
        // 迭代执行队列所有任务
        for (CallbackRecord c = callbacks; c != null; c = c.next) {
            // 回调CallbackRecord的run，其内部回调Callback的run
            c.run(frameTimeNanos);
        }
    } finally {
        synchronized (mLock) {
            mCallbacksRunning = false;
            do {
                final CallbackRecord next = callbacks.next;
                //回收CallbackRecord
                recycleCallbackLocked(callbacks);
                callbacks = next;
            } while (callbacks != null);
        }
    }
}

主要内容就是取对应任务类型的队列，遍历队列执行所有任务，执行任务是 CallbackRecord的 run 方法：

private static final class CallbackRecord {
    public CallbackRecord next;
    public long dueTime;
    public Object action; // Runnable or FrameCallback
    public Object token;

    @UnsupportedAppUsage
    public void run(long frameTimeNanos) {
        if (token == FRAME_CALLBACK_TOKEN) {
            // 通过postFrameCallback 或 postFrameCallbackDelayed，会执行这里
            ((FrameCallback)action).doFrame(frameTimeNanos);
        } else {
            //取出Runnable执行run()
            ((Runnable)action).run();
        }
    }
}