6.1 插件工程起步：工具链与基类选型

6.1 插件工程起步：工具链与基类选型

本节摘要：开模前的两件事——备好工具链、选对基类。工具链最小清单是编译环境加官方脚手架模板，一条装载验证命令走通全链。基类选型是元件设计的最大杠杆：变换基类适合整体加工、视频滤镜基类适合逐帧处理、源与聚合基类各管一头。本节给出选型决策图与水印元件的选型推演，是第六章的开工节。

开模前的两笔账

第一笔账：自制还是组合。水印需求评估时先查现成元件——文字渲染元件存在，但时间格式、位置逻辑、多语言字体的定制需求叠上去，组合方案变成一堆属性开关的杂技。判断标准很简单：定制逻辑塞进现成元件的属性体系里还算自然，就组合；要靠外部胶水代码逐帧干预，就自制。第二笔账：自制的成本。一个维护良好的元件要处理协商、冲刷、状态、内存、错误传播五类事务，好在基类把其中大半已经包办——这就要说到脚手架。

工具链的最小清单：编译工具链、开发头文件包、官方脚手架模板集。脚手架的用法是"给一个样板名，生成一整套骨架"——类型定义、boilerplate 宏、衬垫模板占位、处理函数空壳，全部就位。生成的骨架经过一次"空元件装载验证"，装载链就打通了。

# 开发包就位后的三步验证
# 一 生成骨架（脚手架命令生成源文件与构建描述）
# 二 编译产出动态库
# 三 装载验证：注册成功后目录命令能查到
GST_PLUGIN_PATH=. gst-inspect-1.0 my_watermark
# 查到元件即装载链打通 后续全部迭代都在这条链上
​

基类选型：站在哪副脚手架上

选型决策只问一个问题：你的元件在数据流里是什么形态。

基类选型决策图

水印元件的选型推演：形态是一进一出的逐帧加工；候选在基础变换类与视频滤镜类之间。后者继承前者，额外提供帧元信息结构——宽高、排布、行跨度直接可用，不必每帧解析能力集。水印要按帧宽定位右下角，这个便利直接命中，选视频滤镜基类。代价是强绑视频域——将来要做"任意数据"的通用变换时再回基础变换类。

⚠️ 常见坑：跳过基类直接从元件原始类继承。原始类要求你亲手处理状态、协商、冲刷、内存全套事务，代码量翻数倍且易错。除非写的是极特殊的调度型元件，否则永远先找基类。

💡 关键直觉：选基类像选脚手架——比你需要的低一层最省力。视频滤镜类对水印刚好够用；选聚合类就是高射炮打蚊子，多背一堆用不上的约定。

类型系统：元件的身份证办理

选好基类后过一遍"办证流程"。框架的类型系统要求每个元件类型登记三样：类型名（全系统唯一的字符串，目录命令查的就是它）、父类型（你的基类）、实例与类结构体。脚手架生成的样板代码把这些办妥，值得读懂的是其中两处：类初始化函数里设衬垫模板与属性（下一节展开）；实例初始化函数里建每个实例的私有状态。办完证，工厂就能按名创建你的元件，目录命令里也就有了它的条目。

// 脚手架生成的类型登记骨架（节选 注释为讲解）
G_DEFINE_TYPE(GstMyWatermark, gst_my_watermark,
              GST_TYPE_VIDEO_FILTER);
// 类初始化 每个类型执行一次
static void gst_my_watermark_class_init(gpointer klass, gpointer data) {
    // 此处登记 衬垫模板 属性表 信号表 处理函数指针
}
// 实例初始化 每个实例执行一次
static void gst_my_watermark_init(GstMyWatermark *self,
                                  GstMyWatermarkClass *klass) {
    // 此处初始化 实例私有状态 互斥锁 缓存
}
​

许可与分发的三个注意

自写元件要给别人用，许可与分发比代码本身更容易踩雷。注意一：动态链接的边界。你的插件以动态库形式装载，与框架核心的链接关系要在许可层面确认清楚——商业闭源插件按官方指引走动态链接路线，别把头文件的许可条款误读成传染义务。注意二：依赖库的传染性。水印元件若用了第三方字体库，字体库的许可随你的插件一起分发——逐个列出依赖清单过一遍，比事后被合规部门打回强。注意三：符号可见性。动态库默认导出全部符号可能与宿主环境的其他库冲突，构建脚本里把导出符号收敛到插件初始化函数，这是分发级插件的标配做法。

第一个迭代的工作量预算

给新手的实用建议：把水印元件的第一个迭代定为"只支持一种排布、只画一个格式、不加任何属性"。这个小到半天能完成的版本走通全链路——类型登记、装载验证、命令行接入、真机渲染——之后每个迭代只加一个维度（第二种排布、位置属性、字体选项）。先闭环再加宽的节奏，能让每一步都有可验证的产物，也避免"写了三周还没跑起来一次"的挫败感。

插件命名与版本兼容矩阵

元件类型的命名要有纪律：前缀防撞——类型名以项目或组织缩写打头（本册示例用"我的"前缀即此意），避免与官方元件撞名，撞名的插件装载时后到者会被拒绝，症状是"装了却查不到"；实例名带语义——程序里创建实例时按用途命名，日志可读性立升。命名事故的排查成本极高（症状像是环境问题），预防成本只是起名时多想十秒。

版本兼容矩阵：插件要与框架次段版本声明兼容范围，发版前在矩阵里的每个稳定线各跑一轮装载验证与基础回归。矩阵写进发布说明，使用者一眼能判断"我的框架线能不能用这个版本的插件"——8.3 节清单里的"版本有档"，插件作者侧的兑现就是这张矩阵。

本节要点回顾

• 自制判据：靠胶水逐帧干预就自制，属性组合能表达就组合；
• 脚手架先行：骨架生成加装载验证，一条链打通再迭代；
• 选型先问形态：一进一出、只出不进、多进一出、一进多出各归其位；
• 低一层最省力：够用的最低基类，不多背约定；
• 办证三件套：类型名、父类型、两个初始化函数，读懂样板即可。

模子立起来了，下一节给元件开出正式的接口规格——衬垫模板与协商对接，让自制件能顺利接进任何管线。