6.3 运转核心：处理链、事件与状态跃迁

6.3 运转核心：处理链、事件与状态跃迁

本节摘要：元件的心脏是处理函数：缓冲进来、映射内存、加工、按流返回值交还。围绕它的是事件应答与状态跃迁两套外围约定。本节以水印元件的完整实现为线索，讲透内存映射、流返回值传播、冲刷应答与状态资源管理四组关键机制，是第六章的干货核心节。

元件的运转心脏

站在视频滤镜基类的肩膀上，水印元件的核心只剩一个函数：输入一帧、输出一帧。函数签名与职责高度紧凑——拿到输入缓冲、映射内存、按帧元信息定位水印区域、写像素、把缓冲交给基类发往下游。先看完整骨架再逐组拆解。

// 视频滤镜基类的逐帧处理函数：输入输出各一帧
static GstFlowReturn
my_transform_frame(GstVideoFilter *filter, GstVideoFrame *in,
                   GstVideoFrame *out) {
    GstMyWatermark *self = GST_MY_WATERMARK(filter);
    // 一 只读映射输入 只写映射输出 基类已保证尺寸合法
    // 二 依帧元信息取宽高与排布 选对应像素函数
    // 三 取锁 保护时间缓存与字体资源
    g_mutex_lock(&self->lock);
    draw_timestamp(self, out);          // 四 逐平面写像素
    g_mutex_unlock(&self->lock);
    return GST_FLOW_OK;                  // 五 成功交还
}
​

内存映射是铁规矩。缓冲的内存可能来自普通堆、显存、共享内存，逐帧加工必须经过映射接口拿到可访问的指针，绝不允许直接摸缓冲内部结构。映射接口还带访问模式声明（只读或读写），既是自我文档，也让框架做访问校验。

流返回值是错误传播的总线。处理函数的返回值不是布尔，而是一组流状态码：成功、冲刷中、非连贯、未链接、未协商、错误。它们的传播规则像多米诺：任何一个元件返回非成功，上游逐级停推、管线逐级上报。代码里的对应纪律是——每个可能失败的调用都检查返回值并立即回传，吞掉一个返回值，下游就多一分"莫名停流"的排障成本。

事件应答：上行的邮差

处理链管数据，事件应答管控制。基类已代答多数事件，需要元件亲自处理的主要是冲刷停止——冲刷结束后到达，语义是"新段即将开始，请复位"。水印元件的正确动作：清掉时间缓存、复位字体布局。另一类要亲自应答的是自定义事件：若上游发来带业务载荷的事件（比如标注了场景切换），元件要识别并选择性转发或消费。应答函数返回真假代表"是否继续上行"，吞掉该转发的事件是动态管线失灵的隐蔽来源。

// 冲刷停止后的复位：清缓存 保字体 轻量完成
static gboolean my_sink_event(GstBaseTransform *base,
                              GstEvent *event) {
    GstMyWatermark *self = GST_MY_WATERMARK(base);
    switch (GST_EVENT_TYPE(event)) {
    case GST_EVENT_FLUSH_STOP:
        g_mutex_lock(&self->lock);
        self->last_ts = GST_CLOCK_TIME_NONE;
        g_mutex_unlock(&self->lock);
        break;
    default:
        break;
    }
    return GST_BASE_TRANSFORM_CLASS(parent_class)
           ->sink_event(base, event);   // 链回基类 默认应答
}
​

状态跃迁：资源的开与关

四种状态对应资源管理的四级台阶，元件要在跃迁回调里对号入座。空置到就绪：分配轻量资源（属性解析、字体引擎初始化）。就绪到暂停：此时能力集已定格，可以按定格规格分配帧级资源（行缓存、查找表）。暂停到播放：通常无事可做，除非要启动时钟相关的定时器。降级：逆序释放，尤其注意就绪到空置必须释放全部可重资源——字体引擎、线程、外部库上下文。资源放错台阶的典型症状：反复换文件后内存上涨（放高台该放的没放）或首次播放慢（把重活放到了播放态）。

⚠️ 常见坑：在处理函数里分配每帧资源。字体布局、行缓存的分配放在就绪到暂停的跃迁里一次完成，处理函数只做纯计算——高频路径上的每次分配与锁，都会在性能曲线上留痕。

属性与并发：元件的对外仪表盘

水印元件的属性（水印格式、位置、字号）按第二章的属性系统登记，运行中可改。并发纪律只有一条：属性写与帧处理可能同时发生，实例私有状态必须加互斥保护，处理函数里持锁时间压到最小（锁内不做字体渲染的重活，只做取值快照）。基类已保证同一时刻只有一个处理调用，帧间免锁；跨属性与帧的共享，自己上锁。

💡 关键直觉：把处理函数当高频纯函数写——输入帧加只读状态快照，输出帧；一切带副作用的初始化与释放都挪到状态跃迁的对应台阶。这个习惯直接决定元件能不能进生产线。

批处理与逐帧模式的取舍

视频滤镜基类支持两种处理形态：逐帧函数（输入输出各一帧，框架管映射与传递）与整块函数（一次给一整段可写映射，自己管帧计数）。水印用前者——逻辑简单、框架兜底；批处理视频（转码场景）用后者省一层拷贝。选型的判据是要不要改时间戳与帧数：不改用逐帧，要改（抽帧、合帧、变速）就得接管更多职责。新手从逐帧起步，遇到明确的性能证据再评估整块模式——又一次"证据先于优化"。

本节要点回顾

• 映射后访问：缓冲内存必经映射接口，访问模式要声明；
• 流返回值即错误总线：每个调用查返回值，失败立刻回传；
• 冲刷停止即复位令：清缓存应答，链回基类不吞事件；
• 资源按状态台阶分配：高频路径零分配零重锁；
• 属性与帧并发要上锁：锁内只做取值快照；
• 处理函数当纯函数写：这是元件可上生产线的门槛。

像素写好了，还差最后一块拼图：把逐帧计算结果作为元数据随水流走——下一节讲元数据扩展，也为第七章 AI 支路备好机制。