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.
This commit is contained in:
Mathieu Duponchelle 2020-06-05 23:28:38 +02:00
parent 0c1ce6e8c4
commit 169abc86e9
3 changed files with 60 additions and 3 deletions

View file

@ -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\"",

View file

@ -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

View file

@ -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);