From 4f89b260956c0f1a8498a181e8de6027723f7168 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Wed, 10 May 2006 15:00:32 +0000 Subject: [PATCH] docs/manual/basics-pads.xml: Expand a bit on caps and filtered links and update examples that were still using the no... Original commit message from CVS: * docs/manual/basics-pads.xml: Expand a bit on caps and filtered links and update examples that were still using the no longer existing gst_pad_link_filtered() (#338206). --- ChangeLog | 7 ++ docs/manual/basics-pads.xml | 156 +++++++++++++++++++++++++++++------- 2 files changed, 133 insertions(+), 30 deletions(-) diff --git a/ChangeLog b/ChangeLog index 383d365296..41f9fffbab 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2006-05-10 Tim-Philipp Müller + + * docs/manual/basics-pads.xml: + Expand a bit on caps and filtered links and update + examples that were still using the no longer existing + gst_pad_link_filtered() (#338206). + 2006-05-10 Wim Taymans * libs/gst/base/gstcollectpads.c: (gst_collect_pads_finalize), diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index 55e397e4b4..af45559c21 100644 --- a/docs/manual/basics-pads.xml +++ b/docs/manual/basics-pads.xml @@ -301,6 +301,13 @@ Pad Templates: the property contains a UTF-8 string. + + + A fraction value (GST_TYPE_FRACTION): + contains a fraction expressed by an integer numerator and + denominator. + + @@ -330,6 +337,14 @@ Pad Templates: lower and an upper boundary. + + + A fraction range value + (GST_TYPE_FRACTION_RANGE): the property + denotes a range of possible fraction values, with a + lower and an upper boundary. + + @@ -338,10 +353,16 @@ Pad Templates: property can take any value from a list of basic values given in this list. + + Example: caps that express that either + a sample rate of 44100 Hz and a sample rate of 48000 Hz + is supported would use a list of integer values, with + one value being 44100 and one value being 48000. + - An array value (GST_TYPE_FIXED_LIST): the + An array value (GST_TYPE_ARRAY): the property is an array of values. Each value in the array is a full value on its own, too. All values in the array should be of the same elementary type. This means that an array can @@ -349,6 +370,15 @@ Pad Templates: ranges together, and the same for floats or strings, but it can not contain both floats and ints at the same time. + + Example: for audio where there are more than two channels involved + the channel layout needs to be specified (for one and two channel + audio the channel layout is implicit unless stated otherwise in the + caps). So the channel layout would be an array of integer enum + values where each enum value represents a loudspeaker position. + Unlike a GST_TYPE_LIST, the values in an + array will be interpreted as a whole. + @@ -357,8 +387,8 @@ Pad Templates: What capabilities are used for - Capabilities describe the type of data that is streamed between - two pads, or that one pad (template) supports. This makes them + Capabilities (short: caps) describe the type of data that is streamed + between two pads, or that one pad (template) supports. This makes them very useful for various purposes: @@ -391,9 +421,15 @@ Pad Templates: possible media types that can stream between two pads to a specific subset of their supported stream types. An application can, for example, use filtered caps to set a - specific (non-fixed) video size that will stream between two - pads. You will see an example of filtered caps further on in - this manual, in . + specific (fixed or non-fixed) video size that should stream + between two pads. You will see an example of filtered caps + later in this manual, in . + You can do caps filtering by inserting a capsfilter element into + your pipeline and setting its caps property. Caps + filters are often placed after converter elements like audioconvert, + audioresample, ffmpegcolorspace or videoscale to force those + converters to convert data to a specific output format at a + certain point in a stream. @@ -402,11 +438,42 @@ Pad Templates: Using capabilities for metadata A pad can have a set (i.e. one or more) of capabilities attached - to it. You can get values of properties in a set of capabilities + to it. Capabilities (GstCaps) are represented + as an array of one or more GstStructures, and + each GstStructure is an array of fields where + each field consists of a field name string (e.g. "width") and a + typed value (e.g. G_TYPE_INT or + GST_TYPE_INT_RANGE). + + + Note that there is a distinct difference between the + possible capabilities of a pad (ie. usually what + you find as caps of pad templates as they are shown in gst-inspect), + the allowed caps of a pad (can be the same as + the pad's template caps or a subset of them, depending on the possible + caps of the peer pad) and lastly negotiated caps + (these describe the exact format of a stream or buffer and contain + exactly one structure and have no variable bits like ranges or lists, + ie. they are fixed caps). + + + You can get values of properties in a set of capabilities by querying individual properties of one structure. You can get a structure from a caps using - gst_caps_get_structure (): + gst_caps_get_structure () and the number of + structures in a GstCaps using + gst_caps_get_size (). + + Caps are called simple caps when they contain + only one structure, and fixed caps when they + contain only one structure and have no variable field types (like + ranges or lists of possible values). Two other special types of caps + are ANY caps and empty caps. + + + Here is an example of how to extract the width and height from + a set of fixed video caps: static void read_video_props (GstCaps *caps) @@ -414,7 +481,9 @@ read_video_props (GstCaps *caps) gint width, height; const GstStructure *str; - str = gst_caps_get_structure (caps); + g_return_if_fail (gst_caps_is_fixed (caps)); + + str = gst_caps_get_structure (caps, 0); if (!gst_structure_get_int (str, "width", &width) || !gst_structure_get_int (str, "height", &height)) { g_print ("No width/height available\n"); @@ -425,38 +494,58 @@ read_video_props (GstCaps *caps) width, height); } + Creating capabilities for filtering While capabilities are mainly used inside a plugin to describe the - media type of the pads, the application programmer also has to have - basic understanding of capabilities in order to interface with the - plugins, especially when using filtered caps. When you're using - filtered caps or fixation, you're limiting the allowed types of + media type of the pads, the application programmer often also has + to have basic understanding of capabilities in order to interface + with the plugins, especially when using filtered caps. When you're + using filtered caps or fixation, you're limiting the allowed types of media that can stream between two pads to a subset of their supported - media types. You do this by filtering using your own set of - capabilities. In order to do this, you need to create your own - GstCaps. The simplest way to do this is by - using the convenience function gst_caps_new_simple - (): + media types. You do this using a capsfilter + element in your pipeline. In order to do this, you also need to + create your own GstCaps. The easiest way to + do this is by using the convenience function + gst_caps_new_simple (): + -static void -link_pads_with_filter (GstPad *one, - GstPad *other) +static gboolean +link_elements_with_filter (GstElement *element1, GstElement *element2) { + gboolean link_ok; GstCaps *caps; caps = gst_caps_new_simple ("video/x-raw-yuv", - "width", G_TYPE_INT, 384, - "height", G_TYPE_INT, 288, - "framerate", GST_TYPE_FRACTION, 25, 1, - NULL); - gst_pad_link_filtered (one, other, caps); + "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'), + "width", G_TYPE_INT, 384, + "height", G_TYPE_INT, 288, + "framerate", GST_TYPE_FRACTION, 25, 1, + NULL); + + link_ok = gst_element_link_filtered (element1, element2, caps); + gst_caps_unref (caps); + + if (!link_ok) { + g_warning ("Failed to link element1 and element2!"); + } + + return link_ok; } + This will force the data flow between those two elements to a + a certain video format, width, height and framerate (or the linking + will fail if that cannot be achieved in the context of the elments + involved). Keep in mind that when you use + gst_element_link_filtered () it will automatically create + a capsfilter element for you and insert it into + your bin or pipeline between the two elements you want to connect (this + is important if you ever want to disconnect those elements). + In some cases, you will want to create a more elaborate set of capabilities to filter a link between two pads. Then, this function @@ -464,10 +553,10 @@ link_pads_with_filter (GstPad *one, gst_caps_new_full (): -static void -link_pads_with_filter (GstPad *one, - GstPad *other) +static gboolean +link_elements_with_filter (GstElement *element1, GstElement *element2) { + gboolean link_ok; GstCaps *caps; caps = gst_caps_new_full ( @@ -483,7 +572,14 @@ link_pads_with_filter (GstPad *one, NULL), NULL); - gst_pad_link_filtered (one, other, caps); + link_ok = gst_element_link_filtered (element1, element2, caps); + gst_caps_unref (caps); + + if (!link_ok) { + g_warning ("Failed to link element1 and element2!"); + } + + return link_ok; }