source: trunk/doc/src/howtos/openvg.qdoc@ 603

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page openvg.html
    \title OpenVG Rendering in Qt
    \since 4.6
    \ingroup best-practices

    \brief Efficient rendering on embedded devices with OpenVG

    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. The QtOpenVG plugin provides support for OpenVG
    painting.

    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.

    \tableofcontents

    \section1 Building Qt with OpenVG support

    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:

    \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:

    \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