Flesh out the OpenVG module documentation a bit.

Reviewed-by: trustme

3 files changed, 269 insertions, 17 deletions

diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
index 9fd4a04..acbaa87 100644
--- a/doc/src/index.qdoc
+++ b/doc/src/index.qdoc
@@ -181,6 +181,7 @@
         <li><a href="qthelp.html">Help Module</a></li>
         <li><a href="qtnetwork.html">Network Module</a></li>
         <li><a href="qtopengl.html">OpenGL Module</a></li>
+        <li><a href="qtopenvg.html">OpenVG Module</a></li>
         <li><a href="qtscript.html">Script Module</a></li>
         <li><a href="qtsql.html">SQL Module</a></li>
         <li><a href="qtsvg.html">SVG Module</a></li>
diff --git a/doc/src/qtopenvg.qdoc b/doc/src/qtopenvg.qdoc
index ad036ef..38be288 100644
--- a/doc/src/qtopenvg.qdoc
+++ b/doc/src/qtopenvg.qdoc
@@ -42,32 +42,283 @@
 /*!
     \module QtOpenVG
     \title QtOpenVG Module
+    \since 4.6
     \contentspage Qt's Modules
     \previouspage QtOpenGL
-    \nextpage QtSql
+    \nextpage QtScript
     \ingroup modules
 
-    \brief The QtOpenVG module offers classes that make it easy to
-    use OpenVG in Qt applications.
+    \brief The QtOpenVG module provides support classes for OpenVG painting.
 
-    From the OpenVG 1.1 Specification:
+    \tableofcontents
 
-    \quotation
+    OpenVG is a standard API from the
+    \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated
+    2D vector graphics that is appearing in an increasing number of
+    embedded devices.
 
-    OpenVG is an application programming interface (API) for hardware-accelerated two-
-    dimensional vector and raster graphics developed under the auspices of the Khronos
-    Group (www.khronos.org). It provides a device-independent and vendor-neutral interface
-    for sophisticated 2D graphical applications, while allowing device manufacturers to
-    provide hardware acceleration where appropriate.
+    OpenVG is optimized for 2D vector operations, and closely matches
+    the functionality in QPainter.  It can therefore be an excellent
+    substitute for the default raster-based QPaintEngine on hardware
+    that supports OpenVG.
 
-    \endquotation
+    \section1 Building Qt with OpenVG support
 
-    The specification, and a reference implementation of it are available from the 
-    \l{http://www.khronos.org/registry/vg/}{Khronos Group}.
+    OpenVG support can be enabled by passing the \c{-openvg} option
+    to configure.  It is assumed that the following qmake variables
+    are set to appropriate values in the qmake.conf file for your
+    platform:
 
-    \bold{Note:} Khronos and OpenVG are trademarks of The Khronos Group Inc. OpenGL is a
-    registered trademark, and OpenGL ES is a trademark, of Silicon Graphics, Inc.
+    \list
+    \o QMAKE_INCDIR_OPENVG
+    \o QMAKE_LIBDIR_OPENVG
+    \o QMAKE_LIBS_OPENVG
+    \endlist
 
+    Most OpenVG implementations are based on EGL, so the following
+    variables may also need to be set:
 
-    The Qt OpenVG module makes it easy to use OpenVG in Qt applications.
+    \list
+    \o QMAKE_INCDIR_EGL
+    \o QMAKE_LIBDIR_EGL
+    \o QMAKE_LIBS_EGL
+    \endlist
+
+    See \l{qmake Variable Reference} for more information on these variables.
+
+    Two kinds of OpenVG engines are currently supported: EGL based,
+    and engines built on top of OpenGL such as
+    \l{http://sourceforge.net/projects/shivavg}{ShivaVG}.
+    EGL based engines are preferred.
+
+    It is assumed that the EGL implementation has some way to turn a
+    QWidget::winId() into an EGL rendering surface with
+    \c{eglCreateWindowSurface()}.  If this is not the case, then
+    modifications may be needed to the code under \c{src/gui/egl} and
+    \c{src/plugins/graphicssystems/openvg} to accomodate the EGL
+    implementation.
+
+    The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg}
+    is an example of how to integrate a non-EGL implementation of
+    OpenVG into Qt.  It is currently only supported with Qt/X11
+    and being an example only, the resulting screen output may not
+    be as good as with other OpenVG engines.
+
+    \section1 Using the OpenVG graphics system
+
+    Once the graphics system plugin has been built and installed,
+    applications can be run as follows to use the plugin:
+
+    \code
+    app -graphicssystem OpenVG
+    \endcode
+
+    If ShivaVG is being used, then substitute \c ShivaVG instead of
+    \c OpenVG in the line above.
+
+    If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS
+    environment variable to 1 and try again.  Usually the plugin
+    cannot be loaded because Qt cannot locate it in the directory
+    \c{plugins/graphicssystems} within the Qt installation, or the
+    dynamic library path does not include the directory containing
+    the system's \c libOpenVG.so library.
+
+    \section1 Supported features
+
+    \section2 Context modes
+
+    The default configuration is "single-context" mode, where a single
+    EGLContext object is used for all drawing, regardless of the surface.
+    Multiple EGLSurfaces are created, one for each window surface or pixmap.
+    eglMakeCurrent() is called with the same EGLContext every time, but a
+    different EGLSurface.
+
+    Single-context mode is necessary for QPixmapData to be implemented in
+    terms of a VGImage.  If single-context mode is not enabled, then QPixmapData
+    will use the fallback QRasterPixmapData implementation, which is less
+    efficient performance-wise.
+
+    Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT define
+    if the OpenVG engine does not support one context with multiple surfaces.
+
+    \section2 Transformation matrices
+
+    All affine and projective transformation matrices are supported.
+
+    QVGPaintEngine will use the engine to accelerate affine transformation
+    matrices only.  When a projective transformation matrix is used,
+    QVGPaintEngine will transform the coordinates before passing them
+    to the engine.  This will probably incur a performance penalty.
+
+    Pixmaps and images are always transformed by the engine, because
+    OpenVG specifies that projective transformations must work for images.
+
+    It is recommended that client applications should avoid using projective
+    transformations for non-image elements in performance critical code.
+
+    \section2 Composition modes
+
+    The following composition modes are supported:
+
+    \list
+    \o QPainter::CompositionMode_SourceOver
+    \o QPainter::CompositionMode_DestinationOver
+    \o QPainter::CompositionMode_Source
+    \o QPainter::CompositionMode_SourceIn
+    \o QPainter::CompositionMode_DestinationIn
+    \o QPainter::CompositionMode_Plus
+    \o QPainter::CompositionMode_Multiply
+    \o QPainter::CompositionMode_Screen
+    \o QPainter::CompositionMode_Darken
+    \o QPainter::CompositionMode_Lighten
+    \endlist
+
+    The other members of QPainter::CompositionMode are not supported
+    because OpenVG 1.1 does not have an equivalent in its \c VGBlendMode
+    enumeration.  Any attempt to set an unsupported mode will result in
+    the actual mode being set to QPainter::CompositionMode_SourceOver.
+    Client applications should avoid using unsupported modes.
+
+    \section2 Pens and brushes
+
+    All pen styles are supported, including cosmetic pens.
+
+    All brush styles are supported except for conical gradients, which are
+    not supported by OpenVG 1.1.  Conical gradients will be converted into a
+    solid color brush corresponding to the first color in the gradient's
+    color ramp.
+
+    Affine matrices are supported for brush transforms, but not projective
+    matrices.
+
+    \section2 Rectangles, lines, and points
+
+    Rectangles and lines use cached VGPath objects to try to accelerate
+    drawing operations.  vgModifyPathCoords() is used to modify the
+    co-ordinates in the cached VGPath object each time fillRect(),
+    drawRects(), or drawLines() is called.
+
+    If the engine does not implement vgModifyPathCoords() properly, then the
+    QVG_NO_MODIFY_PATH define can be set to disable path caching.  This will
+    incur a performance penalty.
+
+    Points are implemented as lines from the point to itself.  The cached
+    line drawing VGPath object is used when drawing points.
+
+    \section2 Polygons and Ellipses
+
+    Polygon and ellipse drawing creates a new VGPath object every time
+    drawPolygon() or drawEllipse() is called.  If the client application is
+    making heavy use of these functions, the constant creation and destruction
+    of VGPath objects could have an impact on performance.
+
+    If a projective transformation is active, ellipses are converted into
+    cubic curves prior to transformation, which may further impact performance.
+
+    Client applications should avoid polygon and ellipse drawing in performance
+    critical code if possible.
+
+    \section2 Other Objects
+
+    Most other objects (arcs, pies, etc) use drawPath(), which takes a
+    QPainterPath argument.  The default implementation in QPainterEngineEx
+    converts the QPainterPath into a QVectorPath and then calls draw(),
+    which in turn converts the QVectorPath into a VGPath for drawing.
+
+    To reduce the overhead, we have overridden drawPath() in QVGPaintEngine
+    to convert QPainterPath's directly into VGPath's.  This should help improve
+    performance compared to the default implementation.
+
+    Client applications should try to avoid these types of objects in
+    performance critical code because of the QPainterPath to VGPath
+    conversion cost.
+
+    \section2 Clipping
+
+    Clipping with QRect, QRectF, and QRegion objects is supported on all
+    OpenVG engines with vgMask() if the transformation matrix is the identity
+    or a simple origin translation.
+
+    Clipping with an arbitrary QPainterPath, or setting the clip region when
+    the transformation matrix is simple, is supported only if the OpenVG engine
+    has the vgRenderToMask() function (OpenVG 1.1 and higher).
+
+    The QVG_NO_RENDER_TO_MASK define will disable the use of vgRenderToMask().
+
+    The QVG_SCISSOR_CLIP define will disable clipping with vgMask() or
+    vgRenderToMask() and instead use the scissor rectangle list to perform
+    clipping.  Clipping with an arbitrary QPainterPath will not be supported.
+    The QVG_SCISSOR_CLIP define should only be used if the OpenVG engine
+    does not support vgMask() or vgRenderToMask().
+
+    \section2 Opacity
+
+    Opacity is supported for all drawing operations.  Solid color pens,
+    solid color brushes, gradient brushes, and image drawing with drawPixmap()
+    and drawImage() will probably have the best performance compared to
+    other kinds of pens and brushes.
+
+    \section2 Text Drawing
+
+    If OpenVG 1.1 is used, the paint engine will use VG fonts to cache glyphs
+    while drawing.  If the engine does not support VG fonts correctly,
+    QVG_NO_DRAW_GLYPHS can be defined to disable this mode.  Text drawing
+    performance will suffer if VG fonts are not used.
+
+    By default, image-based glyphs are used.  If QVG_NO_IMAGE_GLYPHS is defined,
+    then path-based glyphs will be used instead.  QVG_NO_IMAGE_GLYPHS is ignored
+    if QVG_NO_DRAW_GLYPHS is defined.
+
+    If path-based glyphs are used, then the OpenVG engine will need to
+    support hinting to render text with good results.  Image-based glyphs
+    avoids the need for hinting and will usually give better results than
+    path-based glyphs.
+
+    \section2 Pixmaps
+
+    In single-context mode, pixmaps will be implemented using VGImage
+    unless QVG_NO_PIXMAP_DATA is defined.
+
+    QVGPixmapData will convert QImage's into VGImage's when the application
+    calls drawPixmap(), and the pixmap will be kept in VGImage form for the
+    lifetime of the QVGPixmapData object.  When the application tries to paint
+    into a QPixmap with QPainter, the data will be converted back into a
+    QImage and the raster paint engine will be used to render into the QImage.
+
+    This arrangement optimizes for the case of drawing the same static pixmap
+    over and over (e.g. for icons), but does not optimize the case of drawing
+    into pixmaps.
+
+    Bitmaps must use QRasterPixmapData.  They are not accelerated with
+    VGImage at present.
+
+    \section2 Pixmap filters
+
+    Convolution, colorize, and drop shadow filters are accelerated using
+    OpenVG operations.
+
+    \section1 Known issues
+
+    Performance of copying the contents of an OpenVG-rendered window to the
+    screen needs platform-specific work in the QVGWindowSurface class.
+
+    Clipping with arbitrary non-rectangular paths only works on engines
+    that support vgRenderToMask().  Simple rectangular paths are supported
+    on all engines that correctly implement vgMask().
+
+    The paint engine is not yet thread-safe, so it is not recommended for
+    use in threaded Qt applications that draw from multiple threads.
+    Drawing should be limited to the main GUI thread.
+
+    Performance of projective matrices for non-image drawing is not as good
+    as for affine matrices.
+
+    QPixmap's are implemented as VGImage objects so that they can be quickly
+    rendered with drawPixmap().  Rendering into a QPixmap using QPainter
+    will use the default Qt raster paint engine on a QImage copy of the
+    QPixmap, and will not be accelerated.  This issue may be addressed in
+    a future version of the engine.
+
+    ShivaVG support is highly experimental and limited to Qt/X11.  It is
+    provided as an example of how to integrate a non-EGL engine.
  */
diff --git a/doc/src/qtscript.qdoc b/doc/src/qtscript.qdoc
index ac13ddf..f2ac6c9 100644
--- a/doc/src/qtscript.qdoc
+++ b/doc/src/qtscript.qdoc
@@ -44,7 +44,7 @@
   \title QtScript Module
   \since 4.3
   \contentspage Qt's Modules
-  \previouspage QtOpenGL
+  \previouspage QtOpenVG
   \nextpage QtScriptTools
   \ingroup modules
   \ingroup scripting