doc/src/qtopengl.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \module QtOpenGL
  44     \title QtOpenGL Module
  45     \contentspage Qt's Modules
  46     \previouspage QtNetwork
  47     \nextpage QtSql
  48     \ingroup modules
  49
  50     \brief The QtOpenGL module offers classes that make it easy to
  51     use OpenGL in Qt applications.
  52
  53     OpenGL is a standard API for rendering 3D graphics. OpenGL only
  54     deals with 3D rendering and provides little or no support for GUI
  55     programming issues. The user interface for an OpenGL application
  56     must be created with another toolkit, such as Motif on the X
  57     platform, Microsoft Foundation Classes (MFC) under Windows, or Qt
  58     on both platforms.
  59
  60     \bold{Note:} OpenGL is a trademark of Silicon Graphics, Inc. in
  61     the United States and other countries.
  62
  63     The Qt OpenGL module makes it easy to use OpenGL in Qt applications.
  64     It provides an OpenGL widget class that can be used just like any
  65     other Qt widget, except that it opens an OpenGL display buffer where
  66     you can use the OpenGL API to render the contents.
  67
  68     To include the definitions of the module's classes, use the
  69     following directive:
  70
  71     \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 0
  72
  73     To link against the module, add this line to your \l qmake \c
  74     .pro file:
  75
  76     \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 1
  77
  78     The Qt OpenGL module is implemented as a platform-independent Qt/C++
  79     wrapper around the platform-dependent GLX (version 1.3 or later),
  80     WGL, or AGL C APIs. Although the basic functionality provided is very
  81     similar to Mark Kilgard's GLUT library, applications using the Qt
  82     OpenGL module can take advantage of the whole Qt API for
  83     non-OpenGL-specific GUI functionality.
  84
  85     \warning The QtOpenGL module is part of the \l{Qt Full Framework Edition}
  86     and the \l{Open Source Versions of Qt}. It is available on Windows,
  87     X11, and Mac OS X. \l{Qt for Embedded Linux} supports OpenGL ES (OpenGL for
  88     Embedded Systems). To be able to use the OpenGL API in \l{Qt for Embedded Linux},
  89     it must be integrated with the Q Window System (QWS). See the
  90     \l{Qt for Embedded Linux and OpenGL} documentation for details.
  91
  92     \section1 Installation
  93
  94     When you install Qt for X11, the configure script will autodetect if
  95     OpenGL headers and libraries are installed on your system, and if so,
  96     it will include the QtOpenGL module in the Qt library. (If your
  97     OpenGL headers or libraries are placed in a non-standard directory,
  98     you may need to change the \c QMAKE_INCDIR_OPENGL and/or
  99     \c QMAKE_LIBDIR_OPENGL in the config file for your system).
 100
 101     When you install Qt for Windows and Mac OS X, the QtOpenGL
 102     module is always included. X11 users might like to read the notes
 103     on overlays below.
 104
 105     The QGL documentation assumes that you are familiar with OpenGL
 106     programming. If you're new to the subject a good starting point is
 107     \l{http://www.opengl.org/}.
 108
 109     \section1 How to Use X11 Overlays with Qt
 110
 111     X11 overlays are a powerful mechanism for drawing
 112     annotations etc., on top of an image without destroying it, thus saving
 113     a great deal of image rendering time. For more information, see the highly
 114     recommended book \e{OpenGL Programming for the X Window System} (Mark
 115     Kilgard, Addison Wesley Developers Press 1996).
 116
 117     \warning The Qt OpenGL Extension includes direct support for the
 118     use of OpenGL overlays. For many uses of overlays, this makes the
 119     technique described below redundant. The following is a discussion
 120     on how to use non-QGL widgets in overlay planes.
 121
 122     In the typical case, X11 overlays can easily be used together with the
 123     current version of Qt and the Qt OpenGL Extension. The following
 124     requirements apply:
 125
 126     \list 1
 127     \i Your X server and graphics card/hardware must support overlays.
 128        For many X servers, overlay support can be turned on with
 129        a configuration option; consult your X server installation
 130        documentation.
 131
 132     \i Your X server must (be configured to) use an overlay visual as the
 133        default visual. Most modern X servers do this, since this has the
 134        added advantage that pop-up menus, overlapping windows etc., will
 135        \e not affect underlying images in the main plane, thereby
 136        avoiding expensive redraws.
 137
 138     \i The best (deepest) visual for OpenGL rendering is in the main
 139        plane. This is the normal case. Typically, X servers that support
 140        overlays provide a 24-bit \c TrueColor visual in the main plane,
 141        and an 8-bit \c PseudoColor (default) visual in the overlay plane.
 142     \endlist
 143
 144     Assuming that the requirements mentioned above are met, a
 145     QGLWidget will default to using the main plane visual, while all
 146     other widgets will use the overlay visual. Thus, we can place a
 147     normal widget on top of the QGLWidget, and do drawing on it,
 148     without affecting the image in the OpenGL window. In other words,
 149     we can use all the drawing capabilities of QPainter to draw
 150     annotations, rubberbands, etc. For the typical use of overlays,
 151     this is much easier than using OpenGL for rendering annotations.
 152
 153     An overlay plane has a specific color called the transparent
 154     color. Pixels drawn in this color will not be visible; instead
 155     the underlying OpenGL image will show through.
 156
 157     To use this technique, you must not use the
 158     QApplication::ManyColor or QApplication::TrueColor color
 159     specification for QApplication, because this will force the
 160     normal Qt widgets to use a \c TrueColor visual, which will
 161     typically be in the main plane, not in the overlay plane as
 162     desired.
 163 */