You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
133 lines
5.7 KiB
133 lines
5.7 KiB
13 years ago
|
/****************************************************************************
|
||
|
|
**
|
||
|
|
** ...
|
||
|
|
**
|
||
|
|
** Copyright (C) 2005-2008 Trolltech ASA. All rights reserved.
|
||
|
|
**
|
||
|
|
** This file is part of the Qt GUI Toolkit.
|
||
|
|
**
|
||
|
|
** This file may be used under the terms of the GNU General
|
||
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
||
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
||
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
||
|
|
** Alternatively you may (at your option) use any later version
|
||
|
|
** of the GNU General Public License if such license has been
|
||
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
||
|
|
** and the KDE Free Qt Foundation.
|
||
|
|
**
|
||
|
|
** Please review the following information to ensure GNU General
|
||
|
|
** Public Licensing retquirements will be met:
|
||
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
||
|
|
** If you are unsure which license is appropriate for your use, please
|
||
|
|
** review the following information:
|
||
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
||
|
|
** or contact the sales department at sales@trolltech.com.
|
||
|
|
**
|
||
|
|
** This file may be used under the terms of the Q Public License as
|
||
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
||
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
||
|
|
** Commercial licenses may use this file in accordance with the Qt
|
||
|
|
** Commercial License Agreement provided with the Software.
|
||
|
|
**
|
||
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
||
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
||
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
||
|
|
** herein.
|
||
|
|
**
|
||
|
|
**********************************************************************/
|
||
|
|
|
||
|
|
/*!
|
||
|
|
\page opengl-x11-overlays.html
|
||
|
|
|
||
|
|
\title How to use X11 overlays with the Qt OpenGL extension
|
||
|
|
|
||
|
|
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, consult the highly
|
||
|
|
recommended book \e{OpenGL Programming for the X Window System} (Mark
|
||
|
|
Kilgard, Addison Wesley Developers Press 1996).
|
||
|
|
|
||
|
|
\warning From version 5.0 onwards, 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. See the
|
||
|
|
\link opengl-overlay-example.html overlay\endlink example program. 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
|
||
|
|
retquirements 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 destroy 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 deep TrueColor visual in the main plane,
|
||
|
|
and an 8 bit PseudoColor (default) visual in the overlay plane.
|
||
|
|
\endlist
|
||
|
|
|
||
|
|
The provided example program \link opengl-overlay-example.html X11
|
||
|
|
overlay\endlink will check for these and report if anything is wrong.
|
||
|
|
See \link #x11visuals About X11 Visuals\endlink, below for more
|
||
|
|
information.
|
||
|
|
|
||
|
|
|
||
|
|
\section1 How it works
|
||
|
|
|
||
|
|
Given the above, a QGLWidget will by default use 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 destroying the image in the OpenGL window. In other words,
|
||
|
|
we can use all the drawing capabilities of QPainter to draw the
|
||
|
|
annotations, rubberbands, etc. For the typical use of overlays,
|
||
|
|
this is much easier than using OpenGL for rendering the 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. In the example program
|
||
|
|
\link opengl-overlay-example.html X11 overlay\endlink, the file
|
||
|
|
\c main.cpp contains a routine that returns a QColor containing the
|
||
|
|
transparent color. For the overlay widget, you will typically want to
|
||
|
|
set the background color to the transparent color, so that the OpenGL
|
||
|
|
image shows through except where explicitly overpainted.
|
||
|
|
|
||
|
|
Note: to use this technique, you must not use the "ManyColor" or
|
||
|
|
"TrueColor" ColorSpec for QApplication, because this will force
|
||
|
|
the normal Qt widgets to use a TrueColor visual, which will typically
|
||
|
|
be in the main plane, not in the overlay plane as desired.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
\target x11visuals
|
||
|
|
\section1 About X11 visuals
|
||
|
|
|
||
|
|
The utilities directory contains two small programs that can help you
|
||
|
|
determine the capabilities of your X server. These programs are from
|
||
|
|
the OpenGL book mentioned above, see utilities/NOTICE for copyright
|
||
|
|
information. The full set of example programs from this book is
|
||
|
|
available at \l{ftp://ftp.sgi.com/pub/opengl/opengl_for_x/}.
|
||
|
|
|
||
|
|
\c glxvisuals will list all the GL-capable visuals the X server
|
||
|
|
provides, together with the depth and other GL-specific information
|
||
|
|
for each. Note especially the column "lvl"; a number in this column
|
||
|
|
means the visual is in an overlay plane.
|
||
|
|
|
||
|
|
\c sovinfo will list all available visuals, and provides special
|
||
|
|
transparency information for overlay visuals.
|
||
|
|
|
||
|
|
The \link opengl-overlay-example.html X11 overlay\endlink example
|
||
|
|
program will output what visual is used for the normal Qt widgets, and
|
||
|
|
what visual is used by the QGLWidget.
|
||
|
|
|
||
|
|
*/
|