docs/pwg/building-boiler.xml

   1 <!-- ############ chapter ############# -->
   2
   3 <chapter id="chapter-building-boiler" xreflabel="Constructing the Boilerplate">
   4   <title>Constructing the Boilerplate</title>
   5   <para>
   6     In this chapter you will learn how to construct the bare minimum code for a
   7     new plugin. Starting from ground zero, you will see how to get the
   8     &GStreamer; template source. Then you will learn how to use a few basic
   9     tools to copy and modify a template plugin to create a new plugin. If you
  10     follow the examples here, then by the end of this chapter you will have a
  11     functional audio filter plugin that you can compile and use in &GStreamer;
  12     applications.
  13   </para>
  14
  15   <!-- ############ sect1 ############# -->
  16
  17   <sect1 id="section-boiler-source" xreflabel="Getting the GStreamer Plugin Templates">
  18     <title>Getting the GStreamer Plugin Templates</title>
  19     <para>
  20       There are currently two ways to develop a new plugin for &GStreamer;: You
  21       can write the entire plugin by hand, or you can copy an existing plugin
  22       template and write the plugin code you need. The second method is by far
  23       the simpler of the two, so the first method will not even be described
  24       here. (Errm, that is, <quote>it is left as an exercise to the
  25       reader.</quote>)
  26     </para>
  27     <para>
  28       The first step is to check out a copy of the
  29       <filename>gst-template</filename> CVS module to get an important tool and
  30       the source code template for a basic &GStreamer; plugin. To check out the
  31       <filename>gst-template</filename> module, make sure you are connected to
  32       the internet, and type the following commands at a command console:
  33     </para>
  34     <screen>
  35 <prompt>shell $ </prompt><userinput>cd .</userinput>
  36 <prompt>shell $ </prompt><userinput>cvs -d:pserver:anonymous@cvs.freedesktop.org:/home/cvs/gstreamer login</userinput>
  37 Logging in to :pserver:anonymous@cvs.freedesktop.org:2401/home/cvs/gstreamer
  38 CVS password:
  39 <prompt>shell $ </prompt><userinput>cvs -z3 -d:pserver:anonymous@cvs.freedesktop.org:/home/cvs/gstreamer co gst-template</userinput>
  40 U gst-template/README
  41 U gst-template/gst-app/AUTHORS
  42 U gst-template/gst-app/ChangeLog
  43 U gst-template/gst-app/Makefile.am
  44 U gst-template/gst-app/NEWS
  45 U gst-template/gst-app/README
  46 U gst-template/gst-app/autogen.sh
  47 U gst-template/gst-app/configure.ac
  48 U gst-template/gst-app/src/Makefile.am
  49 ...
  50     </screen>
  51     <para>
  52       After the first command, you will have to press <keycap>ENTER</keycap> to
  53       log in to the CVS server. (You might have to log in twice.) The second
  54       command will check out a series of files and directories into <filename
  55       class="directory">./gst-template</filename>. The template you will be
  56       using is in <filename
  57       class="directory">./gst-template/gst-plugin/</filename> directory. You
  58       should look over the files in that directory to get a general idea of the
  59       structure of a source tree for a plugin.
  60     </para>
  61   </sect1>
  62
  63   <!-- ############ sect1 ############# -->
  64
  65   <sect1 id="section-boiler-project-stamp" xreflabel="Using the Project Stamp">
  66     <title>Using the Project Stamp</title>
  67     <para>
  68       The first thing to do when making a new element is to specify some basic
  69       details about it: what its name is, who wrote it, what version number it
  70       is, etc. We also need to define an object to represent the element and to
  71       store the data the element needs. These details are collectively known as
  72       the <emphasis>boilerplate</emphasis>.
  73     </para>
  74     <para>
  75       The standard way of defining the boilerplate is simply to write some code,
  76       and fill in some structures. As mentioned in the previous section, the
  77       easiest way to do this is to copy a template and add functionality
  78       according to your needs. To help you do so, there are some tools in the
  79       <filename class="directory">./gst-template/tools/</filename> directory.
  80       One tool, <filename>gst-quick-stamp</filename>, is a quick command line
  81       tool. The other, <filename>gst-project-stamp</filename>, is a full GNOME
  82       druid application that takes you through the steps of creating a new
  83       project (either a plugin or an application).
  84     </para>
  85     <para>
  86       To use <command>pluginstamp.sh</command>, first open up a terminal window.
  87       Change to the <filename class="directory">gst-template</filename>
  88       directory, and then run the <command>pluginstamp.sh</command> command. The
  89       arguments to the <command>pluginstamp.sh</command> are:
  90     </para>
  91     <orderedlist>
  92       <listitem>
  93         <para>the name of the plugin, and</para>
  94       </listitem>
  95       <listitem>
  96         <para>
  97           the directory that should hold a new subdirectory for the source tree
  98           of the plugin.
  99         </para>
 100       </listitem>
 101     </orderedlist>
 102     <para>
 103       Note that capitalization is important for the name of the plugin. Under
 104       some operating systems, capitalization is also important when specifying
 105       directory names. For example, the following commands create the
 106       ExampleFilter plugin based on the plugin template and put the output files
 107       in a new directory called <filename
 108       class="directory">~/src/examplefilter/</filename>:
 109     </para>
 110     <screen>
 111 <prompt>shell $ </prompt><userinput>cd gst-template</userinput>
 112 <prompt>shell $ </prompt><userinput>tools/pluginstamp.sh ExampleFilter ~/src</userinput>
 113     </screen>
 114   </sect1>
 115
 116   <!-- ############ sect1 ############# -->
 117
 118   <sect1 id="section-boiler-examine">
 119     <title>Examining the Basic Code</title>
 120     <para>
 121       First we will examine the code you would be likely to place in a header
 122       file (although since the interface to the code is entirely defined by the
 123       pluging system, and doesn't depend on reading a header file, this is not
 124       crucial.)
 125
 126       The code here can be found in
 127       <filename>examples/pwg/examplefilter/boiler/gstexamplefilter.h</filename>.
 128     </para>
 129
 130     <example id="ex-boiler-examine-h">
 131       <title>Example Plugin Header File</title>
 132       <programlisting>
 133   /* Definition of structure storing data for this element. */
 134   typedef struct _GstExample GstExample;
 135
 136   struct _GstExample {
 137     GstElement element;
 138
 139     GstPad *sinkpad, *srcpad;
 140
 141     gboolean silent;
 142   };
 143
 144   /* Standard definition defining a class for this element. */
 145   typedef struct _GstExampleClass GstExampleClass;
 146   struct _GstExampleClass {
 147     GstElementClass parent_class;
 148   };
 149
 150   /* Standard macros for defining types for this element.  */
 151   #define GST_TYPE_EXAMPLE \
 152     (gst_example_get_type())
 153   #define GST_EXAMPLE(obj) \
 154     (GTK_CHECK_CAST((obj),GST_TYPE_EXAMPLE,GstExample))
 155   #define GST_EXAMPLE_CLASS(klass) \
 156     (GTK_CHECK_CLASS_CAST((klass),GST_TYPE_EXAMPLE,GstExample))
 157   #define GST_IS_EXAMPLE(obj) \
 158     (GTK_CHECK_TYPE((obj),GST_TYPE_EXAMPLE))
 159   #define GST_IS_EXAMPLE_CLASS(obj) \
 160     (GTK_CHECK_CLASS_TYPE((klass),GST_TYPE_EXAMPLE))
 161
 162   /* Standard function returning type information. */
 163   GType gst_example_get_type (void);
 164       </programlisting>
 165     </example>
 166   </sect1>
 167
 168   <!-- ############ sect1 ############# -->
 169
 170   <sect1 id="section-boiler-details">
 171     <title>GstElementDetails</title>
 172     <para>
 173       The GstElementDetails structure gives a heirarchical type for the element,
 174       a human-readable description of the element, as well as author and version
 175       data. The entries are:
 176     </para>
 177     <itemizedlist>
 178       <listitem><para>
 179         A long, english, name for the element.
 180       </para></listitem><listitem><para>
 181         The type of the element, as a heirarchy. The heirarchy is defined by
 182         specifying the top level category, followed by a "/", followed by the
 183         next level category, etc. The type should be defined according to the
 184         guidelines elsewhere in this document. (FIXME: write the guidelines, and
 185         give a better reference to them)
 186       </para></listitem><listitem><para>
 187         A brief description of the purpose of the element.
 188       </para></listitem><listitem><para>
 189         The name of the author of the element, optionally followed by a contact
 190         email address in angle brackets.
 191       </para></listitem>
 192     </itemizedlist>
 193     <para>
 194       For example:
 195     </para>
 196     <programlisting>
 197 static GstElementDetails example_details = {
 198   "An example plugin",
 199   "Example/FirstExample",
 200   "Shows the basic structure of a plugin",
 201   "your name &lt;your.name@your.isp&gt;"
 202 };
 203     </programlisting>
 204     <para>
 205       The element details are registered with the plugin during
 206       <function>_base_init ()</function>.
 207     </para>
 208     <programlisting>
 209 static void
 210 gst_my_filter_base_init (GstMyFilterClass *klass)
 211 {
 212   static GstElementDetails my_filter_details = {
 213 [..]
 214   };
 215   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
 216
 217 [..]
 218   gst_element_class_set_details (element_class, &amp;my_filter_details);
 219 }
 220     </programlisting>
 221   </sect1>
 222
 223   <!-- ############ sect1 ############# -->
 224
 225   <sect1 id="section-boiler-padtemplates">
 226     <title>GstStaticPadTemplate</title>
 227     <para>
 228       A GstStaticPadTemplate is a description of a pad that the element will
 229       (or might) create and use. It contains:
 230     </para>
 231     <itemizedlist>
 232       <listitem>
 233         <para>A short name for the pad.</para>
 234       </listitem>
 235       <listitem>
 236         <para>Pad direction.</para>
 237       </listitem>
 238       <listitem>
 239         <para>
 240           Existence property. This indicates whether the pad exists always (an
 241           <quote>always</quote> pad), only in some cases (a
 242           <quote>sometimes</quote> pad) or only if the application requested
 243           such a pad (a <quote>request</quote> pad).
 244         </para>
 245       </listitem>
 246       <listitem>
 247         <para>Supported types by this element (capabilities).</para>
 248       </listitem>
 249     </itemizedlist>
 250     <para>
 251       For example:
 252     </para>
 253     <programlisting>
 254 static GstStaticPadTemplate sink_factory =
 255 GST_STATIC_PAD_TEMPLATE (
 256   "sink",
 257   GST_PAD_SINK,
 258   GST_PAD_ALWAYS,
 259   GST_STATIC_CAPS ("ANY")
 260 );
 261       </programlisting>
 262     <para>
 263       Those pad templates are registered during the
 264       <function>_base_init ()</function> function. Pads are created from these
 265       templates in the element's <function>_init ()</function> function using
 266       <function>gst_pad_new_from_template ()</function>. The template can be
 267       retrieved from the element class using
 268       <function>gst_element_class_get_pad_template ()</function>. See below
 269       for more details on this.
 270     </para>
 271     <programlisting>
 272 static void
 273 gst_my_filter_base_init (GstMyFilterClass *klass)
 274 {
 275   static GstStaticPadTemplate sink_factory =
 276 [..]
 277   , src_factory =
 278 [..]
 279   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
 280
 281   gst_element_class_add_pad_template (element_class,
 282         gst_static_pad_template_get (&amp;src_factory));
 283   gst_element_class_add_pad_template (element_class,
 284         gst_static_pad_template_get (&amp;sink_factory));
 285 [..]
 286 }
 287     </programlisting>
 288     <para>
 289       The last argument in a template is its type
 290       or list of supported types. In this example, we use 'ANY', which means
 291       that this element will accept all input. In real-life situations, you
 292       would set a mimetype and optionally a set of properties to make sure
 293       that only supported input will come in. This representation should be
 294       a string that starts with a mimetype, then a set of comma-separates
 295       properties with their supported values. In case of an audio filter that
 296       supports raw integer 16-bit audio, mono or stereo at any samplerate, the
 297       correct template would look like this:
 298     </para>
 299     <programlisting>
 300 static GstStaticPadTemplate sink_factory =
 301 GST_STATIC_PAD_TEMPLATE (
 302   "sink",
 303   GST_PAD_SINK,
 304   GST_PAD_ALWAYS,
 305   GST_STATIC_CAPS (
 306     "audio/x-raw-int, "
 307       "width = (int) 16, "
 308       "depth = (int) 16, "
 309       "endianness = (int) BYTE_ORDER, "
 310       "channels = (int) { 1, 2 }, "
 311       "rate = (int) [ 8000, 96000 ]"
 312   )
 313 );
 314     </programlisting>
 315     <para>
 316       Values surrounded by {} are lists, values surrounded by [] are ranges.
 317       Multiple sets of types are supported too, and should be separated by
 318       a semicolon (<quote>;</quote>). Later, in the chapter on pads, we will
 319       see how to use types to know the exact format of a stream:
 320       <xref linkend="chapter-building-pads"/>.
 321     </para>
 322   </sect1>
 323
 324   <!-- ############ sect1 ############# -->
 325
 326   <sect1 id="section-boiler-constructors">
 327     <title>Constructor Functions</title>
 328     <para>
 329       Each element has three functions which are used for construction of an
 330       element. These are the <function>_base_init()</function> function which
 331       is meant to initialize class and child class properties during each new
 332       child class creation; the <function>_class_init()</function> function,
 333       which is used to initialise the class only once (specifying what signals,
 334       arguments and virtual functions the class has and setting up global
 335       state); and the <function>_init()</function> function, which is used to
 336       initialise a specific instance of this type.
 337     </para>
 338   </sect1>
 339
 340   <!-- ############ sect1 ############# -->
 341
 342   <sect1 id="section-boiler-plugininit">
 343     <title>The plugin_init function</title>
 344     <para>
 345       Once we have written code defining all the parts of the plugin, we need to
 346       write the plugin_init() function. This is a special function, which is
 347       called as soon as the plugin is loaded, and should return TRUE or FALSE
 348       depending on whether it loaded initialized any dependencies correctly.
 349       Also, in this function, any supported element type in the plugin should
 350       be registered.
 351     </para>
 352     <programlisting>
 353 static gboolean
 354 plugin_init (GstPlugin *plugin)
 355 {
 356   return gst_element_register (plugin, "my_filter",
 357                                GST_RANK_NONE,
 358                                GST_TYPE_MY_FILTER);
 359 }
 360
 361 GST_PLUGIN_DEFINE (
 362   GST_VERSION_MAJOR,
 363   GST_VERSION_MINOR,
 364   "my_filter",
 365   "My filter plugin",
 366   plugin_init,
 367   VERSION,
 368   "LGPL",
 369   "GStreamer",
 370   "http://gstreamer.net/"
 371 )
 372     </programlisting>
 373     <para>
 374       Note that the information returned by the plugin_init() function will be
 375       cached in a central registry. For this reason, it is important that the
 376       same information is always returned by the function: for example, it
 377       must not make element factories available based on runtime conditions.
 378       If an element can only work in certain conditions (for example, if the
 379       soundcard is not being used by some other process) this must be reflected
 380       by the element being unable to enter the READY state if unavailable,
 381       rather than the plugin attempting to deny existence of the plugin.
 382     </para>
 383   </sect1>
 384 </chapter>