doc/src/platforms/x11overlays.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page x11overlays.html
  30     \title How to Use X11 Overlays with Qt
  31         \ingroup best-practices
  32
  33     X11 overlays are a powerful mechanism for drawing
  34     annotations etc., on top of an image without destroying it, thus saving
  35     a great deal of image rendering time. For more information, see the highly
  36     recommended book \e{OpenGL Programming for the X Window System} (Mark
  37     Kilgard, Addison Wesley Developers Press 1996).
  38
  39     \warning The Qt OpenGL Extension includes direct support for the
  40     use of OpenGL overlays. For many uses of overlays, this makes the
  41     technique described below redundant. The following is a discussion
  42     on how to use non-QGL widgets in overlay planes.
  43
  44     In the typical case, X11 overlays can easily be used together with the
  45     current version of Qt and the Qt OpenGL Extension. The following
  46     requirements apply:
  47
  48     \list 1
  49     \i Your X server and graphics card/hardware must support overlays.
  50        For many X servers, overlay support can be turned on with
  51        a configuration option; consult your X server installation
  52        documentation.
  53
  54     \i Your X server must (be configured to) use an overlay visual as the
  55        default visual. Most modern X servers do this, since this has the
  56        added advantage that pop-up menus, overlapping windows etc., will
  57        \e not affect underlying images in the main plane, thereby
  58        avoiding expensive redraws.
  59
  60     \i The best (deepest) visual for OpenGL rendering is in the main
  61        plane. This is the normal case. Typically, X servers that support
  62        overlays provide a 24-bit \c TrueColor visual in the main plane,
  63        and an 8-bit \c PseudoColor (default) visual in the overlay plane.
  64     \endlist
  65
  66     Assuming that the requirements mentioned above are met, a
  67     QGLWidget will default to using the main plane visual, while all
  68     other widgets will use the overlay visual. Thus, we can place a
  69     normal widget on top of the QGLWidget, and do drawing on it,
  70     without affecting the image in the OpenGL window. In other words,
  71     we can use all the drawing capabilities of QPainter to draw
  72     annotations, rubberbands, etc. For the typical use of overlays,
  73     this is much easier than using OpenGL for rendering annotations.
  74
  75     An overlay plane has a specific color called the transparent
  76     color. Pixels drawn in this color will not be visible; instead
  77     the underlying OpenGL image will show through.
  78
  79     To use this technique, you must not use the
  80     QApplication::ManyColor or QApplication::TrueColor color
  81     specification for QApplication, because this will force the
  82     normal Qt widgets to use a \c TrueColor visual, which will
  83     typically be in the main plane, not in the overlay plane as
  84     desired.
  85 */