[GStreamer] GstPad

参考:

https://gstreamer.freedesktop.org/documentation/gstreamer/gstpad.html?gi-language=c#GstPadhttps://gstreamer.freedesktop.org/documentation/gstreamer/gstpad.html?gi-language=c#GstPad

概述：

• 我们可以使用 padtemplate 创建新的pad，也使用 gst_pad_new 直接无模板创建新的 pad 。
• 使用gst_pad_get_parent来获取pad归属的哪个GstElement，pad 需要依附在 element 内，因此其parent一般情况下都是一个GstElement。
• 可以使用gst_pad_get_peer获取当前pad 和哪些 pad 建立了 link 关系。
• 发送event的函数为 gst_pad_send_event 和 gst_pad_push_event。有些event可以指定为sticky。
• pad是element推拉数据的介质，可以通过gst_pad_push和gst_pad_pull_range进行GstBuffer的推拉。一般情况下编写代码都是以plugin为单位，而pad往往作为element的成员变量，因此gst_pad_push和gst_pad_pull_range的入参往往是 element->srcpad 或者 element->sinkpad 。
• 可以使用gst_pad_add_probe为pad注册一下回调函数，这些回调函数在不同数据（dataflow、events、queries）到达pad时会被触发，有的还会阻塞运行。
• Pad have an offset that can be retrieved with gst_pad_get_offset. This offset will be applied to the running_time of all data passing over the pad. gst_pad_set_offset can be used to change the offset.
• Convenience functions exist to start, pause and stop the task on a pad with gst_pad_start_task, gst_pad_pause_task and gst_pad_stop_task respectively.

回调函数：

表格字段描述：

• 1）函数类型：函数类型定义。
• 2）设置函数：GStreamer留给外界的函数注册接口。
• 3）函数名模板：我们要自行实现的函数的命名规则，这个函数的类型必须满足1），通过2）向 pad 注册自己。
• 4）描述：一些限制；什么情况下 3) 被调用 ；如果不使用 2是否有内置默认动作；建议完成什么功能；等等。

函数类型	设置函数	推荐的函数命名规则	描述
GstPadActivateFunction	gst_pad_set_activatemode_function gst_pad_set_activatemode_function_full	xxx_active()	限制：无 被调时机：pad 从 Ready转换到Paused状态时，或者主动调用gst_pad_activate_mode()强制active pad时。 说明：如果不通过 set 函数为 pad 指定 xxx_active()，则GStreamer 的内部实现是把此pad 的 pad mode设置为PUSH MODE。
GstPadActivateModeFunction	gst_pad_set_activatemode_function gst_pad_set_activatemode_function_full	xxx_active_mode()
GstPadLinkFunction	gst_pad_set_link_function gst_pad_set_link_function_full	xxx_link()	限制：无 被调时机：当新的link添加到当前pad时。
GstPadUnlinkFunction	gst_pad_set_unlink_function gst_pad_set_unlink_function_full	xxx_unlink()	限制：无 被调时机：当有link从当前pad上移除时。
GstPadChainFunction	gst_pad_set_chain_function gst_pad_set_chain_function_full	xxx_chain()	限制：仅限sink pad。 被调时机：当有新buffer到达此pad时。 说明：使用完buffer需要unref；当处理buffer出错时应该post一个message到bus上，并返回错误。
GstPadChainListFunction	gst_pad_set_chain_list_function gst_pad_set_chain_list_function_full	xxx_chain_list()	限制：仅限sink pad。 被调时机：当有新buffer list到达此pad时。 说明：使用完buffer list需要unref；当处理buffer list出错时应该post一个message到bus上，并返回错误。
GstPadGetRangeFunction	gst_pad_set_getrange_function gst_pad_set_getrange_function_full	xxx_getrange()	限制：仅限src pad；仅限PULL MODE；pad必须已经actived。 被调时机：当peer element 调用 gst_pad_get_range 并以当前pad 为入参时。 说明：实现时需要处理好失败场景，比如请求的offset不正确时要返回错误值给peer element。
GstPadEventFunction	gst_pad_set_event_function gst_pad_set_event_function_full	xxx_event()	限制：无 被调时机：下级element 回传 GstEvent，或者上级element 下发GstEvent。 说明：使用完event需要unref。
GstPadEventFullFunction	gst_pad_set_event_full_function gst_pad_set_event_full_function_full	xxx_event_full()	1.8版本后引入，是GstPadEventFunction  的升级版
GstPadQueryFunction	gst_pad_set_query_function gst_pad_set_query_function_full	xxx_query()	限制：无 被调时机：当前pad收到一个GstQuery时。
GstPadIterIntLinkFunction	gst_pad_set_iterate_internal_links_function gst_pad_set_iterate_internal_links_function_full	xxx_iterate_internal_links()	限制：无 被调时机：外部使用gst_pad_iterate_internal_links函数并以本pad作为入参时。 说明：caller使用此函数后需要调用gst_iterator_free()。
GstPadForwardFunction	gst_pad_forward	xxx_forward()	限制：无 被调时机：gst_pad_forwward需要主动调用，主动调用时会同步触发xxx_forward到所有目标pad上。 说明：这其实是一个同步调用，或者说是主动调用，而不是注册一个回调等待某个时刻被触发。
GstPadStickyEventsForeachFunction	gst_pad_sticky_events_foreach	xxx_sticky_events_foreach()	限制：无 被调时机：当前pad收到任何GstEvent，都会触发此函数。 说明：这相当Event处理函数的前置处理函数。
GstPadProbeCallback	gst_pad_add_probe	xxx_probe_yyy()	限制：无 被调时机：pad发生状态转变时。 说明：gst_pad_add_probe在设置callback的时候是需要指定一个等级的，所有注册的callback会被根据具体的状态转变是否匹配而被选择是否被调用，同时这些callback基于等级还会按照一定的优先顺序被调用。

部分函数释义：

---

GstFlowReturn
gst_pad_chain (GstPad * pad,
               GstBuffer * buffer)

把一个GstBuffer对象和pad串起来，调用这个函数就相当于调用pad的xxx_chain函数，并把GstBuffer作为入参。因此在push mode下，上游element会反复调用这个函数来触发下级element 的 xxx_chain，这也正是 xxx_chain 的触发机理。

---

gboolean
gst_pad_forward (GstPad * pad,
                 GstPadForwardFunction forward,
                 gpointer user_data)

立刻把入餐指定的函数作用于当前pad后挂的所有内部pad上，这是一个同步过程，因此需要考虑阻塞问题和执行效率。

---

gpointer
gst_pad_get_element_private (GstPad * pad)

获取pad的private数据，private数据的定义一般都在 c 文件中，因此无法访问(除非include c文件)，这个函数提供了一个访问途径，但是返回的是一个gpointer，因此需要编码人确切知道结构体定义才可使用。

---

gint64
gst_pad_get_offset (GstPad * pad)

每个pad一个时刻只能持有一个GstBuffer，此函数返回当前GstBuffer的offset值。offset代表什么请参阅GstBuffer。

---

GstFlowReturn
gst_pad_get_range (GstPad * pad,
                   guint64 offset,
                   guint size,
                   GstBuffer ** buffer)

调用目标 pad 的 xxx_getrange 函数 ，如果 目标 pad 没有设置 xxx_getrange 函数，则此函数返回 GST_FLOW_NOT_SUPPORTED。这个函数用来访问当前绑定在目标 pad 上的GstBuffer。

---

GstTaskState
gst_pad_get_task_state (GstPad * pad)

每个 pad 都可以绑定一个 GstTask。

---

GstIterator *
gst_pad_iterate_internal_links (GstPad * pad)

获取某个 pad 上挂的所有内部 pad 的迭代器。如果没有为pad指定 xxx_iterate_internal_links 函数，则此函数返回 NULL。

---

GstIterator *
gst_pad_iterate_internal_links_default (GstPad * pad,
                                        GstObject * parent)

如果没有为pad指定 xxx_iterate_internal_links 函数，可以调用此函数来触发默认处理流程以返回一个逆序存储的迭代器。一般情况下使用这个函数而不是gst_pad_iterate_internal_links，因为gst_pad_iterate_internal_links在没指定 xxx_iterate_internal_links 时会返回NULL。

        ps：gst_pad_iterate_internal_links 是否可以融合一下 gst_pad_iterate_internal_links_default 。

---

gboolean
gst_pad_pause_task (GstPad * pad)

Pause the task of pad. This function will also wait until the function executed by the task is finished if this function is not called from the task function.

---

GstFlowReturn
gst_pad_pull_range (GstPad * pad,
                    guint64 offset,
                    guint size,
                    GstBuffer ** buffer)

从peer pad上拉取buffer或者填充入参指定的buffer，如果pad注册了 block 信号，此函数会触发这个信号。

pad 的 block：

每个 pad 一个时刻只能和一个 GstBuffer chain 在一起，GstBuffer的访问由 pad 全权控制，因此会涉及到一些 race condition，而block 正是对应与 race condition 的处理，比如当前已经有一个pad 在和当前pad 做数据交互，那么element内部就无法处理 chain 到pad 上的 GstBuffer，这个时候就说 pad 是 block 的，其实内部就是 GstBuffer 被锁住了。

---

GstFlowReturn
gst_pad_push (GstPad * pad,
              GstBuffer * buffer)

给peer pad 推送一个buffer，此函数会优先触发通过 probe 注册的 block 回调，接着会调用 peer pad 的 gst_pad_chain 函数。而gst_pad_chain又会触发 xxx_chain函数，至此整个函数调用链已经打通。

---

gst_pad_send_event 

TO BE FINISHED