pwg-other-base.md

   1 ---
   2 title: Pre-made base classes
   3 ...
   4
   5 # Pre-made base classes
   6
   7 So far, we've been looking at low-level concepts of creating any type of
   8 GStreamer element. Now, let's assume that all you want is to create an
   9 simple audiosink that works exactly the same as, say, “esdsink”, or a
  10 filter that simply normalizes audio volume. Such elements are very
  11 general in concept and since they do nothing special, they should be
  12 easier to code than to provide your own scheduler activation functions
  13 and doing complex caps negotiation. For this purpose, GStreamer provides
  14 base classes that simplify some types of elements. Those base classes
  15 will be discussed in this chapter.
  16
  17 ## Writing a sink
  18
  19 Sinks are special elements in GStreamer. This is because sink elements
  20 have to take care of *preroll*, which is the process that takes care
  21 that elements going into the `GST_STATE_PAUSED` state will have buffers
  22 ready after the state change. The result of this is that such elements
  23 can start processing data immediately after going into the
  24 `GST_STATE_PLAYING` state, without requiring to take some time to
  25 initialize outputs or set up decoders; all that is done already before
  26 the state-change to `GST_STATE_PAUSED` successfully completes.
  27
  28 Preroll, however, is a complex process that would require the same code
  29 in many elements. Therefore, sink elements can derive from the
  30 `GstBaseSink` base-class, which does preroll and a few other utility
  31 functions automatically. The derived class only needs to implement a
  32 bunch of virtual functions and will work automatically.
  33
  34 The base class implement much of the synchronization logic that a sink
  35 has to perform.
  36
  37 The `GstBaseSink` base-class specifies some limitations on elements,
  38 though:
  39
  40   - It requires that the sink only has one sinkpad. Sink elements that
  41     need more than one sinkpad, must make a manager element with
  42     multiple GstBaseSink elements inside.
  43
  44 Sink elements can derive from `GstBaseSink` using the usual `GObject`
  45 convenience macro `G_DEFINE_TYPE ()`:
  46
  47 ``` c
  48 G_DEFINE_TYPE (GstMySink, gst_my_sink, GST_TYPE_BASE_SINK);
  49
  50 [..]
  51
  52 static void
  53 gst_my_sink_class_init (GstMySinkClass * klass)
  54 {
  55   klass->set_caps = [..];
  56   klass->render = [..];
  57 [..]
  58 }
  59
  60 ```
  61
  62 The advantages of deriving from `GstBaseSink` are numerous:
  63
  64   - Derived implementations barely need to be aware of preroll, and do
  65     not need to know anything about the technical implementation
  66     requirements of preroll. The base-class does all the hard work.
  67
  68     Less code to write in the derived class, shared code (and thus
  69     shared bugfixes).
  70
  71 There are also specialized base classes for audio and video, let's look
  72 at those a bit.
  73
  74 ### Writing an audio sink
  75
  76 Essentially, audio sink implementations are just a special case of a
  77 general sink. An audio sink has the added complexity that it needs to
  78 schedule playback of samples. It must match the clock selected in the
  79 pipeline against the clock of the audio device and calculate and
  80 compensate for drift and jitter.
  81
  82 There are two audio base classes that you can choose to derive from,
  83 depending on your needs: `GstAudioBasesink` and `GstAudioSink`. The
  84 audiobasesink provides full control over how synchronization and
  85 scheduling is handled, by using a ringbuffer that the derived class
  86 controls and provides. The audiosink base-class is a derived class of
  87 the audiobasesink, implementing a standard ringbuffer implementing
  88 default synchronization and providing a standard audio-sample clock.
  89 Derived classes of this base class merely need to provide a `_open
  90 ()`, `_close ()` and a `_write
  91 ()` function implementation, and some optional functions. This should
  92 suffice for many sound-server output elements and even most interfaces.
  93 More demanding audio systems, such as Jack, would want to implement the
  94 `GstAudioBaseSink` base-class.
  95
  96 The `GstAudioBaseSink` has little to no limitations and should fit
  97 virtually every implementation, but is hard to implement. The
  98 `GstAudioSink`, on the other hand, only fits those systems with a simple
  99 `open
 100 ()` / `close ()` / `write
 101 ()` API (which practically means pretty much all of them), but has the
 102 advantage that it is a lot easier to implement. The benefits of this
 103 second base class are large:
 104
 105   - Automatic synchronization, without any code in the derived class.
 106
 107   - Also automatically provides a clock, so that other sinks (e.g. in
 108     case of audio/video playback) are synchronized.
 109
 110   - Features can be added to all audiosinks by making a change in the
 111     base class, which makes maintenance easy.
 112
 113   - Derived classes require only three small functions, plus some
 114     `GObject` boilerplate code.
 115
 116 In addition to implementing the audio base-class virtual functions,
 117 derived classes can (should) also implement the `GstBaseSink` `set_caps
 118 ()` and `get_caps ()` virtual functions for negotiation.
 119
 120 ### Writing a video sink
 121
 122 Writing a videosink can be done using the `GstVideoSink` base-class,
 123 which derives from `GstBaseSink` internally. Currently, it does nothing
 124 yet but add another compile dependency, so derived classes will need to
 125 implement all base-sink virtual functions. When they do this correctly,
 126 this will have some positive effects on the end user experience with the
 127 videosink:
 128
 129   - Because of preroll (and the `preroll ()` virtual function), it is
 130     possible to display a video frame already when going into the
 131     `GST_STATE_PAUSED` state.
 132
 133   - By adding new features to `GstVideoSink`, it will be possible to add
 134     extensions to videosinks that affect all of them, but only need to
 135     be coded once, which is a huge maintenance benefit.
 136
 137 ## Writing a source
 138
 139 In the previous part, particularly [Providing random
 140 access](pwg-scheduling.md#providing-random-access), we have learned
 141 that some types of elements can provide random access. This applies most
 142 definitely to source elements reading from a randomly seekable location,
 143 such as file sources. However, other source elements may be better
 144 described as a live source element, such as a camera source, an audio
 145 card source and such; those are not seekable and do not provide
 146 byte-exact access. For all such use cases, GStreamer provides two base
 147 classes: `GstBaseSrc` for the basic source functionality, and
 148 `GstPushSrc`, which is a non-byte exact source base-class. The
 149 pushsource base class itself derives from basesource as well, and thus
 150 all statements about the basesource apply to the pushsource, too.
 151
 152 The basesrc class does several things automatically for derived classes,
 153 so they no longer have to worry about it:
 154
 155   - Fixes to `GstBaseSrc` apply to all derived classes automatically.
 156
 157   - Automatic pad activation handling, and task-wrapping in case we get
 158     assigned to start a task ourselves.
 159
 160 The `GstBaseSrc` may not be suitable for all cases, though; it has
 161 limitations:
 162
 163   - There is one and only one sourcepad. Source elements requiring
 164     multiple sourcepads must implement a manager bin and use multiple
 165     source elements internally or make a manager element that uses a
 166     source element and a demuxer inside.
 167
 168 It is possible to use special memory, such as X server memory pointers
 169 or `mmap ()`'ed memory areas, as data pointers in buffers returned from
 170 the `create()` virtual function.
 171
 172 ### Writing an audio source
 173
 174 An audio source is nothing more but a special case of a pushsource.
 175 Audio sources would be anything that reads audio, such as a source
 176 reading from a soundserver, a kernel interface (such as ALSA) or a test
 177 sound / signal generator. GStreamer provides two base classes, similar
 178 to the two audiosinks described in [Writing an audio
 179 sink](#writing-an-audio-sink); one is ringbuffer-based, and requires the
 180 derived class to take care of its own scheduling, synchronization and
 181 such. The other is based on this `GstAudioBaseSrc` and is called
 182 `GstAudioSrc`, and provides a simple `open ()`, `close ()` and `read ()`
 183 interface, which is rather simple to implement and will suffice for most
 184 soundserver sources and audio interfaces (e.g. ALSA or OSS) out there.
 185
 186 The `GstAudioSrc` base-class has several benefits for derived classes,
 187 on top of the benefits of the `GstPushSrc` base-class that it is based
 188 on:
 189
 190   - Does syncronization and provides a clock.
 191
 192   - New features can be added to it and will apply to all derived
 193     classes automatically.
 194
 195 ## Writing a transformation element
 196
 197 A third base-class that GStreamer provides is the `GstBaseTransform`.
 198 This is a base class for elements with one sourcepad and one sinkpad
 199 which act as a filter of some sort, such as volume changing, audio
 200 resampling, audio format conversion, and so on and so on. There is quite
 201 a lot of bookkeeping that such elements need to do in order for things
 202 such as buffer allocation forwarding, passthrough, in-place processing
 203 and such to all work correctly. This base class does all that for you,
 204 so that you just need to do the actual processing.
 205
 206 Since the `GstBaseTransform` is based on the 1-to-1 model for filters,
 207 it may not apply well to elements such as decoders, which may have to
 208 parse properties from the stream. Also, it will not work for elements
 209 requiring more than one sourcepad or sinkpad.
 210