Merge branch 'cmake-fixes'
[qtgstreamer:qtgstreamer.git] / README
1 1. About
2 --------
3
4 - What is QtGstreamer?
5
6 QtGstreamer aims to become a library providing C++ bindings for Gstreamer [1]
7 with a Qt-style API plus some helper classes for integrating Gstreamer better
8 in Qt [2] applications.
9
10 [1]. http://gstreamer.freedesktop.org/
11 [2]. http://qt.nokia.com/
12
13 - What is QtGstreamer’s development state at the moment?
14
15 QtGstreamer is still under development, but might be suitable for simple uses.
16 However, note that there is no source or binary compatibility guarantee yet,
17 so if you want to use QtGstreamer in your project, I would recommend to ship
18 it with your sources and build it as a static library.
19
20 - What are the differences between the C++ bindings of QtGstreamer and Gstreamermm?
21
22  * QtGstreamer provides bindings that completely hide the Gstreamer ABI,
23    so your application doesn’t need to link to Gstreamer itself.
24  * QtGstreamer uses QtCore helper classes (QString, QList, etc..) where it can,
25    to ease integration with Qt.
26  * QtGstreamer provides support for connecting arbitrary GObject signals to
27    slots, while in Gstreamermm every signal needs to be defined in the bindings,
28    or else you need to use the C API for connecting it. This is especially useful
29    for connecting signals from element plugins, where their interface is unknown
30    at compile time.
31
32
33 2. Building
34 -----------
35
36 2.1 Dependencies
37 ----------------
38
39 QtGstreamer requires the following software to be installed in order to build:
40  * CMake 2.6 or later <http://www.cmake.org/>
41  * Gstreamer 0.10.30 or later <http://gstreamer.freedesktop.org/>
42    With its dependencies:
43    - Glib / GObject <http://www.gtk.org/>
44  * Qt 4 <http://qt.nokia.com/>
45  * Automoc <svn://anonsvn.kde.org/home/kde/trunk/kdesupport/automoc/>
46  * Boost (static_assert, type_traits, function, bind, preprocessor) <http://www.boost.org/>
47  * Flex <http://flex.sourceforge.net/>
48  * Bison <http://www.gnu.org/software/bison/>
49
50 2.2 Compiler
51 ------------
52
53 A decent compiler with proper support for advanced templates, including features
54 such as partial template specialization, is required. QtGstreamer can also make
55 use of C++0x features (see below for details). A compiler supporting at least
56 some of them is recommended. Currently, only the GNU C++ compiler (g++) version
57 4.3 or later is known to support all the features that QtGstreamer uses. However,
58 other compilers can be used too, but with some limitations.
59
60 C++0x features in use:
61  * static_assert(). Used to show nice error messages when the programmer is trying
62    to use some template in the wrong way. If not present, the templates will still
63    fail to compile if used in the wrong way, but the error messages may be quite
64    weird to understand...
65  * Variadic templates together with rvalue references. Used to support connecting
66    and emitting GObject signals with any number of arguments. If not available, a
67    hack-ish implementation using boost's preprocessor library, boost::function and
68    boost::bind is used to provide support for up to 9 arguments.
69
70 2.3 Procedure
71 -------------
72
73 The build procedure is simple:
74
75 $ mkdir build && cd build
76 $ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/installation/prefix
77 $ make
78 $ make install
79
80 The above commands will build and install QtGstreamer as a shared library.
81 If you prefer to build QtGstreamer as a static library, pass the
82 -DSTATIC_QTGSTREAMER=1 option to cmake, like that:
83
84 $ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/installation/prefix -DSTATIC_QTGSTREAMER=1
85
86 2.4 Generating documentation
87 ----------------------------
88
89 QtGstreamer uses doxygen for documentation. To generate the documentation you need
90 to install doxygen and run "make doc" after you have run cmake. This will generate
91 the documentation in <builddir>/doc/html/.
92
93
94 3. Using QtGstreamer
95 --------------------
96
97 3.1. Build system integration
98 -----------------------------
99
100 If you are using cmake as your build system, using QtGstreamer is quite easy.
101 You can just do:
102
103     find_package(QtGstreamer)
104
105 which will find QtGstreamer and define the following variables:
106
107     QTGSTREAMER_FOUND - system has QtGstreamer
108     QTGSTREAMER_INCLUDE_DIR - the QtGstreamer include directory
109     QTGSTREAMER_INCLUDES - the include directories needed to use QtGstreamer
110     QTGSTREAMER_LIBRARY - the QtGstreamer library
111     QTGSTREAMER_LIBRARIES - the libraries needed to use QtGstreamer
112     QTGSTREAMER_DEFINITIONS - definitions recommended for using QtGstreamer
113     QTGSTREAMER_FLAGS - extra compiler switches recommended for using QtGstreamer
114
115 Take a look at the CMakeLists.txt of the QtGstreamer examples to see how to use them.
116
117 Alternatively, if you are using qmake, you can manually set the required variables,
118 as demonstrated in the example qmake project files that you can find together with
119 the QtGstreamer examples. Unfortunately qmake does not support dynamic detection
120 of installed libraries, so those variables have to be set manually, or you will have
121 to write some wrapper "configure" script that generates a qmake project file. This
122 is quite painful, compared to cmake, thus cmake is recommended.
123
124 3.2. Headers
125 ------------
126
127 The correct way to include a certain QtGstreamer header for a class is to use
128 the #include <namespace/class> syntax. For example: #include <QGst/Element>
129 All the other lowercase headers (which all end with .h) are considered private
130 and should not be used directly.
131
132
133 4. Developing QtGstreamer
134 -------------------------
135
136 4.1. Coding style
137 -----------------
138
139 QtGstreamer follows the kdelibs coding style:
140 http://techbase.kde.org/Policies/Kdelibs_Coding_Style
141
142
143 4.2. Naming policies
144 --------------------
145
146 4.2.1. The namespaces
147 ---------------------
148
149 The "G" namespace (GObject, GValue, etc...) is referred to as "QGlib".
150 The "Gst" namespace (GstObject, GstElement, etc...) is referred to as "QGst".
151 I didn't like them much when I chose them, better names could be discussed...
152
153 4.2.2. The class names
154 ----------------------
155
156 Class names should be the same as their G* equivalents, with the namespace
157 prefix removed. For example, "GstObject" becomes "QGst::Object", "GParamSpec"
158 becomes "QGlib::ParamSpec", etc...
159
160 4.2.3. The method names
161 -----------------------
162
163 In general the method names should be the same as the gstreamer ones,
164 with the g[st]_<class> prefix removed and converted to camel case.
165
166 For example,
167     gboolean gst_caps_is_empty(const GstCaps *caps);
168 becomes:
169     bool isEmpty() const;
170 (and member of the QGst::Caps class)
171
172 There are cases where this may not be followed:
173
174 1) Properties. Most property getters have a "get" prefix, for example,
175 gst_object_get_name(). In QtGstreamer the "get" prefix is omitted, so this
176 becomes just name().
177
178 2) Overloaded members. In C there is no possibility to have two methods with
179 the same name, so overloaded members usually have some extra suffix, like "_full".
180 For example, g_object_set_data and g_object_set_data_full. In C++ we just add
181 a method with the same name, or put optional parameters in the existing method.
182
183 3) Other cases where the glib/gstreamer method name doesn't make much sense...
184 For example, gst_element_is_locked_state(). That doesn't make sense in english,
185 as "state" is the subject and should go before the verb "is".
186 So, it becomes stateIsLocked().
187
188
189 4.3. Refcounted wrappers policy
190 -------------------------------
191
192 All reference counted classes must:
193 1) Inherit from QGlib::RefCountedObject and implement its virtual ref() and
194    unref() methods (and possibly makeWritable() too).
195 2) Include the QGLIB_WRAPPER (or QGST_WRAPPER) macro in their class declaration.
196    This is used like this: QGST_WRAPPER(ClassName).
197 3) Be used with QGlib::RefPointer<T> and provide a
198    typedef QGlib::RefPointer<ClassName> ClassNamePtr;
199
200 No constructor/destructor/copy constructor/assignment operator is allowed for
201 these classes and they are all defined as private in the QGLIB_WRAPPER/QGST_WRAPPER
202 macros.
203
204 RefPointer always creates a new instance of the wrapper class every time it is
205 copied, but it keeps the m_object protected variable of RefCountedObject pointing
206 to the same underlying glib/gstreamer object, using ref()/unref() to keep its
207 reference count correct.
208
209 For classes that implement the makeWritable() virtual method, this method is always
210 called before accessing a non-const member function. This is to implement semantics
211 similar to Qt's implicit sharing for gstreamer classes that use the concept of being
212 writable only when their reference count is 1, such as GstMiniObject and GstCaps.
213 The idea is that makeWritable() makes a copy of the object if its reference count is
214 higher than 1, so when one accesses a non-const method on an object that has more
215 than one references, it is automatically copied.
216
217
218 4.4. About codegen
219 ------------------
220
221 Codegen is a simple code generator that does two basic jobs:
222
223  1) It generates all the implementations of the QGlib::GetType<T> specializations.
224 GetType<T>() is used to get the GType of a type at runtime. Since we don't want
225 the target application to include any glib/gstreamer headers and/or link to
226 glib/gstreamer directly, this is the only way to be able to find the GType of
227 a class in a template class or method, such as RefPointer::dynamicCast(),
228 Value::init(), etc...
229
230 The header declaration of all these specializations is added on the header of each
231 class, with the QGLIB_REGISTER_TYPE() macro. This defines the declaration of the
232 specialization and also acts as a keyword for codegen, which then generates the
233 implementation.
234
235 The usage is simple. For example: QGLIB_REGISTER_TYPE(QGst::Element)
236 With this declaration, codegen will generate an implementation that returns
237 GST_TYPE_ELEMENT.
238
239 If a class name doesn't exactly reflect its GType getter macro, then one can
240 tell codegen which is the real GType macro with a special "codegen instruction"
241 comment after the QGLIB_REGISTER_TYPE keyword that goes like this:
242
243     //codegen: GType=GST_TYPE_FOO
244
245 For example, QGLIB_REGISTER_TYPE(QGlib::ParamSpec) would generate an implementation
246 that returns G_TYPE_PARAM_SPEC. However, that macro doesn't really exist, the
247 correct one is G_TYPE_PARAM. So, we define it like this:
248
249     QGLIB_REGISTER_TYPE(QGst::ParamSpec) //codegen: GType=G_TYPE_PARAM
250
251
252  2) It generates static assertions for all the enums to make sure that their
253 value is exactly the same as their glib/gstreamer equivalent. This is just used
254 as a safety test for developers and doesn't have any impact on the library.
255
256 Since, according to the coding style, all enums should be camel case, starting
257 with a capital and glib's coding style says all enums should be capitals with
258 underscores for separators, codegen does a style conversion to find out the
259 glib/gstreamer equivalent of the enum. An enum that is defined as: FooBar
260 in the namespace QGst will become GST_FOO_BAR. If an enum is defined in such a way
261 that the conversion is not accurate, then one can use a "codegen instruction"
262 after the opening brace of the enum definition that goes like this:
263
264     //codegen: EnumToBeConverted=ENUM_HOW_IT_SHOULD_BE_CONVERTED, SecondEnum=SECONDENUM , ...
265
266 This will assume that "EnumToBeConverted" is "GST_ENUM_HOW_IT_SHOULD_BE_CONVERTED"
267 (assuming that the namespace is QGst), and similar for "SecondEnum" -> GST_SECONDENUM
268
269 A real world example:
270
271 ---- snip ----
272 namespace QGst {
273     enum PadLinkReturn {
274         //codegen: PadLinkNoFormat=PAD_LINK_NOFORMAT, PadLinkNoSched=PAD_LINK_NOSCHED
275         PadLinkOk = 0,
276         PadLinkWrongHierarchy = -1,
277         PadLinkWasLinked = -2,
278         PadLinkWrongDirection = -3,
279         PadLinkNoFormat = -4,
280         PadLinkNoSched = -5,
281         PadLinkRefused = -6
282     };
283 }
284 QGLIB_REGISTER_TYPE(QGst::PadLinkReturn)
285 ---- endsnip ----
286
287 For this snippet, codegen will generate:
288
289 ---- snip ----
290 QGLIB_REGISTER_TYPE_IMPLEMENTATION(QGst::PadLinkReturn,GST_TYPE_PAD_LINK_RETURN)
291
292 namespace QGst {
293     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkOk) == static_cast<int>(GST_PAD_LINK_OK));
294     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkWrongHierarchy) == static_cast<int>(GST_PAD_LINK_WRONG_HIERARCHY));
295     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkWasLinked) == static_cast<int>(GST_PAD_LINK_WAS_LINKED));
296     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkWrongDirection) == static_cast<int>(GST_PAD_LINK_WRONG_DIRECTION));
297     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkNoFormat) == static_cast<int>(GST_PAD_LINK_NOFORMAT));
298     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkNoSched) == static_cast<int>(GST_PAD_LINK_NOSCHED));
299     BOOST_STATIC_ASSERT(static_cast<int>(PadLinkRefused) == static_cast<int>(GST_PAD_LINK_REFUSED));
300 }
301 ---- endsnip ----
302
303
304 4.5. How to contribute
305 ----------------------
306
307 Simply clone the repository on gitorious, develop the feature that you want there
308 and when it's ready, send me a merge request.
309
310
311 --
312 George Kiagiadakis <kiagiadakis.george@gmail.com>
313 Last updated: 11 July 2010