Update documentation & README

2 files changed, 86 insertions, 30 deletions

diff --git a/README b/README
index 0476dce..081fa5c 100644
--- a/README
+++ b/README
@@ -9,13 +9,17 @@ 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,
+ * QtGStreamerUi    - Library providing integration with QtWidgets. Currently,
                       it only provides a video widget that embeds GStreamer's
                       video sinks.
  * QtGStreamerUtils - Library providing some high level utility classes.
+ * QtGStreamerQuick - Library providing integration with QtQuick (Qt5 only).
 
-In addition, it provides a "qwidgetvideosink" GStreamer element, an video
-sink element that can draw directly on QWidgets using QPainter.
+In addition, it provides GStreamer elements for painting video on Qt surfaces:
+ * qwidgetvideosink  - For painting on QWidgets
+ * qtvideosink       - For painting on any surface with QPainter
+ * qtglvideosink     - For painting on any surface with QPainter and OpenGL
+ * qtquick2videosink - For painting on QtQuick2 surfaces (Qt5 only)
 
 [1]. http://gstreamer.freedesktop.org/
 [2]. http://qt-project.org/
@@ -44,6 +48,10 @@ sometimes makes dynamic_cast fail under conditions where it should not.
 2.2 Compiler
 ------------
 
+Note: This paragraph is outdated. It was written at a time where C++11 support
+was not very widespread among compilers. Nowadays, any C++11 capable compiler
+should work fine.
+
 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
@@ -119,14 +127,26 @@ Other options that can be passed to cmake include:
   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
+2.4 Parallel installation
+-------------------------
+
+QtGStreamer can be built both with Qt4 and Qt5. Installing both versions in
+parallel is possible, since all the libraries, directories and plugins are
+named differently.
+
+Parallel installation is also possible, to a certain extent, between the
+GStreamer-0.10 based version and the GStreamer-1.0 based version. The libraries
+and the GStreamer plugins are co-installable, however the QML plugins as well
+as the headers are NOT.
+
+2.5 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
+2.6 Running tests
 -----------------
 
 QtGStreamer comes with a suite of automatic unit tests that ensure QtGStreamer
@@ -136,6 +156,25 @@ 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.
 
+2.7 Checking build system integrity
+-----------------------------------
+
+In order to check if the installed build system files (QtGStreamerConfig.cmake,
+pkg-config files, etc) are correct and usable externally, you can run:
+
+$ make examples_distcheck
+
+This checks compilation of the examples with both cmake and qmake.
+
+Note that you should also set your environment accordingly for cmake and qmake
+to be able to find QtGStreamer. For example, on my debian system where I have
+installed the Qt5 version of QtGStreamer in /home/gkiagia/install, I would
+have to do:
+
+$ export QT_SELECT=5            # for debian's qmake wrapper to work with Qt5
+$ export PKG_CONFIG_PATH=/home/gkiagia/install/lib/x86_64-linux-gnu/pkgconfig/
+$ export CMAKE_PREFIX_PATH=/home/gkiagia/install/
+$ make examples_distcheck
 
 3. Links & Contact information
 ------------------------------
@@ -159,4 +198,4 @@ Bugs, feature requests & patches should be sent at:
 
 --
 George Kiagiadakis <george.kiagiadakis@collabora.com>
-Last updated: May 3, 2014
+Last updated: Jun 24, 2014
diff --git a/src/main.dox b/src/main.dox
index 55568f9..9e51897 100644
--- a/src/main.dox
+++ b/src/main.dox
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2010-2012 George Kiagiadakis <kiagiadakis.george@gmail.com>
+    Copyright (C) 2010-2014 George Kiagiadakis <kiagiadakis.george@gmail.com>
     Copyright (C) 2010-2011 Collabora Ltd.
       @author George Kiagiadakis <george.kiagiadakis@collabora.co.uk>
 
@@ -28,8 +28,9 @@
  * 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.
+ * \li QtGStreamer - Library providing C++/Qt bindings for GStreamer.
+ * \li QtGStreamerQuick - Library providing integration with QtQuick (Qt5 only).
+ * \li QtGStreamerUi - Library providing integration with QtWidgets.
  * \li QtGStreamerUtils - Library providing some high level utility classes.
  *
  * In addition, it provides GStreamer elements for drawing video on widgets,
@@ -69,6 +70,8 @@
  * \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_QUICK_LIBRARY - the QtGStreamerQuick library
+ * \li QTGSTREAMER_QUICK_LIBRARIES - the libraries needed to use QtGStreamerQuick
  * \li QTGSTREAMER_UI_LIBRARY - the QtGStreamerUi library
  * \li QTGSTREAMER_UI_LIBRARIES - the libraries needed to use QtGStreamerUi
  * \li QTGSTREAMER_UTILS_LIBRARY - the QtGStreamerUtils library
@@ -102,6 +105,10 @@
  * \li Qt5GStreamerUi-1.0
  * \li Qt5GStreamerUtils-1.0
  *
+ * And additionally in Qt5 there is:
+ *
+ * \li Qt5GStreamerQuick-1.0 - the libraries needed to use Qt5GStreamerQuick
+ *
  * \section other_build_systems Other build systems
  *
  * If you are not using one of the above build systems, you could also use QtGStreamer
@@ -136,14 +143,14 @@
  * \endcode
  */
 
-/*! \page qtvideosink_overview qtvideosink / qtglvideosink / qwidgetvideosink
+/*! \page qtvideosink_overview qtvideosink / qtglvideosink / qwidgetvideosink / qtquick2videosink
  *
  * \section overview Overview
  *
  * qtvideosink and its variants are elements that provide native video drawing
  * support for Qt surfaces. qtvideosink and qwidgetvideosink do software painting,
- * using QImage and QPainter. qtglvideosink uses OpenGL/OpenGLES and supports
- * hardware colorspace conversion and color balance.
+ * using QImage and QPainter. qtglvideosink and qtquick2videosink use
+ * OpenGL/OpenGLES and support hardware colorspace conversion and color balance.
  *
  * The API of qtvideosink and qtglvideosink is the same, except that qtglvideosink
  * has an extra "glcontext" property that must be set with the surface's QGLContext
@@ -154,17 +161,21 @@
  * property and it will paint in this widget, without any further tampering,
  * while in qtvideosink you need to handle its signals.
  *
- * All 3 elements require a running Qt event loop and have the inherited limitation
+ * qtquick2videosink has a similar concept to qtvideosink, but it uses the new
+ * scene-graph architecture for drawing in QtQuick items instead of using QPainter.
+ *
+ * All 4 elements require a running Qt event loop and have the inherited limitation
  * from Qt that they must be created, destroyed and have their signals and
  * properties handled from the main (GUI) thread.
  *
- * When drawing video on QtQuick1 (QML) or QGraphicsView, it is recommended to use
- * qtglvideosink, if possible, and fall back to qtvideosink otherwise.
+ * When drawing video on QtQuick1 (QML) or QGraphicsView, it is recommended to
+ * use qtglvideosink, if possible, and fall back to qtvideosink otherwise.
  * When drawing on QWidgets, it is recommended to embed the platform's
  * hardware accelerated sink, such as xvimagesink on X11, and if this is
- * not possible, use qwidgetvideosink.
+ * not possible, use qwidgetvideosink. Finally, when drawing on QtQuick2 (Qt5),
+ * the only way is to use qtquick2videosink.
  *
- * All 3 elements are independent of the QtGStreamer libraries and can be built
+ * All 4 elements are independent of the QtGStreamer libraries and can be built
  * and used without them. However, QtGStreamer provides helper integration classes
  * that you may find useful.
  *
@@ -199,16 +210,17 @@
  * \section usage_with_qtgstreamer Usage with QtGStreamer
  *
  * If you are using the QtGStreamer libraries in your applications, you can directly
- * use QGst::Ui::VideoWidget to embed any of the 3 variants in a QWidget, or
- * QGst::Ui::GraphicsVideoWidget with QGst::Ui::GraphicsVideoSurface to paint
- * on a QGraphicsView.
+ * use QGst::Ui::VideoWidget to embed any of the 3 first variants (i.e. except
+ * the qtquick2 one) in a QWidget, or QGst::Ui::GraphicsVideoWidget with
+ * QGst::Ui::GraphicsVideoSurface to paint on a QGraphicsView.
  *
- * If you are using QtQuick1, there is also a "VideoItem" element available when you import
- * "QtGStreamer 1.0". See the qmlplayer example for details.
+ * If you are using QtQuick (either QtQuick1 with Qt4 or Qt5, or QtQuick2 with Qt5),
+ * there is also a "VideoItem" element available when you import "QtGStreamer 1.0".
+ * See the qmlplayer and qmlplayer2 examples for details.
  *
- * \section qt5_support Qt5 support
+ * \section qt5_notes Qt5 notes
  *
- * When QtGStreamer is compiled with Qt5, those 3 elements are named:
+ * When QtGStreamer is compiled with Qt5, the first 3 elements are named:
  *
  * \li qt5videosink
  * \li qt5glvideosink
@@ -216,10 +228,6 @@
  *
  * This is done to allow them to be parallel installable to their Qt4 counterparts
  * and to avoid Qt version mixing through gstreamer's plugin loading.
- *
- * All 3 elements are based on Qt4 concepts (QtWidgets, QtQuick1) and do not support
- * Qt5's new QtQuick2 scene-graph architecture. Support for that may be added in
- * a future version of QtGStreamer.
  */
 
 /*! \namespace QGlib
@@ -241,10 +249,10 @@
  */
 
 /*! \namespace QGst::Ui
- * \brief Helper classes for better integration of GStreamer in graphical Qt applications
+ * \brief Helper classes for better integration of GStreamer in QtWidgets-based graphical applications
  *
  * This namespace provides helper classes for better integration of GStreamer
- * in graphical Qt applications.
+ * in QtWidgets-based graphical applications.
  *
  * \note This namespace is contained in the QtGStreamerUi library.
  */
@@ -258,6 +266,15 @@
  * \note This namespace is contained in the QtGStreamerUtils library.
  */
 
+/*! \namespace QGst::Quick
+ * \brief Helper classes for better integration of GStreamer in QtQuick-based graphical applications
+ *
+ * This namespace provides helper classes for better integration of GStreamer
+ * in QtQuick-based graphical applications.
+ *
+ * \note This namespace is contained in the QtGStreamerQuick library.
+ */
+
 /*! \page internal_design_details Internal Design Details
  *
  * This page documents various implementation details for people that are interested