Add documentation for GraphicsVideoSurface, GraphicsVideoWidget and the qmlplayer example.

2 files changed, 50 insertions, 1 deletions

diff --git a/src/QGst/Ui/graphicsvideosurface.h b/src/QGst/Ui/graphicsvideosurface.h
index 07343d4..629690b 100644
--- a/src/QGst/Ui/graphicsvideosurface.h
+++ b/src/QGst/Ui/graphicsvideosurface.h
@@ -31,6 +31,12 @@ class GraphicsVideoSurfacePrivate;
 /*! \headerfile graphicsvideosurface.h <QGst/Ui/GraphicsVideoSurface>
  * \brief Helper class for painting video on a QGraphicsView
  *
+ * This is a helper class that represents a video surface on a QGraphicsView.
+ * This is not a QGraphicsItem, though, it is just a helper class to bind
+ * the video sink to a specific view. To use it, create a GraphicsVideoWidget,
+ * add it to your scene and connect it with this surface.
+ *
+ * Example
  * \code
  * QGraphicsView *view = new QGraphicsView;
  * view->setViewport(new QGLWidget); //recommended
@@ -40,6 +46,39 @@ class GraphicsVideoSurfacePrivate;
  * widget->setSurface(surface);
  * view->addItem(widget);
  * \endcode
+ *
+ * This class internally creates and uses a "qtvideosink" element. This element
+ * is created the first time it is requested and a reference is kept internally.
+ *
+ * To make use of OpenGL hardware acceleration in qtvideosink, it is recommended
+ * that you set a QGLWidget as the viewport of the QGraphicsView. Note that you must
+ * do this before the qtvideosink element is requested for the first time using the
+ * videoSink() method, as it needs to find a GL context at construction time to
+ * query the hardware about supported features. If you don't use OpenGL acceleration,
+ * painting will be done in software with QImage and QPainter.
+ *
+ * This class can also be used to paint video on QML.
+ *
+ * Example:
+ * \code
+ * // in your C++ code
+ * QDeclarativeView *view = new QDeclarativeView;
+ * view->setViewport(new QGLWidget); //recommended
+ * QGst::Ui::GraphicsVideoSurface *surface = new QGst::Ui::GraphicsVideoSurface(view);
+ * view->rootContext()->setContextProperty(QLatin1String("videoSurface"), surface);
+ * ...
+ * // and in your qml file:
+ * import QtGStreamer 0.10
+ * ...
+ * VideoItem {
+ *      id: video
+ *      width: 320
+ *      height: 240
+ *      surface: videoSurface
+ * }
+ * \endcode
+ *
+ * \sa GraphicsVideoWidget
  */
 class QTGSTREAMERUI_EXPORT GraphicsVideoSurface : public QObject
 {
diff --git a/src/QGst/Ui/graphicsvideowidget.h b/src/QGst/Ui/graphicsvideowidget.h
index af3ff31..d034f1d 100644
--- a/src/QGst/Ui/graphicsvideowidget.h
+++ b/src/QGst/Ui/graphicsvideowidget.h
@@ -24,6 +24,16 @@
 namespace QGst {
 namespace Ui {
 
+/*! \headerfile graphicsvideowidget.h <QGst/Ui/GraphicsVideoWidget>
+ * \brief A QGraphicsWidget for displaying video on a QGraphicsScene
+ *
+ * This is a QGraphicsWidget subclass that can display video. To use it,
+ * you have to create a GraphicsVideoSurface and connect it with this
+ * widget using the setSurface() method or the surface property.
+ * See the GraphicsVideoSurface documentation for details and examples.
+ *
+ * \sa GraphicsVideoSurface
+ */
 class QTGSTREAMERUI_EXPORT GraphicsVideoWidget : public QGraphicsWidget
 {
     Q_OBJECT
@@ -33,7 +43,7 @@ public:
     explicit GraphicsVideoWidget(QGraphicsItem *parent = 0, Qt::WindowFlags wFlags = 0);
     virtual ~GraphicsVideoWidget();
 
-    /*! \reimpl */
+    /*! Reimplemented from QGraphicsWidget. Do not call directly. */
     virtual void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
 
     GraphicsVideoSurface *surface() const;