docs/manual/links.xml

   1 <chapter id="cha-links">
   2   <title>Linking elements</title>
   3   <para>
   4     You can link the different pads of elements together so that the elements
   5     form a chain.
   6   </para>
   7
   8   <figure float="1" id="sec-link">
   9     <title>Visualisation of three linked elements</title>
  10       <mediaobject>
  11         <imageobject>
  12           <imagedata fileref="images/linked-elements.&magic;" format="&MAGIC;" />
  13         </imageobject>
  14       </mediaobject>
  15   </figure>
  16   <para>
  17     By linking these three elements, we have created a very simple
  18     chain. The effect of this will be that the output of the source element
  19     (element1) will be used as input for the filter element (element2). The
  20     filter element will do something with the data and send the result to
  21     the final sink element (element3).
  22   </para>
  23   <para>
  24     Imagine the above graph as a simple MPEG audio decoder. The source
  25     element is a disk source, the filter element is the MPEG decoder and
  26     the sink element is your audiocard. We will use this simple graph to
  27     construct an MPEG player later in this manual.
  28   </para>
  29
  30   <sect1 id="sec-link-basic">
  31    <title>Making simple links</title>
  32    <para>
  33      You can link two pads with:
  34    </para>
  35    <programlisting>
  36  GstPad *srcpad, *sinkpad;
  37
  38  srcpad = gst_element_get_pad (element1, "src");
  39  sinpad = gst_element_get_pad (element2, "sink");
  40
  41  // link them
  42  gst_pad_link (srcpad, sinkpad);
  43    ....
  44  // and unlink them
  45  gst_pad_unlink (srcpad, sinkpad);
  46
  47   </programlisting>
  48    <para>
  49      A convenient shortcut for the above code is done with the gst_element_link_pads ()
  50      function:
  51    </para>
  52   <programlisting>
  53
  54  // link them
  55  gst_element_link_pads (element1, "src", element2, "sink");
  56    ....
  57  // and unlink them
  58  gst_element_unlink_pads (element1, "src", element2, "sink");
  59
  60   </programlisting>
  61    <para>
  62      An even more convenient shortcut for single-source, single-sink elements is the
  63      gst_element_link () function:
  64    </para>
  65   <programlisting>
  66
  67  // link them
  68  gst_element_link (element1, element2);
  69    ....
  70  // and unlink them
  71  gst_element_unlink (element1, element2);
  72
  73   </programlisting>
  74    <para>
  75      If you have more than one element to link, the gst_element_link_many () function takes
  76      a NULL-terminated list of elements:
  77    </para>
  78   <programlisting>
  79
  80  // link them
  81  gst_element_link_many (element1, element2, element3, element4, NULL);
  82    ....
  83  // and unlink them
  84  gst_element_unlink_many (element1, element2, element3, element4, NULL);
  85
  86   </programlisting>
  87    <para>
  88      You can query if a pad is linked with GST_PAD_IS_LINKED (pad).
  89    </para>
  90    <para>
  91      To query for the <classname>GstPad</classname> a pad is linked to, use
  92      gst_pad_get_peer (pad).
  93    </para>
  94   </sect1>
  95
  96   <sect1 id="sec-link-filtered">
  97    <title>Making filtered links</title>
  98     <para>
  99       You can also force a specific media type on the link by using gst_pad_link_filtered ()
 100       and gst_element_link_filtered (). FIXME link to caps documentation.
 101     </para>
 102   </sect1>
 103
 104 </chapter>