pwg-building-boiler.md

   1 ---
   2 title: Constructing the Boilerplate
   3 ...
   4
   5 # Constructing the Boilerplate
   6
   7 In this chapter you will learn how to construct the bare minimum code
   8 for a new plugin. Starting from ground zero, you will see how to get the
   9 GStreamer template source. Then you will learn how to use a few basic
  10 tools to copy and modify a template plugin to create a new plugin. If
  11 you follow the examples here, then by the end of this chapter you will
  12 have a functional audio filter plugin that you can compile and use in
  13 GStreamer applications.
  14
  15 ## Getting the GStreamer Plugin Templates
  16
  17 There are currently two ways to develop a new plugin for GStreamer: You
  18 can write the entire plugin by hand, or you can copy an existing plugin
  19 template and write the plugin code you need. The second method is by far
  20 the simpler of the two, so the first method will not even be described
  21 here. (Errm, that is, “it is left as an exercise to the reader.”)
  22
  23 The first step is to check out a copy of the `gst-template` git module
  24 to get an important tool and the source code template for a basic
  25 GStreamer plugin. To check out the `gst-template` module, make sure you
  26 are connected to the internet, and type the following commands at a
  27 command
  28 console:
  29
  30 ```
  31 shell $ git clone git://anongit.freedesktop.org/gstreamer/gst-template.git
  32 Initialized empty Git repository in /some/path/gst-template/.git/
  33 remote: Counting objects: 373, done.
  34 remote: Compressing objects: 100% (114/114), done.
  35 remote: Total 373 (delta 240), reused 373 (delta 240)
  36 Receiving objects: 100% (373/373), 75.16 KiB | 78 KiB/s, done.
  37 Resolving deltas: 100% (240/240), done.
  38
  39 ```
  40
  41 This command will check out a series of files and directories into
  42 `gst-template`. The template you will be using is in the
  43 `gst-template/gst-plugin/` directory. You should look over the files in
  44 that directory to get a general idea of the structure of a source tree
  45 for a plugin.
  46
  47 If for some reason you can't access the git repository, you can also
  48 [download a snapshot of the latest
  49 revision](http://cgit.freedesktop.org/gstreamer/gst-template/commit/)
  50 via the cgit web interface.
  51
  52 ## Using the Project Stamp
  53
  54 The first thing to do when making a new element is to specify some basic
  55 details about it: what its name is, who wrote it, what version number it
  56 is, etc. We also need to define an object to represent the element and
  57 to store the data the element needs. These details are collectively
  58 known as the *boilerplate*.
  59
  60 The standard way of defining the boilerplate is simply to write some
  61 code, and fill in some structures. As mentioned in the previous section,
  62 the easiest way to do this is to copy a template and add functionality
  63 according to your needs. To help you do so, there is a tool in the
  64 `./gst-plugin/tools/` directory. This tool, `make_element`, is a command
  65 line utility that creates the boilerplate code for you.
  66
  67 To use `make_element`, first open up a terminal window. Change to the
  68 `gst-template/gst-plugin/src` directory, and then run the `make_element`
  69 command. The arguments to the `make_element` are:
  70
  71 1.  the name of the plugin, and
  72
  73 2.  the source file that the tool will use. By default, `gstplugin` is
  74     used.
  75
  76 For example, the following commands create the MyFilter plugin based on
  77 the plugin template and put the output files in the
  78 `gst-template/gst-plugin/src` directory:
  79
  80 ```
  81 shell $ cd gst-template/gst-plugin/src
  82 shell $ ../tools/make_element MyFilter
  83
  84 ```
  85
  86 > **Note**
  87 >
  88 > Capitalization is important for the name of the plugin. Keep in mind
  89 > that under some operating systems, capitalization is also important
  90 > when specifying directory and file names in general.
  91
  92 The last command creates two files: `gstmyfilter.c` and `gstmyfilter.h`.
  93
  94 > **Note**
  95 >
  96 > It is recommended that you create a copy of the `gst-plugin` directory
  97 > before continuing.
  98
  99 Now one needs to adjust the `Makefile.am` to use the new filenames and
 100 run `autogen.sh` from the parent directory to bootstrap the build
 101 environment. After that, the project can be built and installed using
 102 the well known `make && sudo make install` commands.
 103
 104 > **Note**
 105 >
 106 > Be aware that by default `autogen.sh` and `configure` would choose
 107 > `/usr/local` as a default location. One would need to add
 108 > `/usr/local/lib/gstreamer-1.0` to `GST_PLUGIN_PATH` in order to make
 109 > the new plugin show up in a gstreamer that's been installed from
 110 > packages.
 111
 112 > **Note**
 113 >
 114 > FIXME: this section is slightly outdated. gst-template is still useful
 115 > as an example for a minimal plugin build system skeleton. However, for
 116 > creating elements the tool gst-element-maker from gst-plugins-bad is
 117 > recommended these days.
 118
 119 ## Examining the Basic Code
 120
 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
 123 the plugin system, and doesn't depend on reading a header file, this is
 124 not crucial.)
 125
 126 ``` c
 127 #include <gst/gst.h>
 128
 129 /* Definition of structure storing data for this element. */
 130 typedef struct _GstMyFilter {
 131   GstElement element;
 132
 133   GstPad *sinkpad, *srcpad;
 134
 135   gboolean silent;
 136
 137
 138
 139 } GstMyFilter;
 140
 141 /* Standard definition defining a class for this element. */
 142 typedef struct _GstMyFilterClass {
 143   GstElementClass parent_class;
 144 } GstMyFilterClass;
 145
 146 /* Standard macros for defining types for this element.  */
 147 #define GST_TYPE_MY_FILTER (gst_my_filter_get_type())
 148 #define GST_MY_FILTER(obj) \
 149   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_MY_FILTER,GstMyFilter))
 150 #define GST_MY_FILTER_CLASS(klass) \
 151   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_MY_FILTER,GstMyFilterClass))
 152 #define GST_IS_MY_FILTER(obj) \
 153   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_MY_FILTER))
 154 #define GST_IS_MY_FILTER_CLASS(klass) \
 155   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_MY_FILTER))
 156
 157 /* Standard function returning type information. */
 158 GType gst_my_filter_get_type (void);
 159
 160 ```
 161
 162 Using this header file, you can use the following macro to setup the
 163 `GObject` basics in your source file so that all functions will be
 164 called appropriately:
 165
 166 ``` c
 167 #include "filter.h"
 168
 169 G_DEFINE_TYPE (GstMyFilter, gst_my_filter, GST_TYPE_ELEMENT);
 170
 171 ```
 172
 173 ## Element metadata
 174
 175 The Element metadata provides extra element information. It is
 176 configured with `gst_element_class_set_metadata` or
 177 `gst_element_class_set_static_metadata` which takes the following
 178 parameters:
 179
 180   - A long, English, name for the element.
 181
 182   - The type of the element, see the docs/design/draft-klass.txt
 183     document in the GStreamer core source tree for details and examples.
 184
 185   - A brief description of the purpose of the element.
 186
 187   - The name of the author of the element, optionally followed by a
 188     contact email address in angle brackets.
 189
 190 For example:
 191
 192 ``` c
 193 gst_element_class_set_static_metadata (klass,
 194   "An example plugin",
 195   "Example/FirstExample",
 196   "Shows the basic structure of a plugin",
 197   "your name <your.name@your.isp>");
 198
 199 ```
 200
 201 The element details are registered with the plugin during the
 202 `_class_init ()` function, which is part of the GObject system. The
 203 `_class_init ()` function should be set for this GObject in the function
 204 where you register the type with GLib.
 205
 206 ``` c
 207 static void
 208 gst_my_filter_class_init (GstMyFilterClass * klass)
 209 {
 210   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
 211
 212 [..]
 213   gst_element_class_set_static_metadata (element_klass,
 214     "An example plugin",
 215     "Example/FirstExample",
 216     "Shows the basic structure of a plugin",
 217     "your name <your.name@your.isp>");
 218
 219 }
 220
 221 ```
 222
 223 ## GstStaticPadTemplate
 224
 225 A GstStaticPadTemplate is a description of a pad that the element will
 226 (or might) create and use. It contains:
 227
 228   - A short name for the pad.
 229
 230   - Pad direction.
 231
 232   - Existence property. This indicates whether the pad exists always (an
 233     “always” pad), only in some cases (a “sometimes” pad) or only if the
 234     application requested such a pad (a “request” pad).
 235
 236   - Supported types by this element (capabilities).
 237
 238 For example:
 239
 240 ``` c
 241 static GstStaticPadTemplate sink_factory =
 242 GST_STATIC_PAD_TEMPLATE (
 243   "sink",
 244   GST_PAD_SINK,
 245   GST_PAD_ALWAYS,
 246   GST_STATIC_CAPS ("ANY")
 247 );
 248
 249
 250
 251 ```
 252
 253 Those pad templates are registered during the `_class_init ()` function
 254 with the `gst_element_class_add_pad_template ()`. For this function you
 255 need a handle the `GstPadTemplate` which you can create from the static
 256 pad template with `gst_static_pad_template_get ()`. See below for more
 257 details on this.
 258
 259 Pads are created from these static templates in the element's `_init ()`
 260 function using `gst_pad_new_from_static_template ()`. In order to create
 261 a new pad from this template using `gst_pad_new_from_static_template
 262 ()`, you will need to declare the pad template as a global variable.
 263 More on this subject in [Specifying the pads](pwg-building-pads.md).
 264
 265     static GstStaticPadTemplate sink_factory = [..],
 266         src_factory = [..];
 267
 268     static void
 269     gst_my_filter_class_init (GstMyFilterClass * klass)
 270     {
 271       GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
 272     [..]
 273
 274       gst_element_class_add_pad_template (element_class,
 275         gst_static_pad_template_get (&src_factory));
 276       gst_element_class_add_pad_template (element_class,
 277         gst_static_pad_template_get (&sink_factory));
 278     }
 279
 280 The last argument in a template is its type or list of supported types.
 281 In this example, we use 'ANY', which means that this element will accept
 282 all input. In real-life situations, you would set a media type and
 283 optionally a set of properties to make sure that only supported input
 284 will come in. This representation should be a string that starts with a
 285 media type, then a set of comma-separates properties with their
 286 supported values. In case of an audio filter that supports raw integer
 287 16-bit audio, mono or stereo at any samplerate, the correct template
 288 would look like this:
 289
 290 ``` c
 291
 292 static GstStaticPadTemplate sink_factory =
 293 GST_STATIC_PAD_TEMPLATE (
 294   "sink",
 295   GST_PAD_SINK,
 296   GST_PAD_ALWAYS,
 297   GST_STATIC_CAPS (
 298     "audio/x-raw, "
 299       "format = (string) " GST_AUDIO_NE (S16) ", "
 300       "channels = (int) { 1, 2 }, "
 301       "rate = (int) [ 8000, 96000 ]"
 302   )
 303 );
 304
 305
 306 ```
 307
 308 Values surrounded by curly brackets (“{” and “}”) are lists, values
 309 surrounded by square brackets (“\[” and “\]”) are ranges. Multiple sets
 310 of types are supported too, and should be separated by a semicolon
 311 (“;”). Later, in the chapter on pads, we will see how to use types
 312 to know the exact format of a stream: [Specifying the
 313 pads](pwg-building-pads.md).
 314
 315 ## Constructor Functions
 316
 317 Each element has two functions which are used for construction of an
 318 element. The `_class_init()` function, which is used to initialise the
 319 class only once (specifying what signals, arguments and virtual
 320 functions the class has and setting up global state); and the `_init()`
 321 function, which is used to initialise a specific instance of this type.
 322
 323 ## The plugin\_init function
 324
 325 Once we have written code defining all the parts of the plugin, we need
 326 to write the plugin\_init() function. This is a special function, which
 327 is called as soon as the plugin is loaded, and should return TRUE or
 328 FALSE depending on whether it loaded initialized any dependencies
 329 correctly. Also, in this function, any supported element type in the
 330 plugin should be registered.
 331
 332 ``` c
 333
 334
 335 static gboolean
 336 plugin_init (GstPlugin *plugin)
 337 {
 338   return gst_element_register (plugin, "my_filter",
 339                    GST_RANK_NONE,
 340                    GST_TYPE_MY_FILTER);
 341 }
 342
 343 GST_PLUGIN_DEFINE (
 344   GST_VERSION_MAJOR,
 345   GST_VERSION_MINOR,
 346   my_filter,
 347   "My filter plugin",
 348   plugin_init,
 349   VERSION,
 350   "LGPL",
 351   "GStreamer",
 352   "http://gstreamer.net/"
 353 )
 354
 355
 356
 357 ```
 358
 359 Note that the information returned by the plugin\_init() function will
 360 be cached in a central registry. For this reason, it is important that
 361 the same information is always returned by the function: for example, it
 362 must not make element factories available based on runtime conditions.
 363 If an element can only work in certain conditions (for example, if the
 364 soundcard is not being used by some other process) this must be
 365 reflected by the element being unable to enter the READY state if
 366 unavailable, rather than the plugin attempting to deny existence of the
 367 plugin.
 368