Home Documentation Download Examples Developer

# 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 `QGLWidget` 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 Sunday, February 28, 2010.