padtemplate: expose getters and setters "documentation caps"

This can be used in elements where the caps of pad templates
are dynamically generated and dependent on the environment.

An example is x265enc.

docs/gst-hotdoc-plugins-scanner.c

@@ -709,15 +709,21 @@ _add_element_pad_templates (GString * json, GString * other_types,
 
   pads = gst_element_factory_get_static_pad_templates (factory);
   while (pads) {
+    GstCaps *documentation_caps;
     gchar *name, *caps;
     GType pad_type;
     GstPadTemplate *tmpl;
     padtemplate = (GstStaticPadTemplate *) (pads->data);
     pads = g_list_next (pads);
 
+    tmpl = gst_element_class_get_pad_template (GST_ELEMENT_GET_CLASS (element),
+        padtemplate->name_template);
+
     name = g_regex_replace (re, padtemplate->name_template,
         -1, 0, "%%", 0, NULL);;
-    caps = _build_caps (gst_static_caps_get (&padtemplate->static_caps));
+    documentation_caps = gst_pad_template_get_documentation_caps (tmpl);
+    caps = _build_caps (documentation_caps);
+    gst_caps_replace (&documentation_caps, NULL);
     g_string_append_printf (json, "%s"
         "\"%s\": {"
         "\"caps\": \"%s\","
@@ -735,8 +741,6 @@ _add_element_pad_templates (GString * json, GString * other_types,
     opened = TRUE;
     g_free (name);
 
-    tmpl = gst_element_class_get_pad_template (GST_ELEMENT_GET_CLASS (element),
-        padtemplate->name_template);
     pad_type = GST_PAD_TEMPLATE_GTYPE (tmpl);
     if (pad_type != G_TYPE_NONE && pad_type != GST_TYPE_PAD) {
       g_string_append_printf (json, ", \"type\": \"%s\"",

gst/gstpadtemplate.c

@@ -230,6 +230,8 @@ gst_pad_template_dispose (GObject * object)
     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
   }
 
+  gst_pad_template_set_documentation_caps (templ, NULL);
+
   G_OBJECT_CLASS (parent_class)->dispose (object);
 }
 
@@ -478,6 +480,50 @@ gst_pad_template_get_caps (GstPadTemplate * templ)
   return (caps ? gst_caps_ref (caps) : NULL);
 }
 
+/**
+ * gst_pad_template_set_documentation_caps:
+ * @templ: the pad template to set documented capabilities on
+ * @caps: the documented capabilities
+ *
+ * Certain elements will dynamically construct the caps of their
+ * pad templates. In order not to let environment-specific information
+ * into the documentation, element authors should use this method to
+ * expose "stable" caps to the reader.
+ *
+ * Since: 1.18
+ */
+void
+gst_pad_template_set_documentation_caps (GstPadTemplate * templ, GstCaps * caps)
+{
+  g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
+  g_return_if_fail (GST_IS_CAPS (caps));
+
+  gst_caps_replace (&(((GstPadTemplate *) (templ))->ABI.abi.documentation_caps),
+      caps);
+}
+
+/**
+ * gst_pad_template_get_documentation_caps:
+ * @templ: the pad template to get documented capabilities on
+ *
+ * See gst_pad_template_set_documentation_caps().
+ *
+ * Returns: The caps to document. For convenience, this will return
+ *   gst_pad_template_get_caps() when no documentation caps were set.
+ * Since: 1.18
+ */
+GstCaps *
+gst_pad_template_get_documentation_caps (GstPadTemplate * templ)
+{
+  g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
+
+  if (((GstPadTemplate *) (templ))->ABI.abi.documentation_caps)
+    return gst_caps_ref (((GstPadTemplate *) (templ))->ABI.abi.
+        documentation_caps);
+  else
+    return gst_pad_template_get_caps (templ);
+}
+
 /**
  * gst_pad_template_pad_created:
  * @templ: a #GstPadTemplate that has been created

gst/gstpadtemplate.h

@@ -141,6 +141,7 @@ struct _GstPadTemplate {
     gpointer _gst_reserved[GST_PADDING];
     struct {
       GType gtype;
+      GstCaps *documentation_caps;
     } abi;
   } ABI;
 };
@@ -228,6 +229,12 @@ GstCaps*		gst_static_pad_template_get_caps	(GstStaticPadTemplate *templ);
 GST_API
 GstCaps*		gst_pad_template_get_caps		(GstPadTemplate *templ);
 
+GST_API
+void        gst_pad_template_set_documentation_caps (GstPadTemplate *templ, GstCaps *caps);
+
+GST_API
+GstCaps*    gst_pad_template_get_documentation_caps (GstPadTemplate *templ);
+
 GST_API
 void                    gst_pad_template_pad_created            (GstPadTemplate * templ, GstPad * pad);