GStreamer基础教程之媒体格式和pad功能

目标：

Pad Capabilities 是 GStreamer 的一个基本元素，尽管大多数时候它们是不可见的，因为框架会自动处理它们。这个有点理论的教程显示：

• 什么是Pad Capabilities
• 如何检索它们
• 何时取回它们
• 为什么你需要了解它们

介绍：

pad

如前所述，Pads 允许信息进入和离开元素。Pad的Capabilities（或Caps，简称Caps），然后，指定什么样的信息可以通过 Pad 传播。例如，“分辨率为 320x200 像素和每秒 30 帧的 RGB 视频”，或“每个样本音频 16 位，每秒 44100 个样本的 5.1 通道”，甚至是 mp3 或 h264 等压缩格式。

Pads 可以支持多种 Capabilities（例如，视频接收器可以支持不同类型的 RGB 或 YUV 格式的视频）并且可以将能力指定为范围（例如，音频接收器可以支持每秒 1 到 48000 个样本的采样率） . 但是，从 Pad 到 Pad 传输的实际信息必须只有一种明确指定的类型。通过一个称为协商的过程，两个链接的 Pad 就一个通用类型达成一致，因此 Pad 的 Capabilities 变得固定 （它们只有一种类型并且不包含范围）。下面的示例代码演练应该使这一切变得清晰。

为了将两个元素链接在一起，它们必须共享一个共同的能力子集（否则它们不可能相互理解）。这是 Capabilities 的主要目标。

作为应用程序开发人员，您通常会通过将元素链接在一起来构建管道（如果您使用诸如 之类的全能元素，则在较小程度上playbin）。在这种情况下，您需要知道元素的Pad Caps（众所周知的），或者至少知道当 GStreamer 拒绝链接两个元素并出现协商错误时它们是什么。

Pad templates

Pads 是从Pad Templates创建的，它表示一个 Pad 可能拥有的所有可能的功能。模板可用于创建多个相似的 Pad，并且还允许提前拒绝元素之间的连接：如果它们的 Pad 模板的 Capabilities 没有公共子集（它们的交集为空），则无需进一步协商。

Pad Templates 可视为协商过程的第一步。随着过程的发展，实际的 Pads 被实例化，它们的 Capabilities 被改进，直到它们被修复（或协商失败）。

请记住，某些元素会查询底层硬件以获取支持的格式并相应地提供它们的 Pad Caps（它们通常在进入 READY 状态或更高状态时执行此操作）。因此，显示的上限可能因平台而异，甚至从一个执行到下一个执行（即使这种情况很少见）。

示例

SINK template: 'sink'
  Availability: Always
  Capabilities:
    audio/x-raw
               format: S16LE
                 rate: [ 1, 2147483647 ]
             channels: [ 1, 2 ]
    audio/x-raw
               format: U8
                 rate: [ 1, 2147483647 ]
             channels: [ 1, 2 ]

这个pad是一个sink，它总是在元件上可用（我们现在不讨论可用性）。它支持两种媒体，都是整数格式 ( audio/x-raw) 的原始音频：有符号 16 位小端和无符号 8 位。方括号表示一个范围：例如，通道数从 1 到 2 不等。

SRC template: 'src'
  Availability: Always
  Capabilities:
    video/x-raw
                width: [ 1, 2147483647 ]
               height: [ 1, 2147483647 ]
            framerate: [ 0/1, 2147483647/1 ]
               format: { I420, NV12, NV21, YV12, YUY2, Y42B, Y444, YUV9, YVU9, Y41B, Y800, Y8, GREY, Y16 , UYVY, YVYU, IYU1, v308, AYUV, A420 }

video/x-raw表示此源垫输出原始视频。它支持广泛的维度和帧率，以及一组 YUV 格式（花括号表示列表）。所有这些格式表示图像平面的不同打包和子采样。

功能示例

#include <gst/gst.h>

/* Functions below print the Capabilities in a human-friendly format */
static gboolean print_field (GQuark field, const GValue * value, gpointer pfx) {
  gchar *str = gst_value_serialize (value);  //transform the given value into a string  representation

  g_print ("%s  %15s: %s\n", (gchar *) pfx, g_quark_to_string (field), str);
  g_free (str);
  return TRUE;
}

static void print_caps (const GstCaps * caps, const gchar * pfx) {
  guint i;

  g_return_if_fail (caps != NULL);

  if (gst_caps_is_any (caps)) {             //检测是否caps代表所有的媒体格式
    g_print ("%sANY\n", pfx);
    return;
  }
  if (gst_caps_is_empty (caps)) {           //检测是否caps代表没有媒体格式
    g_print ("%sEMPTY\n", pfx);
    return;
  }

  for (i = 0; i < gst_caps_get_size (caps); i++) {          //caps包含的结构的数量
    GstStructure *structure = gst_caps_get_structure (caps, i);

    g_print ("%s%s\n", pfx, gst_structure_get_name (structure));
    gst_structure_foreach (structure, print_field, (gpointer) pfx);     //为GstStructure的每个字段都执行print_field函数
  }
}

/* Prints information about a Pad Template, including its Capabilities */
static void print_pad_templates_information (GstElementFactory * factory) {
  const GList *pads;
  GstStaticPadTemplate *padtemplate;

  g_print ("Pad Templates for %s:\n", gst_element_factory_get_longname (factory));
  if (!gst_element_factory_get_num_pad_templates (factory)) {
    g_print ("  none\n");
    return;
  }

  pads = gst_element_factory_get_static_pad_templates (factory);
  while (pads) {
    padtemplate = reinterpret_cast<GstStaticPadTemplate*>(pads->data);

    if(padtemplate == nullptr)
    {
        g_print("pads->data turn to GstStaticPadTemplate pointer failed");
        break;
    }

    pads = g_list_next (pads);

    if (padtemplate->direction == GST_PAD_SRC)
      g_print ("  SRC template: '%s'\n", padtemplate->name_template);
    else if (padtemplate->direction == GST_PAD_SINK)
      g_print ("  SINK template: '%s'\n", padtemplate->name_template);
    else
      g_print ("  UNKNOWN!!! template: '%s'\n", padtemplate->name_template);

    if (padtemplate->presence == GST_PAD_ALWAYS)
      g_print ("    Availability: Always\n");
    else if (padtemplate->presence == GST_PAD_SOMETIMES)
      g_print ("    Availability: Sometimes\n");
    else if (padtemplate->presence == GST_PAD_REQUEST)
      g_print ("    Availability: On request\n");
    else
      g_print ("    Availability: UNKNOWN!!!\n");

    if (padtemplate->static_caps.string) {
      GstCaps *caps;
      g_print ("    Capabilities:\n");
      caps = gst_static_caps_get (&padtemplate->static_caps);
      print_caps (caps, "      ");
      gst_caps_unref (caps);

    }

    g_print ("\n");
  }
}

static void printPadCapbilities(GstElement* element, gchar* pad_name)
{
    GstPad* pad = gst_element_get_static_pad(element, pad_name);
    if(!pad)
    {
        g_printerr("Could not retrieve pad '%s'\n", pad_name);
        return;
    }

    GstCaps* caps = gst_pad_get_current_caps(pad);
    if(!caps)
    {
        caps = gst_pad_query_caps(pad, nullptr);
    }
    g_print("Caps for the %s pad:\n", pad_name);
    print_caps(caps, "    ");
    gst_caps_unref(caps);
    gst_object_unref(pad);
}

/* Shows the CURRENT capabilities of the requested pad in the given element */
static void print_pad_capabilities (GstElement *element, gchar *pad_name) {
  GstPad *pad = NULL;
  GstCaps *caps = NULL;

  /* Retrieve pad */
  pad = gst_element_get_static_pad (element, pad_name);
  if (!pad) {
    g_printerr ("Could not retrieve pad '%s'\n", pad_name);
    return;
  }

  /* Retrieve negotiated caps (or acceptable caps if negotiation is not finished yet) */
  caps = gst_pad_get_current_caps (pad);
  if (!caps)
    caps = gst_pad_query_caps (pad, NULL);

  /* Print and free */
  g_print ("Caps for the %s pad:\n", pad_name);
  print_caps (caps, "      ");
  gst_caps_unref (caps);
  gst_object_unref (pad);
}

int main(int argc, char *argv[]) {
  GstElement *pipeline, *source, *sink;
  GstElementFactory *source_factory, *sink_factory;
  GstBus *bus;
  GstMessage *msg;
  GstStateChangeReturn ret;
  gboolean terminate = FALSE;

  /* Initialize GStreamer */
  gst_init (&argc, &argv);

  /* Create the element factories */
  source_factory = gst_element_factory_find ("audiotestsrc");
  sink_factory = gst_element_factory_find ("autoaudiosink");
  if (!source_factory || !sink_factory) {
    g_printerr ("Not all element factories could be created.\n");
    return -1;
  }

  /* Print information about the pad templates of these factories */
  print_pad_templates_information (source_factory);
  print_pad_templates_information (sink_factory);

  /* Ask the factories to instantiate actual elements */
  source = gst_element_factory_create (source_factory, "source");
  sink = gst_element_factory_create (sink_factory, "sink");

  /* Create the empty pipeline */
  pipeline = gst_pipeline_new ("test-pipeline");

  if (!pipeline || !source || !sink) {
    g_printerr ("Not all elements could be created.\n");
    return -1;
  }

  /* Build the pipeline */
  gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);
  if (gst_element_link (source, sink) != TRUE) {
    g_printerr ("Elements could not be linked.\n");
    gst_object_unref (pipeline);
    return -1;
  }

  /* Print initial negotiated caps (in NULL state) */
  g_print ("In NULL state:\n");
  print_pad_capabilities (sink, "sink");

  /* Start playing */
  ret = gst_element_set_state (pipeline, GST_STATE_PLAYING);
  if (ret == GST_STATE_CHANGE_FAILURE) {
    g_printerr ("Unable to set the pipeline to the playing state (check the bus for error messages).\n");
  }

  /* Wait until error, EOS or State Change */
  bus = gst_element_get_bus (pipeline);
  do {
    msg = gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE, (GstMessageType)(GST_MESSAGE_ERROR | GST_MESSAGE_EOS |
        GST_MESSAGE_STATE_CHANGED));

    /* Parse message */
    if (msg != NULL) {
      GError *err;
      gchar *debug_info;

      switch (GST_MESSAGE_TYPE (msg)) {
        case GST_MESSAGE_ERROR:
          gst_message_parse_error (msg, &err, &debug_info);
          g_printerr ("Error received from element %s: %s\n", GST_OBJECT_NAME (msg->src), err->message);
          g_printerr ("Debugging information: %s\n", debug_info ? debug_info : "none");
          g_clear_error (&err);
          g_free (debug_info);
          terminate = TRUE;
          break;
        case GST_MESSAGE_EOS:
          g_print ("End-Of-Stream reached.\n");
          terminate = TRUE;
          break;
        case GST_MESSAGE_STATE_CHANGED:
          /* We are only interested in state-changed messages from the pipeline */
          if (GST_MESSAGE_SRC (msg) == GST_OBJECT (pipeline)) {
            GstState old_state, new_state, pending_state;
            gst_message_parse_state_changed (msg, &old_state, &new_state, &pending_state);
            g_print ("\nPipeline state changed from %s to %s:\n",
                gst_element_state_get_name (old_state), gst_element_state_get_name (new_state));
            /* Print the current capabilities of the sink element */
            print_pad_capabilities (sink, "sink");
          }
          break;
        default:
          /* We should not reach here because we only asked for ERRORs, EOS and STATE_CHANGED */
          g_printerr ("Unexpected message received.\n");
          break;
      }
      gst_message_unref (msg);
    }
  } while (!terminate);

  /* Free resources */
  gst_object_unref (bus);
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  gst_object_unref (source_factory);
  gst_object_unref (sink_factory);
  return 0;
}

执行结果：

在NULL状态时：

 在非NULL状态时：

 NULL状态和非NULL状态下的sink pad结构不同，是因为：在非NULL状态下，元素会查询底层硬件以获取支持的格式并相应地提供它们的 Pad Caps（pad当前协商的caps）。

结论

• 如果两个元素可以链接在一起，那么事先知道 Pad Caps 很重要。

• 根据管道的状态，它们具有不同的含义（最初它们表示所有可能的 Capabilities，后来它们表示 Pad 当前协商的 Caps）。

• 可以使用gst-inspect-1.0描述的工具找到 Pad Caps 。