1. About
--------

QtGStreamer is a set of libraries and plugins providing C++ bindings for
GStreamer [1] with a Qt-style API plus some helper classes for integrating
GStreamer better in Qt [2] applications.

Currently, it consists of the following parts:
 * QtGLib           - Library providing C++/Qt bindings for parts of the GLib
                      and GObject APIs, a base on which QtGStreamer is built.
 * QtGStreamer      - Library providing C++/Qt bindings for GStreamer
 * QtGStreamerUi    - Library providing integration with QtGui. Currently,
                      it only provides a video widget that embeds GStreamer's
                      video sinks.
 * QtGStreamerUtils - Library providing some high level utility classes.

In addition, it provides a "qwidgetvideosink" GStreamer element, an video
sink element that can draw directly on QWidgets using QPainter.

[1]. http://gstreamer.freedesktop.org/
[2]. http://qt.nokia.com/

2. Building
-----------

2.1 Dependencies
----------------

QtGStreamer requires the following software to be installed in order to build:
 * CMake 2.8 or later <http://www.cmake.org/>
 * GStreamer 0.10.31 or later <http://gstreamer.freedesktop.org/>
   With its dependencies:
   - Glib / GObject <http://www.gtk.org/>
   and including gstreamer-plugins-base (0.10.31 or later)
 * Qt 4.5 or later <http://qt.nokia.com/>
 * Automoc <https://projects.kde.org/projects/kdesupport/automoc/>
 * Boost 1.39 or later <http://www.boost.org/>
 * Flex <http://flex.sourceforge.net/>
 * Bison <http://www.gnu.org/software/bison/>

In addition, if gcc is used as the compiler, libstdc++ version 4.5 or later is
required at runtime. This is due to a bug in earlier versions of libstdc++ that
sometimes makes dynamic_cast fail under conditions where it should not.

2.2 Compiler
------------

A decent compiler with proper support for advanced templates, including features
such as partial template specialization, is required. QtGStreamer can also make
use of C++0x features (see below for details). A compiler supporting at least
some of them is recommended. Currently, only the GNU C++ compiler (g++) version
4.5 or later is known to support all the features that QtGStreamer uses. However,
other compilers can be used too, but with some limitations.

C++0x features in use:
 * static_assert(). Used to show nice error messages when the programmer is trying
   to use some template in the wrong way. If not present, the templates will still
   fail to compile if used in the wrong way, but the error messages may be quite
   weird to understand...
 * Variadic templates together with rvalue references. Used to support connecting
   and emitting GObject signals with any number of arguments. If not available, a
   hack-ish implementation using boost's preprocessor library, boost::function and
   boost::bind is used to provide support for up to 9 arguments.

2.3 Procedure
-------------

The build procedure is simple:

$ mkdir build && cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/installation/prefix
$ make
$ make install

Other options that can be passed to cmake include:

* -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel]
  Allows you to specify the type of the build. This is a standard
  cmake option, see the cmake man page for details.

* -DQTGSTREAMER_STATIC=[ON|OFF]
  Allows you to choose whether to build static or dynamic libraries.
  ON means static, OFF means dynamic.

* -DQTGSTREAMER_EXAMPLES=[ON|OFF]
  Allows you to choose whether to build the examples shipped with QtGStreamer or not.
  Note that the examples can also be built independently outside the source tree.

* -DQTGSTREAMER_TESTS=[ON|OFF]
  Allows you to choose whether to build tests or not.

* -DGST_PACKAGE_NAME="some string"
  Allows you to specify the name that gst-inspect will show as the "Binary package"
  name for all the element plugins that are build from this source package.

* -DGST_PACKAGE_ORIGIN="http://some.url"
  Allows you to specify the url that gst-inspect will show as the "Origin URL"
  for all the element plugins that are build from this source package.

2.4 Generating documentation
----------------------------

QtGStreamer uses doxygen for documentation. To generate the documentation you need
to install doxygen and run "make doc" after you have run cmake. This will generate
the documentation in <builddir>/doc/html/.

2.5 Running tests
-----------------

QtGStreamer comes with a suite of automatic unit tests that ensure QtGStreamer
is working properly. To run them you will need ctest, a tool that comes with cmake,
plus some gstreamer plugins from the base and good sets.

To run them, simply invoke "make test" or "ctest" in the build directory.
For advanced usage, refer to the ctest manual page.


3. Links & Contact information
------------------------------

Web:
    http://gstreamer.freedesktop.net
    http://gstreamer.freedesktop.org/wiki/QtGStreamer

Mailing list:
    mailto:gstreamer-devel@lists.sourceforge.net

Irc channels:
    irc://irc.freenode.net/gstreamer
    irc://irc.freenode.net/qtgstreamer

Git repository:
    http://cgit.freedesktop.org/gstreamer/qt-gstreamer/

Bugs, feature requests & patches should be sent at:
    https://bugzilla.gnome.org/enter_bug.cgi?product=GStreamer&component=qt-gstreamer

--
George Kiagiadakis <george.kiagiadakis@collabora.co.uk>
Last updated: Jan 10, 2011
