summaryrefslogtreecommitdiffstats
path: root/doc/src/qtopengl.qdoc
diff options
context:
space:
mode:
authorLars Knoll <lars.knoll@nokia.com>2009-03-23 09:18:55 (GMT)
committerSimon Hausmann <simon.hausmann@nokia.com>2009-03-23 09:18:55 (GMT)
commite5fcad302d86d316390c6b0f62759a067313e8a9 (patch)
treec2afbf6f1066b6ce261f14341cf6d310e5595bc1 /doc/src/qtopengl.qdoc
downloadQt-e5fcad302d86d316390c6b0f62759a067313e8a9.zip
Qt-e5fcad302d86d316390c6b0f62759a067313e8a9.tar.gz
Qt-e5fcad302d86d316390c6b0f62759a067313e8a9.tar.bz2
Long live Qt 4.5!
Diffstat (limited to 'doc/src/qtopengl.qdoc')
-rw-r--r--doc/src/qtopengl.qdoc163
1 files changed, 163 insertions, 0 deletions
diff --git a/doc/src/qtopengl.qdoc b/doc/src/qtopengl.qdoc
new file mode 100644
index 0000000..1052f14
--- /dev/null
+++ b/doc/src/qtopengl.qdoc
@@ -0,0 +1,163 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, 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 are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \module QtOpenGL
+ \title QtOpenGL Module
+ \contentspage Qt's Modules
+ \previouspage QtNetwork
+ \nextpage QtSql
+ \ingroup modules
+
+ \brief The QtOpenGL module offers classes that make it easy to
+ use OpenGL in Qt applications.
+
+ OpenGL is a standard API for rendering 3D graphics. OpenGL only
+ deals with 3D rendering and provides little or no support for GUI
+ programming issues. The user interface for an OpenGL application
+ must be created with another toolkit, such as Motif on the X
+ platform, Microsoft Foundation Classes (MFC) under Windows, or Qt
+ on both platforms.
+
+ \bold{Note:} OpenGL is a trademark of Silicon Graphics, Inc. in
+ the United States and other countries.
+
+ The Qt OpenGL module makes it easy to use OpenGL in Qt applications.
+ It provides an OpenGL widget class that can be used just like any
+ other Qt widget, except that it opens an OpenGL display buffer where
+ you can use the OpenGL API to render the contents.
+
+ To include the definitions of the module's classes, use the
+ following directive:
+
+ \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 0
+
+ To link against the module, add this line to your \l qmake \c
+ .pro file:
+
+ \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 1
+
+ The Qt OpenGL module is implemented as a platform-independent Qt/C++
+ wrapper around the platform-dependent GLX (version 1.3 or later),
+ WGL, or AGL C APIs. Although the basic functionality provided is very
+ similar to Mark Kilgard's GLUT library, applications using the Qt
+ OpenGL module can take advantage of the whole Qt API for
+ non-OpenGL-specific GUI functionality.
+
+ \warning The QtOpenGL module is part of the \l{Qt Full Framework Edition}
+ and the \l{Open Source Versions of Qt}. It is available on Windows,
+ X11, and Mac OS X. \l{Qt for Embedded Linux} supports OpenGL ES (OpenGL for
+ Embedded Systems). To be able to use the OpenGL API in \l{Qt for Embedded Linux},
+ it must be integrated with the Q Window System (QWS). See the
+ \l{Qt for Embedded Linux and OpenGL} documentation for details.
+
+ \section1 Installation
+
+ When you install Qt for X11, the configure script will autodetect if
+ OpenGL headers and libraries are installed on your system, and if so,
+ it will include the QtOpenGL module in the Qt library. (If your
+ OpenGL headers or libraries are placed in a non-standard directory,
+ you may need to change the \c QMAKE_INCDIR_OPENGL and/or
+ \c QMAKE_LIBDIR_OPENGL in the config file for your system).
+
+ When you install Qt for Windows and Mac OS X, the QtOpenGL
+ module is always included. X11 users might like to read the notes
+ on overlays below.
+
+ The QGL documentation assumes that you are familiar with OpenGL
+ programming. If you're new to the subject a good starting point is
+ \l{http://www.opengl.org/}.
+
+ \section1 How to Use X11 Overlays with Qt
+
+ X11 overlays are a powerful mechanism for drawing
+ annotations etc., on top of an image without destroying it, thus saving
+ a great deal of image rendering time. For more information, see the highly
+ recommended book \e{OpenGL Programming for the X Window System} (Mark
+ Kilgard, Addison Wesley Developers Press 1996).
+
+ \warning The Qt OpenGL Extension includes direct support for the
+ use of OpenGL overlays. For many uses of overlays, this makes the
+ technique described below redundant. The following is a discussion
+ on how to use non-QGL widgets in overlay planes.
+
+ In the typical case, X11 overlays can easily be used together with the
+ current version of Qt and the Qt OpenGL Extension. The following
+ requirements apply:
+
+ \list 1
+ \i Your X server and graphics card/hardware must support overlays.
+ For many X servers, overlay support can be turned on with
+ a configuration option; consult your X server installation
+ documentation.
+
+ \i Your X server must (be configured to) use an overlay visual as the
+ default visual. Most modern X servers do this, since this has the
+ added advantage that pop-up menus, overlapping windows etc., will
+ \e not affect underlying images in the main plane, thereby
+ avoiding expensive redraws.
+
+ \i The best (deepest) visual for OpenGL rendering is in the main
+ plane. This is the normal case. Typically, X servers that support
+ overlays provide a 24-bit \c TrueColor visual in the main plane,
+ and an 8-bit \c PseudoColor (default) visual in the overlay plane.
+ \endlist
+
+ Assuming that the requirements mentioned above are met, a
+ QGLWidget will default to using the main plane visual, while all
+ other widgets will use the overlay visual. Thus, we can place a
+ normal widget on top of the QGLWidget, and do drawing on it,
+ without affecting the image in the OpenGL window. In other words,
+ we can use all the drawing capabilities of QPainter to draw
+ annotations, rubberbands, etc. For the typical use of overlays,
+ this is much easier than using OpenGL for rendering annotations.
+
+ An overlay plane has a specific color called the transparent
+ color. Pixels drawn in this color will not be visible; instead
+ the underlying OpenGL image will show through.
+
+ To use this technique, you must not use the
+ QApplication::ManyColor or QApplication::TrueColor color
+ specification for QApplication, because this will force the
+ normal Qt widgets to use a \c TrueColor visual, which will
+ typically be in the main plane, not in the overlay plane as
+ desired.
+*/