BSGUI.dox

//==============================================================================
//!
//! \file BSGUI.dox
//!
//! \date July 2014
//!
//! \author Eivind Fonn / SINTEF
//!
//! \brief File containing the main page of the BSGUI documentation.
//!
//==============================================================================

/*! 

\mainpage (Another) GUI for GoTools splines

\author Eivind Fonn, Sintef ICT, Trondheim

\section intro Introduction

This project is an attempted improvement on the Spline GUI tool ("Fenris") originally 
written by Kjetil Johannessen. The following shortcomings in Fenris serve as motivation.

- Fenris uses the old fixed function pipeline of OpenGL. This is fine for small models,
  but prohibitively slow for larger ones. BSGUI will use the programmable OpenGL
  pipeline.
- Fenris uses GLUT, a very limited OpenGL windowing system. To enable more sophisticated
  interaction, BSGUI will use Qt, a well-supported and popular GUI toolkit.
- Fenris has poor or non-existent support for persistent sessions. It can only parse
  files and display their contents, it cannot wait for updates and refresh automatically.
  BSGUI will support this workflow.
- Loading large models is time consuming. BSGUI will support multithreaded loading
  without sacrificing application responsiveness more than necessary.

Beyond this, the intended role is the same as for Fenris: spline object visualization
and very basic manipulation.

\section overview Overview

The code is heavily integrated with Qt.

The MainWindow class subclasses QMainWindow and contains three primary widgets: a
GLWidget object (subclasss of QGLWidget), a ToolBox object (subclass of
QDockWidget) and an InfoBox object (subclass of QWidget). The GLWidget owns
most of the screen space and is used for rendering. The toolbox is intended for
interactive widgets, and the infobox for information display.

In addition, there is an ObjectSet object created. This object maintains ownership
of all the open spline objects. It is a subclass of QAbstractItemModel, which allows
the QTreeView widget in the toolbox to display the state of the application.

The ObjectSet is responsible for creating, updating and destroying objects. It emits
signals to which the GLWidget and the toolbox and infobox widgets should listen.

Some important mutexes:

- GLWidget::m should be locked when any context-sensitive OpenGL functions are used.
  In particular this means during GLWidget::initializeGL, GLWidget::resizeGL,
  GLWidget::paintGL, GLWidget::paintGLPicks and GLWidget::initializeDispObject.
- DisplayObject::m is a static mutex which should be locked whenever code needs to
  interact with the static index of display objects. This is required whenever objects
  are created or destroyed, whenever selections are manipulated, or whenever anything
  loops over all objects (such as during drawing).
- ObjectSet::m should be locked whenever something manipulates the internal tree
  representation kept by this object. This should not be necessary outside of the
  ObjectSet itself.
- ObjectSet::mQueue should be locked whenever a thread manipulates the file loading
  queue.
- Each File object also has a lock, but it's not currently useful.

\section controls Controls

Keyboard controls:

- 1-6: Set a fixed preset orthographic camera (top, bottom, left, right, front, back).
- \`: Set a free camera.
- A: Toggle drawing of the axes cross.
- P: Switch between perspective and orthographic projections.
- C: Center the camera on the selected patch, or the whole scene.

In free mode:

- Right mouse button + drag: Rotate.
- Ctrl + right mouse button + drag: Pan (orthogonal to the camera axis).
- Scroll wheel: zoom physically (in perspective mode) or optically (in orthographic mode).
- Ctrl + scroll wheel: zoom optically (in perspective mode).

By physical zoom we mean a genuine movement of the camera. It is possible to occlude and
move behind objects using physical zoom. By optical zoom we mean a wider or narrower
field of view. This zoom mode cannot move behind objects.

Physical zoom is disabled in orthographic mode.

When switching between projections, the application will attempt to maintain a roughly
equal view area. This is sometimes not possible. Use the sliders in the camera panel
to reset the view if necessary.

In fixed mode:

- Right mouse button + drag: Pan.
- Ctrl + right mouse button + drag: Roll.
- Scroll wheel: zoom optically.

In fixed mode, the azimuth and inclination are locked.

For all mouse controls, hold shift to get finer control.

The camera look-at point is persistent throughout. If you move in fixed mode, you will
also have moved the camera in free mode. Except for this, the free mode camera state
will be saved.

\section selection Selection

There are four selection modes: patches, faces, edges and vertices. You can switch between
them using Ctrl+P, Ctrl+F, Ctrl+E and Ctrl+V.

In patch selection mode, each patch is either fully selected or fully unselected. In the other
modes, a patch may also be partially selected.

If you switch selection mode while a selection is active, the "expected" thing happens, for
certain values of "expected".

Press S to show and H to hide the current selection. Selection does not depend on visibility!
In particular, if you hide selected patches, they remain selected. You can see which objects
are selected in the treeview. Press escape to clear the selection.

For convenience, Ctrl+S and Ctrl+H will show or hide full patches. This has the same effect
as switching to patch selection mode and then clicking S or H.

In all cases, Ctrl+Shift+S will show all patches, selected or not.

\section requirements Library requirements

- Qt 5
- OpenGL

The developer uses rather cutting-edge libraries, but one may hope the implementation
still works with older ones.

*/