From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qglwidget.html | 583 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 583 insertions(+) create mode 100644 doc/html/qglwidget.html (limited to 'doc/html/qglwidget.html') diff --git a/doc/html/qglwidget.html b/doc/html/qglwidget.html new file mode 100644 index 000000000..a9fa0e7e5 --- /dev/null +++ b/doc/html/qglwidget.html @@ -0,0 +1,583 @@ + + + + + +TQGLWidget Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQGLWidget Class Reference
[OpenGL module]

+ +

The TQGLWidget class is a widget for rendering OpenGL graphics. +More... +

#include <qgl.h> +

Inherits TQWidget and TQGL. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Static Public Members

+ +

Protected Members

+ +

Detailed Description

+ + +The TQGLWidget class is a widget for rendering OpenGL graphics. + +

+ + + +

TQGLWidget provides functionality for displaying OpenGL* +graphics integrated into a TQt application. It is very simple to +use. You inherit from it and use the subclass like any other +TQWidget, except that instead of drawing the widget's contents +using TQPainter etc. you use the standard OpenGL rendering +commands. +

TQGLWidget provides three convenient virtual functions that you can +reimplement in your subclass to perform the typical OpenGL tasks: +

+

Here is a rough outline of how a TQGLWidget subclass might look: +

+    class MyGLDrawer : public TQGLWidget
+    {
+        Q_OBJECT        // must include this if you use TQt signals/slots
+
+    public:
+        MyGLDrawer( TQWidget *parent, const char *name )
+            : TQGLWidget(parent, name) {}
+
+    protected:
+
+        void initializeGL()
+        {
+            // Set up the rendering context, define display lists etc.:
+            ...
+            glClearColor( 0.0, 0.0, 0.0, 0.0 );
+            glEnable(GL_DEPTH_TEST);
+            ...
+        }
+
+        void resizeGL( int w, int h )
+        {
+            // setup viewport, projection etc.:
+            glViewport( 0, 0, (GLint)w, (GLint)h );
+            ...
+            glFrustum( ... );
+            ...
+        }
+
+        void paintGL()
+        {
+            // draw the scene:
+            ...
+            glRotatef( ... );
+            glMaterialfv( ... );
+            glBegin( GL_QUADS );
+            glVertex3f( ... );
+            glVertex3f( ... );
+            ...
+            glEnd();
+            ...
+        }
+
+    };
+
+ +

If you need to trigger a repaint from places other than paintGL() +(a typical example is when using timers to +animate scenes), you should call the widget's updateGL() function. +

Your widget's OpenGL rendering context is made current when +paintGL(), resizeGL(), or initializeGL() is called. If you need to +call the standard OpenGL API functions from other places (e.g. in +your widget's constructor or in your own paint functions), you +must call makeCurrent() first. +

TQGLWidget provides functions for requesting a new display format and you can also create widgets with +customized rendering contexts. +

You can also share OpenGL display lists between TQGLWidgets (see +the documentation of the TQGLWidget constructors for details). +

Overlays +

+

The TQGLWidget creates a GL overlay context in addition to the +normal context if overlays are supported by the underlying system. +

If you want to use overlays, you specify it in the format. (Note: Overlay must be requested in the format +passed to the TQGLWidget constructor.) Your GL widget should also +implement some or all of these virtual methods: +

+

These methods work in the same way as the normal paintGL() etc. +functions, except that they will be called when the overlay +context is made current. You can explicitly make the overlay +context current by using makeOverlayCurrent(), and you can access +the overlay context directly (e.g. to ask for its transparent +color) by calling overlayContext(). +

On X servers in which the default visual is in an overlay plane, +non-GL TQt windows can also be used for overlays. See the +examples/opengl/overlay_x11 example program for details. +

* OpenGL is a trademark of Silicon Graphics, Inc. in the +United States and other countries. +

See also Graphics Classes and Image Processing Classes. + +

Member Function Documentation

+

TQGLWidget::TQGLWidget ( TQWidget * parent = 0, const char * name = 0, const TQGLWidget * shareWidget = 0, WFlags f = 0 ) +

+Constructs an OpenGL widget with a parent widget and a name. +

The default format is +used. The widget will be invalid if the +system has no OpenGL support. +

The parent, name and widget flag, f, arguments are passed +to the TQWidget constructor. +

If the shareWidget parameter points to a valid TQGLWidget, this +widget will share OpenGL display lists with shareWidget. If +this widget and shareWidget have different formats, display list sharing may fail. You can check +whether display list sharing succeeded by calling isSharing(). +

The initialization of OpenGL rendering state, etc. should be done +by overriding the initializeGL() function, rather than in the +constructor of your TQGLWidget subclass. +

See also TQGLFormat::defaultFormat(). + +

TQGLWidget::TQGLWidget ( TQGLContext * context, TQWidget * parent, const char * name = 0, const TQGLWidget * shareWidget = 0, WFlags f = 0 ) +

+Constructs an OpenGL widget with parent parent, called name. +

The context argument is a pointer to the TQGLContext that +you wish to be bound to this widget. This allows you to pass in +your own TQGLContext sub-classes. +

The widget will be invalid if the system +has no OpenGL support. +

The parent, name and widget flag, f, arguments are passed +to the TQWidget constructor. +

If the shareWidget parameter points to a valid TQGLWidget, this +widget will share OpenGL display lists with shareWidget. If +this widget and shareWidget have different formats, display list sharing may fail. You can check +whether display list sharing succeeded by calling isSharing(). +

The initialization of OpenGL rendering state, etc. should be done +by overriding the initializeGL() function, rather than in the +constructor of your TQGLWidget subclass. +

See also TQGLFormat::defaultFormat() and isValid(). + +

TQGLWidget::TQGLWidget ( const TQGLFormat & format, TQWidget * parent = 0, const char * name = 0, const TQGLWidget * shareWidget = 0, WFlags f = 0 ) +

+Constructs an OpenGL widget with parent parent, called name. +

The format argument specifies the desired rendering options. If the underlying OpenGL/Window system +cannot satisfy all the features requested in format, the +nearest subset of features will be used. After creation, the +format() method will return the actual format obtained. +

The widget will be invalid if the system +has no OpenGL support. +

The parent, name and widget flag, f, arguments are passed +to the TQWidget constructor. +

If the shareWidget parameter points to a valid TQGLWidget, this +widget will share OpenGL display lists with shareWidget. If +this widget and shareWidget have different formats, display list sharing may fail. You can check +whether display list sharing succeeded by calling isSharing(). +

The initialization of OpenGL rendering state, etc. should be done +by overriding the initializeGL() function, rather than in the +constructor of your TQGLWidget subclass. +

See also TQGLFormat::defaultFormat() and isValid(). + +

TQGLWidget::~TQGLWidget () +

+Destroys the widget. + +

bool TQGLWidget::autoBufferSwap () const [protected] +

+ +

Returns TRUE if the widget is doing automatic GL buffer swapping; +otherwise returns FALSE. +

See also setAutoBufferSwap(). + +

const TQGLColormap & TQGLWidget::colormap () const +

+ +

Returns the colormap for this widget. +

Usually it is only top-level widgets that can have different +colormaps installed. Asking for the colormap of a child widget +will return the colormap for the child's top-level widget. +

If no colormap has been set for this widget, the TQColormap +returned will be empty. +

See also setColormap(). + +

const TQGLContext * TQGLWidget::context () const +

+ +

Returns the context of this widget. +

It is possible that the context is not valid (see isValid()), for +example, if the underlying hardware does not support the format +attributes that were requested. + +

TQImage TQGLWidget::convertToGLFormat ( const TQImage & img ) [static] +

+Converts the image img into the unnamed format expected by +OpenGL functions such as glTexImage2D(). The returned image is not +usable as a TQImage, but TQImage::width(), TQImage::height() and +TQImage::bits() may be used with OpenGL. The following few lines +are from the texture example. Most of the code is irrelevant, so +we just quote the relevant bits: +

+ +

        TQImage tex1, tex2, buf;
+        if ( !buf.load( "gllogo.bmp" ) ) {  // Load first image from file
+
+

We create tex1 (and another variable) for OpenGL, and load a real +image into buf. +

        tex1 = TQGLWidget::convertToGLFormat( buf );  // flipped 32bit RGBA
+
+

A few lines later, we convert buf into OpenGL format and store it +in tex1. +

        glTexImage2D( GL_TEXTURE_2D, 0, 3, tex1.width(), tex1.height(), 0,
+                      GL_RGBA, GL_UNSIGNED_BYTE, tex1.bits() );
+
+

Note the dimension restrictions for texture images as described in +the glTexImage2D() documentation. The width must be 2^m + 2*border +and the height 2^n + 2*border where m and n are integers and +border is either 0 or 1. +

Another function in the same example uses tex1 with OpenGL. + +

Example: opengl/texture/gltexobj.cpp. +

void TQGLWidget::doneCurrent () +

+ +

Makes no GL context the current context. Normally, you do not need +to call this function; TQGLContext calls it as necessary. However, +it may be useful in multithreaded environments. + +

bool TQGLWidget::doubleBuffer () const +

+ +

Returns TRUE if the contained GL rendering context has double +buffering; otherwise returns FALSE. +

See also TQGLFormat::doubleBuffer(). + +

TQGLFormat TQGLWidget::format () const +

+ +

Returns the format of the contained GL rendering context. + +

void TQGLWidget::glDraw () [virtual protected] +

+Executes the virtual function paintGL(). +

The widget's rendering context will become the current context and +initializeGL() will be called if it hasn't already been called. + +

void TQGLWidget::glInit () [virtual protected] +

+Initializes OpenGL for this widget's context. Calls the virtual +function initializeGL(). + +

TQImage TQGLWidget::grabFrameBuffer ( bool withAlpha = FALSE ) [virtual] +

+Returns an image of the frame buffer. If withAlpha is TRUE the +alpha channel is included. +

Depending on your hardware, you can explicitly select which color +buffer to grab with a glReadBuffer() call before calling this +function. + +

void TQGLWidget::initializeGL () [virtual protected] +

+This virtual function is called once before the first call to +paintGL() or resizeGL(), and then once whenever the widget has +been assigned a new TQGLContext. Reimplement it in a subclass. +

This function should set up any retquired OpenGL context rendering +flags, defining display lists, etc. +

There is no need to call makeCurrent() because this has already +been done when this function is called. + +

void TQGLWidget::initializeOverlayGL () [virtual protected] +

+This virtual function is used in the same manner as initializeGL() +except that it operates on the widget's overlay context instead of +the widget's main context. This means that initializeOverlayGL() +is called once before the first call to paintOverlayGL() or +resizeOverlayGL(). Reimplement it in a subclass. +

This function should set up any retquired OpenGL context rendering +flags, defining display lists, etc. for the overlay context. +

There is no need to call makeOverlayCurrent() because this has +already been done when this function is called. + +

bool TQGLWidget::isSharing () const +

+ +

Returns TRUE if display list sharing with another TQGLWidget was +requested in the constructor, and the GL system was able to +provide it; otherwise returns FALSE. The GL system may fail to +provide display list sharing if the two TQGLWidgets use different +formats. +

See also format(). + +

bool TQGLWidget::isValid () const +

+ +

Returns TRUE if the widget has a valid GL rendering context; +otherwise returns FALSE. A widget will be invalid if the system +has no OpenGL support. + +

void TQGLWidget::makeCurrent () [virtual] +

+ +

Makes this widget the current widget for OpenGL operations, i.e. +makes the widget's rendering context the current OpenGL rendering +context. + +

void TQGLWidget::makeOverlayCurrent () [virtual] +

+ +

Makes the overlay context of this widget current. Use this if you +need to issue OpenGL commands to the overlay context outside of +initializeOverlayGL(), resizeOverlayGL(), and paintOverlayGL(). +

Does nothing if this widget has no overlay. +

See also makeCurrent(). + +

const TQGLContext * TQGLWidget::overlayContext () const +

+ +

Returns the overlay context of this widget, or 0 if this widget +has no overlay. +

See also context(). + +

void TQGLWidget::paintEvent ( TQPaintEvent * ) [virtual protected] +

+Handles paint events. Will cause the virtual paintGL() function to +be called. +

The widget's rendering context will become the current context and +initializeGL() will be called if it hasn't already been called. + +

Reimplemented from TQWidget. +

void TQGLWidget::paintGL () [virtual protected] +

+This virtual function is called whenever the widget needs to be +painted. Reimplement it in a subclass. +

There is no need to call makeCurrent() because this has already +been done when this function is called. + +

void TQGLWidget::paintOverlayGL () [virtual protected] +

+This virtual function is used in the same manner as paintGL() +except that it operates on the widget's overlay context instead of +the widget's main context. This means that paintOverlayGL() is +called whenever the widget's overlay needs to be painted. +Reimplement it in a subclass. +

There is no need to call makeOverlayCurrent() because this has +already been done when this function is called. + +

void TQGLWidget::qglClearColor ( const TQColor & c ) const +

+Convenience function for specifying the clearing color to OpenGL. +Calls glClearColor (in RGBA mode) or glClearIndex (in color-index +mode) with the color c. Applies to the current GL context. +

See also qglColor(), TQGLContext::currentContext(), and TQColor. + +

void TQGLWidget::qglColor ( const TQColor & c ) const +

+Convenience function for specifying a drawing color to OpenGL. +Calls glColor3 (in RGBA mode) or glIndex (in color-index mode) +with the color c. Applies to the current GL context. +

See also qglClearColor(), TQGLContext::currentContext(), and TQColor. + +

TQPixmap TQGLWidget::renderPixmap ( int w = 0, int h = 0, bool useContext = FALSE ) [virtual] +

+Renders the current scene on a pixmap and returns the pixmap. +

You can use this method on both visible and invisible TQGLWidgets. +

This method will create a pixmap and a temporary TQGLContext to +render on the pixmap. It will then call initializeGL(), +resizeGL(), and paintGL() on this context. Finally, the widget's +original GL context is restored. +

The size of the pixmap will be w pixels wide and h pixels +high unless one of these parameters is 0 (the default), in which +case the pixmap will have the same size as the widget. +

If useContext is TRUE, this method will try to be more +efficient by using the existing GL context to render the pixmap. +The default is FALSE. Only use TRUE if you understand the risks. +

Overlays are not rendered onto the pixmap. +

If the GL rendering context and the desktop have different bit +depths, the result will most likely look surprising. +

Note that the creation of display lists, modifications of the view +frustum etc. should be done from within initializeGL(). If this is +not done, the temporary TQGLContext will not be initialized +properly, and the rendered pixmap may be incomplete/corrupted. + +

void TQGLWidget::renderText ( int x, int y, const TQString & str, const TQFont & fnt = TQFont ( ), int listBase = 2000 ) +

+Renders the string str into the GL context of this widget. +

x and y are specified in window coordinates, with the origin +in the upper left-hand corner of the window. If fnt is not +specified, the currently set application font will be used to +render the string. To change the color of the rendered text you can +use the glColor() call (or the qglColor() convenience function), +just before the renderText() call. Note that if you have +GL_LIGHTING enabled, the string will not appear in the color you +want. You should therefore switch lighting off before using +renderText(). +

listBase specifies the index of the first display list that is +generated by this function. The default value is 2000. 256 display +lists will be generated, one for each of the first 256 characters +in the font that is used to render the string. If several fonts are +used in the same widget, the display lists for these fonts will +follow the last generated list. You would normally not have to +change this value unless you are using lists in the same range. The +lists are deleted when the widget is destroyed. +

Note: This function only works reliably with ASCII strings. + +

void TQGLWidget::renderText ( double x, double y, double z, const TQString & str, const TQFont & fnt = TQFont ( ), int listBase = 2000 ) +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

x, y and z are specified in scene or object coordinates +relative to the currently set projection and model matrices. This +can be useful if you want to annotate models with text labels and +have the labels move with the model as it is rotated etc. + +

void TQGLWidget::resizeEvent ( TQResizeEvent * ) [virtual protected] +

+ +

Handles resize events. Calls the virtual function resizeGL(). + +

Reimplemented from TQWidget. +

void TQGLWidget::resizeGL ( int width, int height ) [virtual protected] +

+ +

This virtual function is called whenever the widget has been +resized. The new size is passed in width and height. +Reimplement it in a subclass. +

There is no need to call makeCurrent() because this has already +been done when this function is called. + +

void TQGLWidget::resizeOverlayGL ( int width, int height ) [virtual protected] +

+ +

This virtual function is used in the same manner as paintGL() +except that it operates on the widget's overlay context instead of +the widget's main context. This means that resizeOverlayGL() is +called whenever the widget has been resized. The new size is +passed in width and height. Reimplement it in a subclass. +

There is no need to call makeOverlayCurrent() because this has +already been done when this function is called. + +

void TQGLWidget::setAutoBufferSwap ( bool on ) [protected] +

+ +

If on is TRUE automatic GL buffer swapping is switched on; +otherwise it is switched off. +

If on is TRUE and the widget is using a double-buffered format, +the background and foreground GL buffers will automatically be +swapped after each paintGL() call. +

The buffer auto-swapping is on by default. +

See also autoBufferSwap(), doubleBuffer(), and swapBuffers(). + +

void TQGLWidget::setColormap ( const TQGLColormap & cmap ) +

+ +

Set the colormap for this widget to cmap. Usually it is only +top-level widgets that can have colormaps installed. +

See also colormap(). + +

void TQGLWidget::swapBuffers () [virtual] +

+ +

Swaps the screen contents with an off-screen buffer. This only +works if the widget's format specifies double buffer mode. +

Normally, there is no need to explicitly call this function +because it is done automatically after each widget repaint, i.e. +each time after paintGL() has been executed. +

See also doubleBuffer(), setAutoBufferSwap(), and TQGLFormat::setDoubleBuffer(). + +

void TQGLWidget::updateGL () [virtual slot] +

+ +

Updates the widget by calling glDraw(). + +

void TQGLWidget::updateOverlayGL () [virtual slot] +

+ +

Updates the widget's overlay (if any). Will cause the virtual +function paintOverlayGL() to be executed. +

The widget's rendering context will become the current context and +initializeGL() will be called if it hasn't already been called. + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1