6.2 衬垫模板与协商对接：让元件接入管线

6.2 衬垫模板与协商对接：让元件接入管线

本节摘要：元件对外的全部规格就是它的衬垫模板：方向、可用性、能力集清单。本节站在制造方实现第三章的协商——模板怎么声明与登记、能力集字符串怎么写才既诚实又好相处、定格建议回调怎么实现、转化能力集怎么声明。学完这节，自制元件在任何管线里的协商行为都可控可预期。

制造方眼中的协商

第三章我们站在使用方看协商：模板求交集、建议提案、收敛定格。制造方的任务是把前两步做扎实——模板写得准确，协商空间就健康。一个元件的模板是它对外的承诺书：宣称太多（比如排布写成任意），运行时却处理不了，会在协商成功后当场崩溃；宣称太少（只认一种排布），又会让使用方处处补转换元件。原则一句话：宣称即能力，能力即宣称。

模板登记发生在类初始化函数里，一件元件的模板在类型层面共享。

// 水印元件的模板登记：静态字符串定义能力集
static GstStaticPadTemplate sink_template =
    GST_STATIC_PAD_TEMPLATE("sink", GST_PAD_SINK, GST_PAD_ALWAYS,
        GST_STATIC_CAPS("video/x-raw, format={ I420, NV12, RGBA }, "
                        "width=[1, 8192], height=[1, 8192], "
                        "framerate=[0/1, 240/1]"));
static GstStaticPadTemplate src_template =
    GST_STATIC_PAD_TEMPLATE("src", GST_PAD_SRC, GST_PAD_ALWAYS,
        GST_STATIC_CAPS("video/x-raw, format={ I420, NV12, RGBA }, "
                        "width=[1, 8192], height=[1, 8192], "
                        "framerate=[0/1, 240/1]"));

static void gst_my_watermark_class_init(gpointer klass, gpointer data) {
    GstElementClass *ec = GST_ELEMENT_CLASS(klass);
    gst_element_class_add_static_pad_template(ec, &sink_template);
    gst_element_class_add_static_pad_template(ec, &src_template);
    gst_element_class_set_metadata(ec, "时间水印", "Filter/Video",
        "在帧上烙时间水印", "你 <you@example>");
}
​

两块模板的方向常量一个进一个出，这是最不容易写错也最常被写反的地方。三个值得记住的正例：排布用枚举列出真正支持的集合（水印实现里这三种排布都有像素级代码支撑）；宽高用范围但上下限给真实边界（字体渲染模块到不了无限大）；帧率范围给到业务上限即可。元数据一段则贡献目录命令里的元件说明——分发给他人的元件，这段就是门面。

转化能力集：进与出不一致时怎么写

水印元件进出同规格，模板照抄即可。但另一类常见元件会改变格式——缩放器改变宽高、转换器改变排布、抽取器改变帧率。这类元件要在能力集里写转化映射：进出字段分开声明，框架据此构造协商图。这也是能力集语法里"分号分隔多组结构"的用途之一——进模板与出模板各自声明，字段间的对应关系由框架按同名字段推断。实现上的实用建议：先做不改规格的版本，转化需求出现时再升级模板，一步到位的通用转化元件是进阶课题。

定格建议：把业务偏好写进协商

协商第二步"下游提建议"对应制造方的定格建议回调：框架在收敛前询问元件"这几个字段你偏好什么值"。水印元件的正确答案与多数视频元件一致——透传上游的值：上游给什么宽高帧率，我出什么，绝不自作主张。

// 定格建议：优先透传 让协商空间由上下游决定
static gboolean my_fixate(GstMyWatermark *self, GstCaps *caps) {
    // 把范围与枚举按默认规则收敛 具体字段可按业务偏好覆写
    GstCaps *fixed = gst_caps_fixate(caps);
    gst_caps_unref(caps);
    // 水印不挑分辨率 交回框架默认策略即可
    return gst_caps_is_fixed(fixed);
}
​

哪类元件需要真正的偏好？源类（测试源默认建议常用分辨率）、合成类（按画布规格建议输出）、抽取类（建议目标帧率）。透传是默认美德，偏好是业务行为——分清这两者，协商日志里你的元件就从不添乱。

模板声明到协商成功的路径

模板的可用性再强调

第二章讲过衬垫可用性三档，制造方视角再看一眼。恒有垫：模板登记即存在，适合水印这类规格固定的元件。偶发垫：运行时按数据长出——解封装器的选择，需要配合信号广播（框架代发，实现方只需在恰当时机添加衬垫并设置能力集）。请求垫：使用方显式请求才创建——多路复用器的选择，要实现请求与释放的回调。水印两垫都用恒有，自制的第一个元件也建议从恒有垫起步，动态行为留给第二个迭代。

⚠️ 常见坑：模板宣称了运行时处理不了的排布。协商通过、数据一到，处理函数里没有对应分支，帧被静默损坏或直接崩溃。模板里的每一项，都必须在处理函数里有对应实现——发版前拿"遍历模板全部排布"当测试清单。

💡 关键直觉：模板是合同，处理函数是履约能力。签约前先盘点履约清单，是元件作者的第一职业素养。

本节要点回顾

• 模板即承诺：宣称即能力，能力即宣称，不多不少；
• 登记在类初始化：模板与元数据一次登记、全类型共享；
• 透传是默认美德：定格建议不添乱，业务偏好才覆写；
• 转化能力集分开声明：进出现格差异靠映射，先做不改规格版；
• 可用性三档各归其位：第一个元件从恒有垫起步；
• 发版前遍历模板当测试：每项宣称都要有实现兜底。

规格立好，下一节写运转核心——处理链、事件应答与状态切换，水印元件的心脏手术。