1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
/*
Copyright (C) 2010 George Kiagiadakis <kiagiadakis.george@gmail.com>
Copyright (C) 2010-2011 Collabora Ltd.
@author George Kiagiadakis <george.kiagiadakis@collabora.co.uk>
This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*! \mainpage QtGStreamer API Reference
*
* \section introduction Introduction
* QtGStreamer is a set of libraries and plugins providing C++ bindings for
* <a href="http://www.gstreamer.net">GStreamer</a> with a Qt-style API plus some
* helper classes for integrating GStreamer better in
* <a href="http://qt.nokia.com">Qt</a> applications.
*
* Currently, it consists of the following parts:
* \li QtGLib - Library providing C++/Qt bindings for parts of the GLib
* and GObject APIs, a base on which QtGStreamer is built.
* \li QtGStreamer - Library providing C++/Qt bindings for GStreamer
* \li QtGStreamerUi - Library providing integration with QtGui. Currently,
* it only provides a video widget that embeds GStreamer's video sinks.
*
* In addition, it provides a "qwidgetvideosink" GStreamer element, an video
* sink element that can draw directly on QWidgets using QPainter.
*
* \section api_reference API Reference
* \li <a href="classes.html">All Classes</a>
* \li <a href="namespaces.html">All Namespaces</a>
*
* \section using_qtgstreamer Using QtGStreamer
* \li \subpage build_system_integration
* \li \subpage coding_conventions
*/
/*! \page build_system_integration Build system integration
*
* \section cmake CMake
*
* If you are using cmake as your build system, using QtGStreamer is quite easy.
* You can just do:
*
* \code
* find_package(QtGStreamer)
* \endcode
*
* which will find QtGStreamer and define the following variables:
*
* \li QTGSTREAMER_FOUND - system has QtGStreamer
* \li QTGSTREAMER_INCLUDE_DIR - the QtGStreamer include directory
* \li QTGSTREAMER_INCLUDES - the include directories needed to use QtGStreamer
* \li QTGLIB_LIBRARY - the QtGLib library
* \li QTGLIB_LIBRARIES - the libraries needed to use QtGLib
* \li QTGSTREAMER_LIBRARY - the QtGStreamer library
* \li QTGSTREAMER_LIBRARIES - the libraries needed to use QtGStreamer
* \li QTGSTREAMER_UI_LIBRARY - the QtGStreamerUi library
* \li QTGSTREAMER_UI_LIBRARIES - the libraries needed to use QtGStreamerUi
* \li QTGSTREAMER_DEFINITIONS - definitions recommended for using QtGStreamer
* \li QTGSTREAMER_FLAGS - extra compiler switches recommended for using QtGStreamer
*
* Take a look at the CMakeLists.txt of the QtGStreamer examples to see how to use them.
*
* \section qmake qmake
*
* If you are using qmake as your build system, you can use QtGStreamer via
* pkg-config. For example:
*
* \code
* CONFIG += link_pkgconfig
* PKGCONFIG += QtGStreamer-0.10
* \endcode
*
* In the PKGCONFIG variable you can set one or more of:
*
* \li QtGLib-2.0 - the libraries needed to use QtGLib
* \li QtGStreamer-0.10 - the libraries needed to use QtGStreamer
* \li QtGStreamerUi-0.10 - the libraries needed to use QtGStreamerUi
*
* \section other_build_systems Other build systems
*
* If you are not using one of the above build systems, you could also use QtGStreamer
* via pkg-config, if your build system integrates with it.
*/
/*! \page coding_conventions Coding conventions
*
* \section headers Headers
*
* The correct way to include a certain QtGStreamer header for a class is to use
* the #include <namespace/class> syntax. For example:
* \code
* #include <QGst/Element>
* \endcode
* All the other lowercase headers (which all end with .h) are considered private
* and should \em not be used directly.
*
* \section smart_pointers Smart pointers
*
* Nearly all the C objects that these bindings wrap are reference counted. This means
* that when you obtain a pointer to such an object, you need to increase its reference
* count value and decrease it when you no longer need that pointer. To make reference
* counting easy, QtGStreamer wraps all those objects in a smart pointer class, RefPointer.
* This smart pointer does all the reference counting work for you and you do not need to
* worry about it at all.
*
* To offer a nice syntax, all those wrapper classes additionally offer typedefs for
* RefPointer, in the form:
* \code
* typedef RefPointer<WrapperClass> WrapperClassPtr;
* \endcode
*/
/*! \namespace QGlib
* \brief Wrappers for Glib and GObject classes
*
* This namespace provides wrapper classes for objects from the Glib and GObject libraries,
* plus some helper classes that provide the foundations for building C++/Qt bindings for
* GObject-based libraries.
*
* \note This namespace is contained in the QtGLib library.
*/
/*! \namespace QGst
* \brief Wrappers for GStreamer classes
*
* This namespace provides wrapper classes for GStreamer objects.
*
* \note This namespace is contained in the QtGStreamer library.
*/
/*! \namespace QGst::Ui
* \brief Helper classes for better integration of GStreamer in graphical Qt applications
*
* This namespace provides helper classes for better integration of GStreamer
* in graphical Qt applications.
*
* \note This namespace is contained in the QtGStreamerUi library.
*/
/*! \page internal_design_details Internal Design Details
*
* This page documents various implementation details for people that are interested
* in contributing to the library itself or who are just interesting in learning how
* some things work.
*
* \section value_design Value Design
* What is interesting about Value is how its set/get methods handle all possible
* kinds of data in a unified way and call the appropriate g(st)_value_set/get_* methods
* internally. This is handled like this: Every type passed to set/get is converted into
* a void* and then it is passed to setData/getData, which use the GType of this type to
* determine if it can be directly assigned to the GValue or if it needs conversion.
* If it can be directly assigned, a dispatcher that holds set/get methods for the various
* GTypes is used to get the appropriate set/get method that knows how to convert void* back
* to the original type and handle it. A method (Value::registerValueVTable()) is
* provided to register additional such methods from client code, if necessary.
* If a conversion is required, it is handled by g_value_transform. This of course means
* that an intermediate GValue that holds the given GType is created and transformed
* accordingly.
*
* Between Value::set/get and Value::setData/getData, there is an intermediate layer,
* struct ValueImpl<T>. This struct provides the actual implementation of set() and get().
* This is provided as an external template, so that it is possible to specialize it for
* specific C++ types that need special handling. Examples include RefPointer<T>, QFlags<T>,
* the various string types (internally, the dispatcher's set/get methods only handle QByteArray
* for Type::String) and others. This is also useful to prevent a certain C++ type from
* being used with Value, if necessary (for example, get<const char*>() is disabled and
* will result in compilation error).
*
* One more thing to note here is that Value::setData/getData are implemented to throw exceptions
* when something goes wrong. These exceptions are later catched in Value::set/get, so that users
* are not faced with exceptions, however, they are used internally from the signals/slots code
* to handle errors and show friendlier error messages. Because Value::set/get catch these
* exceptions, the signals/slots code uses directly ValueImpl<T>.
*
* \section connect_design Connect Design
* connect() is a template method. When it is used, it takes the arguments of the given
* slot and instantiates a template marshaller that is responsible for converting
* the GValues that the signal provides to the C++ types that the slot expects.
* This marshaller and the structure holding the receiver & slot are then attached on
* the data of a GClosure and this GClosure is connected to the signal.
*/
/*! \example echo/main.cpp
* This is a trivial example which echoes the microphone input to the output
*/
/*! \example player/main.cpp
* This is an example audio player using QtGStreamer
*/
|
