Update theme submodule
[platform/upstream/gstreamer.git] / markdown / 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.