gstreamer/subprojects/gst-docs/markdown/for-later/qt-gstreamer-vs-c-gstreamer.md

108 lines
3.2 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# QtGStreamer vs C GStreamer
QtGStreamer is designed to mirror the C GStreamer API as closely as
possible. There are, of course, minor differences. They are documented
here.
## Common Functions
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead>
<tr class="header">
<th>C GStreamer</th>
<th>QtGStreamer</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>gst_element_factory_make()</code></td>
<td><code>QGst::ElementFactory::make(const QString &amp;factoryName, const char *elementName=NULL)</code></td>
</tr>
<tr class="even">
<td><code>gst_parse_bin_from_description()</code></td>
<td><code>QGst::Bin::fromDescription(const QString &amp;description, BinFromDescriptionOption ghostUnlinkedPads=Ghost)</code></td>
</tr>
<tr class="odd">
<td><code>gst_caps_from_string()</code></td>
<td><p><code>QGst::Caps::fromString(const QString &amp;string)</code></p></td>
</tr>
<tr class="even">
<td><code>g_signal_connect()</code></td>
<td><code>QGlib::connect(GObject* instance, const char *detailedSignal, T *receiver, R(T::*)(Args...) slot, ConnectFlags flags)</code></td>
</tr>
</tbody>
</table>
## Naming Convention
QtGStreamer follows a strict naming policy to help make cross
referencing easier:
#### Namespaces
The "G" namespace (`GObject`, `GValue`, etc...) is referred to as
"QGlib".
The "Gst" namespace (`GstObject`, `GstElement`, etc...) is referred to
as "QGst".
#### Class Names
Class names should be the same as their G\* equivalents, with the
namespace prefix removed. For example, "`GstObject`" becomes
"`QGst::Object`", "`GParamSpec`" becomes "`QGlib::ParamSpec`", etc...
#### Method Names
In general the method names should be the same as the GStreamer ones,
with the g\[st\]\_\<class\> prefix removed and converted to camel case.
For example,
``` c
gboolean gst_caps_is_emtpy(const GstCaps *caps);
```
becomes:
``` c
namespace QGst {
class Caps {
bool isEmpty() const;
}
}
```
There are cases where this may not be followed:
1. **Properties**. Most property getters have a "get" prefix, for
example, `gst_object_get_name()`. In QtGStreamer the "get" prefix is
omitted, so this becomes just `name()`.
2. **Overloaded members**. In C there is no possibility to have two
methods with the same name, so overloaded members usually have some
extra suffix, like "\_full". For example, `g_object_set_data()` and
`g_object_set_data_full()`. In C++ we just add a method with the
same name, or put optional parameters in the existing method.
3. **Other cases where the glib/gstreamer method name doesn't make much
sense**. For example, `gst_element_is_locked_state()`. That doesn't
make sense in english, as "sate" is the subject and should go before
the verb "is". So, it becomes `stateIsLocked()`.
## Reference Counting
Reference counting is handled the same way as Qt does. There is no need
to call `g_object_ref()`` and g_object_unref()`.
## Access to GStreamer Elements
QtGStreamer provides access to the underlying C objects, in case you
need them. This is accessible with a simple cast:
``` c
ElementPtr qgstElement = QGst::ElementFactory::make("playbin");
GstElement* gstElement = GST_ELEMENT(qgstElement);
```