libQGLViewer - Introduction

Philosophy

libQGLViewer provides 3D application developers some of the classical features of a 3D viewer (see the feature list). Most of the functionalities of the viewer are illustrated by a very simple example which can be used as a cut and paste source for your own applications.

libQGLViewer enables you to quickly develop a small test program as well as a complete 3D application. It is versatile and is not designed for any specific application. It it also very convenient as a 3D/OpenGL pedagogical tool.

The QGLViewer class

The core of the library is the QGLViewer class, which opens an OpenGL window with your 3D geometry inside, and lets you move the camera using the mouse. QGLViewer actually inherits from the Qt's QOpenGLWidget class (use Qt's assistant to see its documentation).

A very simple application will look like simpleViewer. In your header file, you declare a new Viewer class which publicly inherits from QGLViewer and you overload the draw() method:

class Viewer : public QGLViewer
{
protected :
  virtual void draw();
};

and here is the implementation:

#include "viewer.h"

void Viewer::draw()
{
  // Your OpenGL 3D code goes here.
  // It consists in geometry description using glBegin() ... glEnd() blocks.
  // Camera's GL_MODELVIEW and GL_PROJECTION matrices are handled by the QGLViewer.
}

All you need now is a main function, where you create a Viewer instance. Most main function are identical: simply copy and paste from the simpleViewer example.

An other useful method that can be overloaded is init(), which is called once before the first display. This is where your OpenGL initialization code goes (camera placement, scene initialization, display lists creation...).

libQGLViewer also provides useful tools (a Camera class, key frame interpolation, manipulated frames...) that simplify the implementation of your viewer's specific features. See the complete documentation for details.

Your viewer can also be embedded in a Qt interface, using other Qt widgets to create a complete multi-platform application. Instead of deriving from QGLViewer, you can also use the Qt signal-slot mechanism and connect your drawing method to the signals emitted by an instance of QGLViewer. See the callback example for details.

Camera and world coordinate system

When you start giving OpenGL orders in your draw() function, you are implicitly located at the origin of the so-called world coordinate system.

In libQGLViewer, the Camera is an "object" located in this virtual world, that displays it and that can be moved with the mouse. Press 'A' to draw the axis of this world coordinate system. This approach is different (but much more intuitive) from the original camera-centered OpenGL coordinate system.

Scene radius and center

A QGLViewer has no knowledge of the 3D scene it displays. However, you need to provide an estimation of your scene radius (expressed in OpenGL units) in order to optimally set the near and far clipping planes of the camera and to be able to showEntireScene(). This is done using the setSceneRadius() function (default value is 1.0).

You may also want to tune the scene center if your scene is not centered on the world coordinate origin (0,0,0).

Use code like this in your init() function to define your scene dimensions:

setSceneRadius(100.0);          // scene has a 100 OpenGL units radius 
setSceneCenter( Vec(400,0,0) ); // with a center shifted by 400 units along X direction
camera()->showEntireScene();

Last modified on Thursday, December 29, 2022.