6.4 GstMeta：把推理结果贴在帧上

6.4 GstMeta：把推理结果贴在帧上

本节摘要：元数据是挂在缓冲上的附带信息：注册一个类型、实现变换与拷贝语义、逐帧添加、下游按名取用。水印元件的时间戳、AI 支路的检测框、多机对拍的校准信息，都靠它在管线里随水流动而不占数据车道。本节讲透注册、附着、读取与变换语义四件事，是第六章收口，也是第七章推理集成的机制预备。

数据车道之外的第二层

设想两个未来需求。其一：水印元件想把自己的绘制耗时上报给监控支路。其二（第七章主线）：AI 推理元件输出检测框，下游要画框渲染。两条路的错误走法是把结果塞进像素或改用旁路数据库按帧号对齐——前者污染数据，后者引入时序对齐难题。正确机制是元数据：缓冲对象上允许挂多个命名的小结构，随缓冲同生同灭、同序流动。数据车道保持纯净，附带信息搭便车。

元数据随缓冲流动示意

注册：给元数据办户口

元数据类型要先注册：声明结构体、登记类型与变换语义。语义函数是注册的灵魂——它回答"缓冲被变换时元数据怎么办"。

// 一 元数据结构体 业务字段自由定义
typedef struct {
    GstMeta       meta;           // 必须打头 框架锚点
    GstClockTime  draw_cost;      // 水印绘制耗时
} MyPerfMeta;

// 二 变换语义 缓冲被变换时如何处置元数据
static gboolean my_perf_transform(GstBuffer *dst, GstMeta *meta,
        GstBuffer *src, GQuark type, gpointer data) {
    // 耗时统计遇变换 原样复制 语义仍成立
    if (type == GST_META_TRANSFORM_COPY) {
        MyPerfMeta *d = gst_buffer_add_my_perf_meta(dst);
        if (d) d->draw_cost = ((MyPerfMeta *)meta)->draw_cost;
    }
    return TRUE;   // 返回假表示丢弃该元数据
}

// 三 注册 API 类型由注册中心分配句柄
GType my_perf_meta_api_get_type(void) {
    static GType t = 0;
    if (!t)
        t = g_boxed_type_register_static("MyPerfMetaAPI",
              (GBoxedCopyFunc)NULL, (GBoxedFreeFunc)NULL);
    return t;
}
​

添加与读取：两行核心调用

注册之后，添加与读取各一个入口。水印元件在处理函数里记录耗时、加工完成时挂上；监控支路在探针里按接口取用。

// 挂：加工完成处 添加并填值
MyPerfMeta *m = gst_buffer_add_my_perf_meta(outbuf);
if (m) m->draw_cost = elapsed;

// 取：下游探针或处理函数里 按接口查找
MyPerfMeta *got = gst_buffer_get_my_perf_meta(buffer);
if (got) g_print("水印耗时 %ld 纳秒\n", got->draw_cost);
​

读取按接口而非按内容对齐——缓冲上没有该类型时返回空指针，调用方判空即走。判空是元数据读取的日常：上游可能被替换、支路可能被裁剪，把"没有元数据"当正常分支处理，元件才具备可组合性。

语义函数的三种典型策略

变换语义决定元数据的可信度，三种典型策略对应三类信息。原样复制：统计类信息（耗时、设备号），复制即可。重算跟随：几何类信息（检测框、区域标注），缓冲被缩放裁剪时坐标必须按同样几何重算，否则下游画框全偏——这是语义函数最重的职责，也是元数据机制最常见的缺陷来源。主动丢弃：强绑上游上下文的信息（上游私有句柄），变换后无意义，返回假丢弃，宁可没有不可错。

⚠️ 常见坑：注册了元数据却不实现几何重算。检测框元数据穿过的第一个缩放元件就把坐标系打乱，下游画框偏移，排查者第一时间怀疑推理模型，极少怀疑元数据语义——这类缺陷的潜伏期以周计。

💡 关键直觉：元数据是"随货单据"，语义函数是"单据变更规则"。单据与货物失同步，比没有单据更糟。

第六章收工检验

开模四站走完：选基类、立模板、写运转、贴标签。自检两题：流返回值有哪几类、各自怎么传播；检测框元数据穿过缩放元件需要什么语义。答得上，第七章的 AI 支路可以直接开工——推理元件的输出正是靠元数据送达渲染端。

元数据设计的三条军规

军规一：字段自描述。元数据结构里带上坐标系与单位信息（框坐标是像素还是归一化值、耗时是纳秒还是微秒），下游不必猜约定——猜约定的对接就是下一个bug。军规二：语义函数宁丢弃不错乱。拿不准怎么重算的场景，返回假主动丢弃，让下游走"无元数据"分支；带错值的元数据比没有元数据危害大得多，6.4 节开头的潜伏期故事就是这么来的。军规三：命名预留对齐空间。字段名向生态约定靠拢（检测类元数据的字段命名参考官方同类插件），将来标准化落地时白拿互操作性——9.2 节的趋势判断在这里落到了字段命名这么具体的地方。

元数据与消费端的配合

元数据的完整故事要连消费端一起讲。渲染端探针里读元数据画框（7.3 节的主线场景）；统计端则常在应用汇或探针处做聚合——每秒从帧元数据里抽取耗时字段，聚合成百分位上报。两种消费有一个共同前提：读取都要判空（上游可能被替换），聚合还要设样本窗口（只统计最近一段时间，防陈旧值拉偏基线）。

// 探针里的轻量聚合：读耗时字段 计入滑动窗口
static GstPadProbeReturn stats_probe(GstPad *pad,
        GstPadProbeInfo *info, gpointer user) {
    StatsCtx *ctx = user;
    GstBuffer *buf = GST_PAD_PROBE_INFO_BUFFER(info);
    MyPerfMeta *m = gst_buffer_get_my_perf_meta(buf);
    if (m) stats_window_add(ctx, m->draw_cost);   // 有则记 无则跳过
    return GST_PAD_PROBE_OK;                      // 只读不拦
}
​

这个探针骨架展示了元数据消费的全部要点：按接口取、判空、轻处理、不拦流。把探针挂在与业务无关的观察点上，统计支路就与业务支路彻底解耦——8.3 节的指标基线，原料正来自这里。

本节要点回顾

• 元数据是第二车道：附带信息随缓冲流动，不污染数据、不搞旁路对齐；
• 注册三件套：结构体锚点打头、语义函数定生死、类型句柄统一分配；
• 读取必判空：没有元数据是正常分支；
• 语义三策略：复制、重算、丢弃，几何类必须重算；
• 单据失同步比没有更糟：元数据的可信度全在语义函数。

模具齐备，主线项目上高压。第七章三档工况——硬件编解码零拷贝、网络推流、AI 推理——逐台压测。