markdown/for-later/qt-gstreamer-vs-c-gstreamer.md

   1 # QtGStreamer vs C GStreamer
   2
   3 QtGStreamer is designed to mirror the C GStreamer API as closely as
   4 possible. There are, of course, minor differences. They are documented
   5 here.
   6
   7 ## Common Functions
   8
   9 <table>
  10 <colgroup>
  11 <col width="50%" />
  12 <col width="50%" />
  13 </colgroup>
  14 <thead>
  15 <tr class="header">
  16 <th>C GStreamer</th>
  17 <th>QtGStreamer</th>
  18 </tr>
  19 </thead>
  20 <tbody>
  21 <tr class="odd">
  22 <td><code>gst_element_factory_make()</code></td>
  23 <td><code>QGst::ElementFactory::make(const QString &amp;factoryName, const char *elementName=NULL)</code></td>
  24 </tr>
  25 <tr class="even">
  26 <td><code>gst_parse_bin_from_description()</code></td>
  27 <td><code>QGst::Bin::fromDescription(const QString &amp;description, BinFromDescriptionOption ghostUnlinkedPads=Ghost)</code></td>
  28 </tr>
  29 <tr class="odd">
  30 <td><code>gst_caps_from_string()</code></td>
  31 <td><p><code>QGst::Caps::fromString(const QString &amp;string)</code></p></td>
  32 </tr>
  33 <tr class="even">
  34 <td><code>g_signal_connect()</code></td>
  35 <td><code>QGlib::connect(GObject* instance, const char *detailedSignal, T *receiver, R(T::*)(Args...) slot, ConnectFlags flags)</code></td>
  36 </tr>
  37 </tbody>
  38 </table>
  39
  40 ## Naming Convention
  41
  42 QtGStreamer follows a strict naming policy to help make cross
  43 referencing easier:
  44
  45 #### Namespaces
  46
  47 The "G" namespace (`GObject`, `GValue`, etc...) is referred to as
  48 "QGlib".
  49
  50 The "Gst" namespace (`GstObject`, `GstElement`, etc...) is referred to
  51 as "QGst".
  52
  53 #### Class Names
  54
  55 Class names should be the same as their G\* equivalents, with the
  56 namespace prefix removed. For example, "`GstObject`" becomes
  57 "`QGst::Object`", "`GParamSpec`" becomes "`QGlib::ParamSpec`", etc...
  58
  59 #### Method Names
  60
  61 In general the method names should be the same as the GStreamer ones,
  62 with the g\[st\]\_\<class\> prefix removed and converted to camel case.
  63
  64 For example,
  65
  66 ``` c
  67 gboolean gst_caps_is_emtpy(const GstCaps *caps);
  68 ```
  69
  70 becomes:
  71
  72 ``` c
  73 namespace QGst {
  74     class Caps {
  75         bool isEmpty() const;
  76     }
  77 }
  78 ```
  79
  80 There are cases where this may not be followed:
  81
  82 1.  **Properties**. Most property getters have a "get" prefix, for
  83     example, `gst_object_get_name()`. In QtGStreamer the "get" prefix is
  84     omitted, so this becomes just `name()`.
  85 2.  **Overloaded members**. In C there is no possibility to have two
  86     methods with the same name, so overloaded members usually have some
  87     extra suffix, like "\_full". For example, `g_object_set_data()` and
  88     `g_object_set_data_full()`. In C++ we just add a method with the
  89     same name, or put optional parameters in the existing method.
  90 3.  **Other cases where the glib/gstreamer method name doesn't make much
  91     sense**. For example, `gst_element_is_locked_state()`. That doesn't
  92     make sense in english, as "sate" is the subject and should go before
  93     the verb "is". So, it becomes `stateIsLocked()`.
  94
  95 ## Reference Counting
  96
  97 Reference counting is handled the same way as Qt does. There is no need
  98 to call `g_object_ref()`` and g_object_unref()`.
  99
 100 ## Access to GStreamer Elements
 101
 102 QtGStreamer provides access to the underlying C objects, in case you
 103 need them. This is accessible with a simple cast:
 104
 105 ``` c
 106 ElementPtr qgstElement = QGst::ElementFactory::make("playbin");
 107 GstElement* gstElement = GST_ELEMENT(qgstElement);
 108 ```