A versatile 3D OpenGL viewer based on QGLWidget. More...

Inheritance diagram for QGLViewer:

Signals
void	animateNeeded ()
	Signal emitted by the default animate() method.

void	axisIsDrawnChanged (bool drawn)
	This signal is emitted whenever axisIsDrawn() changes value.

void	cameraIsEditedChanged (bool edited)
	This signal is emitted whenever cameraIsEdited() changes value.

void	drawFinished (bool automatic)
	Signal emitted at the end of the QGLViewer::paintGL() method, when frame is drawn.

void	drawNeeded ()
	Signal emitted by the default draw() method.

void	FPSIsDisplayedChanged (bool displayed)
	This signal is emitted whenever FPSIsDisplayed() changes value.

void	gridIsDrawnChanged (bool drawn)
	This signal is emitted whenever gridIsDrawn() changes value.

void	helpRequired ()
	Signal emitted by the default QGLViewer::help() method.

void	mouseGrabberChanged (qglviewer::MouseGrabber *mouseGrabber)
	Signal emitted by setMouseGrabber() when the mouseGrabber() is changed.

void	pointSelected (const QMouseEvent *e)
	Signal emitted by select().

void	stereoChanged (bool on)
	This signal is emitted whenever displaysInStereo() changes value.

void	textIsEnabledChanged (bool enabled)
	This signal is emitted whenever textIsEnabled() changes value.

void	viewerInitialized ()
	Signal emitted by the default init() method.

Public Member Functions
	QGLViewer (QWidget parent=NULL, const char name=0, const QGLWidget *shareWidget=0, Qt::WFlags flags=0)

	QGLViewer (const QGLFormat &format, QWidget parent=0, const char name=0, const QGLWidget *shareWidget=0, Qt::WFlags flags=0)

	QGLViewer (QGLContext context, QWidget parent, const char name=0, const QGLWidget shareWidget=0, Qt::WFlags flags=0)

virtual	~QGLViewer ()
	Virtual destructor.

Display of visual hints
bool	axisIsDrawn () const
	Returns `true` if the world axis is drawn by the viewer.

bool	gridIsDrawn () const
	Returns `true` if a XY grid is drawn by the viewer.

bool	FPSIsDisplayed () const
	Returns `true` if the viewer displays the current frame rate (Frames Per Second).

bool	textIsEnabled () const
	Returns `true` if text display (see drawText()) is enabled.

bool	cameraIsEdited () const
	Returns `true` if the camera() is being edited in the viewer.

void	setAxisIsDrawn (bool draw=true)
	Sets the state of axisIsDrawn().

void	setGridIsDrawn (bool draw=true)
	Sets the state of gridIsDrawn().

void	setFPSIsDisplayed (bool display=true)
	Sets the state of FPSIsDisplayed().

void	setTextIsEnabled (bool enable=true)
	Sets the state of textIsEnabled().

void	setCameraIsEdited (bool edit=true)
	Starts (`edit` = `true`, default) or stops (`edit=false)` the edition of the camera().

void	toggleAxisIsDrawn ()
	Toggles the state of axisIsDrawn().

void	toggleGridIsDrawn ()
	Toggles the state of gridIsDrawn().

void	toggleFPSIsDisplayed ()
	Toggles the state of FPSIsDisplayed().

void	toggleTextIsEnabled ()
	Toggles the state of textIsEnabled().

void	toggleCameraIsEdited ()
	Toggles the state of cameraIsEdited().

Viewer's colors
QColor	backgroundColor () const
	Returns the background color of the viewer.

QColor	foregroundColor () const
	Returns the foreground color used by the viewer.

void	setBackgroundColor (const QColor &color)
	Sets the backgroundColor() of the viewer and calls `qglClearColor()`.

void	setForegroundColor (const QColor &color)
	Sets the foregroundColor() of the viewer, used to draw visual hints.

Scene dimensions
float	sceneRadius () const
	Returns the scene radius.

qglviewer::Vec	sceneCenter () const
	Returns the scene center, defined in world coordinates.

virtual void	setSceneRadius (float radius)
	Sets the sceneRadius().

virtual void	setSceneCenter (const qglviewer::Vec &center)
	Sets the sceneCenter(), defined in world coordinates.

void	setSceneBoundingBox (const qglviewer::Vec &min, const qglviewer::Vec &max)
	Convenient way to call setSceneCenter() and setSceneRadius() from a (world axis aligned) bounding box of the scene.

void	showEntireScene ()
	Moves the camera so that the entire scene is visible.

Associated objects
qglviewer::Camera *	camera () const
	Returns the associated qglviewer::Camera, never `NULL`.

qglviewer::ManipulatedFrame *	manipulatedFrame () const
	Returns the viewer's qglviewer::ManipulatedFrame.

void	setCamera (qglviewer::Camera *const camera)
	Associates a new qglviewer::Camera to the viewer.

void	setManipulatedFrame (qglviewer::ManipulatedFrame *frame)
	Sets the viewer's manipulatedFrame().

Mouse grabbers
qglviewer::MouseGrabber *	mouseGrabber () const
	Returns the current qglviewer::MouseGrabber, or `NULL` if no qglviewer::MouseGrabber currently grabs mouse events.

void	setMouseGrabberIsEnabled (const qglviewer::MouseGrabber *const mouseGrabber, bool enabled=true)
	Sets the mouseGrabberIsEnabled() state.

bool	mouseGrabberIsEnabled (const qglviewer::MouseGrabber *const mouseGrabber)
	Returns `true` if `mouseGrabber` is enabled.

void	setMouseGrabber (qglviewer::MouseGrabber *mouseGrabber)
	Directly defines the mouseGrabber().

State of the viewer
float	aspectRatio () const
	Returns the aspect ratio of the viewer's widget (width() / height()).

float	currentFPS ()
	Returns the current averaged viewer frame rate.

bool	isFullScreen () const
	Returns `true` if the viewer is in fullScreen mode.

bool	displaysInStereo () const
	Returns `true` if the viewer displays in stereo.

virtual QSize	sizeHint () const
	Returns the recommended size for the QGLViewer.

void	setFullScreen (bool fullScreen=true)
	Sets the isFullScreen() state.

void	setStereoDisplay (bool stereo=true)
	Sets the state of displaysInStereo().

void	toggleFullScreen ()
	Toggles the state of isFullScreen().

void	toggleStereoDisplay ()
	Toggles the state of displaysInStereo().

void	toggleCameraMode ()
	Swaps between two predefined camera mouse bindings.

Display methods
virtual void	startScreenCoordinatesSystem (bool upward=false) const
	Modify the projection matrix so that drawing can be done directly with 2D screen coordinates.

virtual void	stopScreenCoordinatesSystem () const
	Stops the pixel coordinate drawing block started by startScreenCoordinatesSystem().

void	drawText (int x, int y, const QString &text, const QFont &fnt=QFont())
	Draws `text` at position `x`, `y` (expressed in screen coordinates pixels, origin in the upper left corner of the widget).

void	displayMessage (const QString &message, int delay=2000)
	Briefly displays a message in the lower left corner of the widget.

static void	drawArrow (float length=1.0f, float radius=-1.0f, int nbSubdivisions=12)
	Draws a 3D arrow along the positive Z axis.

static void	drawArrow (const qglviewer::Vec &from, const qglviewer::Vec &to, float radius=-1.0f, int nbSubdivisions=12)
	Draws a 3D arrow between the 3D point `from` and the 3D point `to`, both defined in the current ModelView coordinates system.

static void	drawAxis (float length=1.0f)
	Draws an XYZ axis, with a given size (default is 1.0).

static void	drawGrid (float size=1.0f, int nbSubdivisions=10)
	Draws a grid in the XY plane, centered on (0,0,0) (defined in the current coordinate system).

virtual void	drawLight (GLenum light, float scale=1.0f) const
	Draws a representation of `light`.

void	drawVectorial (void *param)

Snapshots
virtual QImage	grabFrameBuffer (bool withAlpha=false)

const QString &	snapshotFileName () const
	Returns the snapshot file name used by saveSnapshot().

const QString &	snapshotFilename () const

const QString &	snapshotFormat () const
	Returns the snapshot file format used by saveSnapshot().

int	snapshotCounter () const
	Returns the value of the counter used to name snapshots in saveSnapshot() when `automatic` is `true`.

int	snapshotQuality ()
	Defines the image quality of the snapshots produced with saveSnapshot().

QFont	scaledFont (const QFont &font) const
	Return a possibly scaled version of `font`, used for snapshot rendering.

void	saveSnapshot (bool automatic=true, bool overwrite=false)
	Saves a snapshot of the current image displayed by the widget.

void	saveSnapshot (const QString &fileName, bool overwrite=false)
	Same as saveSnapshot(), except that it uses `fileName` instead of snapshotFileName().

void	setSnapshotFileName (const QString &name)
	Sets snapshotFileName().

void	setSnapshotFormat (const QString &format)
	Sets the snapshotFormat().

void	setSnapshotCounter (int counter)
	Sets the snapshotCounter().

void	setSnapshotQuality (int quality)
	Sets the snapshotQuality().

bool	openSnapshotFormatDialog ()
	Opens a dialog that displays the different available snapshot formats.

void	snapshotToClipboard ()
	Takes a snapshot of the current display and pastes it to the clipboard.

Buffer to texture
GLuint	bufferTextureId () const
	Returns the texture id of the texture created by copyBufferToTexture().

float	bufferTextureMaxU () const
	Returns the texture coordinate corresponding to the u extremum of the bufferTexture.

float	bufferTextureMaxV () const
	Same as bufferTextureMaxU(), but for the v texture coordinate.

void	copyBufferToTexture (GLint internalFormat, GLenum format=GL_NONE)
	Makes a copy of the current buffer into a texture.

Animation
bool	animationIsStarted () const
	Return `true` when the animation loop is started.

int	animationPeriod () const
	The animation loop period, in milliseconds.

void	setAnimationPeriod (int period)
	Sets the animationPeriod(), in milliseconds.

virtual void	startAnimation ()
	Starts the animation loop.

virtual void	stopAnimation ()
	Stops animation.

virtual void	animate ()
	Scene animation method.

void	toggleAnimation ()
	Calls startAnimation() or stopAnimation(), depending on animationIsStarted().

Help window
virtual QString	helpString () const
	Returns the QString displayed in the help() window main tab.

virtual QString	mouseString () const
	Returns a QString that describes the application mouse bindings, displayed in the help() window `Mouse` tab.

virtual QString	keyboardString () const
	Returns a QString that describes the application keyboard shortcut bindings, and that will be displayed in the help() window `Keyboard` tab.

virtual QString	mouseBindingsString () const
	This method is deprecated, use mouseString() instead.

virtual QString	shortcutBindingsString () const
	This method is deprecated, use keyboardString() instead.

virtual void	help ()
	Opens a modal help window that includes four tabs, respectively filled with helpString(), keyboardString(), mouseString() and about libQGLViewer.

virtual void	aboutQGLViewer ()
	Displays the help window "About" tab.

QTabWidget *	helpWidget ()
	Returns a pointer to the help widget.

Drawing methods
virtual void	resizeGL (int width, int height)
	Callback method used when the widget size is modified.

virtual void	initializeGL ()
	Initializes the QGLViewer OpenGL context and then calls user-defined init().

virtual void	init ()
	Initializes the viewer OpenGL context.

virtual void	paintGL ()
	Main paint method, inherited from `QGLWidget`.

virtual void	preDraw ()
	Sets OpenGL state before draw().

virtual void	preDrawStereo (bool leftBuffer=true)
	Called before draw() (instead of preDraw()) when viewer displaysInStereo().

virtual void	draw ()
	The core method of the viewer, that draws the scene.

virtual void	fastDraw ()
	Draws a simplified version of the scene to guarantee interactive camera displacements.

virtual void	postDraw ()
	Called after draw() to draw viewer visual hints.

Mouse, keyboard and event handlers
virtual void	mousePressEvent (QMouseEvent *)
	Overloading of the `QWidget` method.

virtual void	mouseMoveEvent (QMouseEvent *)
	Overloading of the `QWidget` method.

virtual void	mouseReleaseEvent (QMouseEvent *)
	Overloading of the `QWidget` method.

virtual void	mouseDoubleClickEvent (QMouseEvent *)
	Overloading of the `QWidget` method.

virtual void	wheelEvent (QWheelEvent *)
	Overloading of the `QWidget` method.

virtual void	keyPressEvent (QKeyEvent *)
	Overloading of the `QWidget` method.

virtual void	timerEvent (QTimerEvent *)
	Overloading of the `QObject` method.

virtual void	closeEvent (QCloseEvent *)
	Overloading of the `QWidget` method.

Object selection
int	selectedName () const
	Returns the name (an integer value) of the entity that was last selected by select().

int	selectBufferSize () const
	Returns the selectBuffer() size.

int	selectRegionWidth () const
	Returns the width (in pixels) of a selection frustum, centered on the mouse cursor, that is used to select objects.

int	selectRegionHeight () const
	See the selectRegionWidth() documentation.

GLuint *	selectBuffer ()
	Returns a pointer to an array of `GLuint`.

virtual void	select (const QMouseEvent *event)
	Simple wrapper method: calls `select`(event->pos()).

virtual void	select (const QPoint &point)
	This method performs a selection in the scene from pixel coordinates.

void	setSelectBufferSize (int size)
	Sets the selectBufferSize().

void	setSelectRegionWidth (int width)
	Sets the selectRegionWidth().

void	setSelectRegionHeight (int height)
	Sets the selectRegionHeight().

void	setSelectedName (int id)
	Set the selectedName() value.

virtual void	beginSelection (const QPoint &point)
	This method should prepare the selection.

virtual void	drawWithNames ()
	This method is called by select() and should draw selectable entities.

virtual void	endSelection (const QPoint &point)
	This method is called by select() after scene elements were drawn by drawWithNames().

virtual void	postSelection (const QPoint &point)
	This method is called at the end of the select() procedure.

Keyboard customization
enum	KeyboardAction { DRAW_AXIS, DRAW_GRID, DISPLAY_FPS, ENABLE_TEXT, EXIT_VIEWER, SAVE_SCREENSHOT, CAMERA_MODE, FULL_SCREEN, STEREO, ANIMATION, HELP, EDIT_CAMERA, MOVE_CAMERA_LEFT, MOVE_CAMERA_RIGHT, MOVE_CAMERA_UP, MOVE_CAMERA_DOWN, INCREASE_FLYSPEED, DECREASE_FLYSPEED, SNAPSHOT_TO_CLIPBOARD }
	Defines the different actions that can be associated with a keyboard shortcut using setShortcut(). More...

int	shortcut (KeyboardAction action) const
	Returns the keyboard shortcut associated to a given QGLViewer::KeyboardAction.

int	keyboardAccelerator (KeyboardAction action) const

Qt::Key	keyFrameKey (int index) const

QtKeyboardModifiers	playKeyFramePathStateKey () const

QtKeyboardModifiers	addKeyFrameStateKey () const

QtKeyboardModifiers	playPathStateKey () const

Qt::Key	pathKey (int index) const
	Returns the keyboard key associated to camera Key Frame path `index`.

QtKeyboardModifiers	addKeyFrameKeyboardModifiers () const
	Returns the keyboard modifiers that must be pressed with a pathKey() to add the current camera position to a KeyFrame path.

QtKeyboardModifiers	playPathKeyboardModifiers () const
	Returns the keyboard modifiers that must be pressed with a pathKey() to play a camera KeyFrame path.

void	setShortcut (KeyboardAction action, int key)
	Defines the shortcut() that triggers a given QGLViewer::KeyboardAction.

void	setKeyboardAccelerator (KeyboardAction action, int key)

void	setKeyDescription (int key, QString description)
	Defines a custom keyboard shortcut description, that will be displayed in the help() window `Keyboard` tab.

virtual void	setKeyFrameKey (int index, int key)

virtual void	setPlayKeyFramePathStateKey (int buttonState)

virtual void	setPlayPathStateKey (int buttonState)

virtual void	setAddKeyFrameStateKey (int buttonState)

virtual void	setPathKey (int key, int index=0)
	Sets the pathKey() associated with the camera Key Frame path `index`.

virtual void	setPlayPathKeyboardModifiers (QtKeyboardModifiers modifiers)
	Sets the playPathKeyboardModifiers() value.

virtual void	setAddKeyFrameKeyboardModifiers (QtKeyboardModifiers modifiers)
	Sets the addKeyFrameKeyboardModifiers() value.

Mouse customization
enum	MouseHandler { CAMERA, FRAME }
	Defines the different mouse handlers: camera() or manipulatedFrame(). More...

enum	ClickAction { NO_CLICK_ACTION, ZOOM_ON_PIXEL, ZOOM_TO_FIT, SELECT, RAP_FROM_PIXEL, RAP_IS_CENTER, CENTER_FRAME, CENTER_SCENE, SHOW_ENTIRE_SCENE, ALIGN_FRAME, ALIGN_CAMERA }
	Defines the possible actions that can be binded to a mouse click using setMouseBinding(int,ClickAction,bool,int). More...

enum	MouseAction { NO_MOUSE_ACTION, ROTATE, ZOOM, TRANSLATE, MOVE_FORWARD, LOOK_AROUND, MOVE_BACKWARD, SCREEN_ROTATE, ROLL, DRIVE, SCREEN_TRANSLATE, ZOOM_ON_REGION }
	Defines the possible actions that can be binded to a mouse motion (a click, followed by a mouse displacement). More...

MouseAction	mouseAction (int state) const
	Returns the MouseAction associated with the `state` mouse button(s) and keyboard modifiers.

int	mouseHandler (int state) const
	Returns the MouseHandler associated with the `state`.

int	mouseButtonState (MouseHandler handler, MouseAction action, bool withConstraint=true) const
	Returns the mouse buttons and keyboard modifiers (if any) that have to be used to activate `action` on `handler` (with constraint or not).

ClickAction	clickAction (int state, bool doubleClick, QtMouseButtons buttonsBefore) const
	Same as mouseAction(), but for the ClickAction set using setMouseBinding().

void	getClickButtonState (ClickAction action, int &state, bool &doubleClick, QtMouseButtons &buttonsBefore) const
	Similar to mouseButtonState(), but for ClickAction.

MouseAction	wheelAction (QtKeyboardModifiers modifiers) const
	Same as mouseAction(), but for the wheel action.

int	wheelHandler (QtKeyboardModifiers modifiers) const
	Same as mouseHandler() but for the wheel action.

int	wheelButtonState (MouseHandler handler, MouseAction action, bool withConstraint=true) const
	Same as mouseButtonState(), but for the wheel.

void	setMouseBinding (int state, ClickAction action, bool doubleClick=false, QtMouseButtons buttonsBefore=Qt::NoButton)
	Associates a ClickAction to any mouse buttons and keyboard modifiers combination.

void	setMouseBindingDescription (int state, QString description, bool doubleClick=false, QtMouseButtons buttonsBefore=Qt::NoButton)
	Provides a custom mouse binding description, displayed in the help() window Mouse tab.

void	setMouseBinding (int state, MouseHandler handler, MouseAction action, bool withConstraint=true)
	Associates a MouseAction to any mouse button and keyboard modifiers `state` combination.

void	setWheelBinding (QtKeyboardModifiers modifiers, MouseHandler handler, MouseAction action, bool withConstraint=true)
	Associates a MouseAction and a MouseHandler to a mouse wheel event.

void	setHandlerKeyboardModifiers (MouseHandler handler, QtKeyboardModifiers modifiers)
	Associates keyboard modifiers to MouseHandler `handler`.

void	setHandlerStateKey (MouseHandler handler, int buttonState)

void	setMouseStateKey (MouseHandler handler, int buttonState)

State persistence
QString	stateFileName () const
	Returns the state file name.

virtual QDomElement	domElement (const QString &name, QDomDocument &document) const
	Returns an XML `QDomElement` that represents the QGLViewer.

virtual void	initFromDOMElement (const QDomElement &element)
	Restores the QGLViewer state from a `QDomElement` created by domElement().

virtual void	saveStateToFile ()
	Saves in stateFileName() an XML representation of the QGLViewer state, obtained from domElement().

virtual bool	restoreStateFromFile ()
	Restores the QGLViewer state from the stateFileName() file using initFromDOMElement().

void	setStateFileName (const QString &name)
	Defines the stateFileName() used by saveStateToFile() and restoreStateFromFile().

void	saveToFile (const QString &fileName=QString::null)
	This method is deprecated since version 1.3.9-5.

bool	restoreFromFile (const QString &fileName=QString::null)
	This function is deprecated since version 1.3.9-5.

QGLViewer pool
static const QPtrList < QGLViewer > &	QGLViewerPool ()
	Returns a `QList` that contains pointers to all the created QGLViewers.

static int	QGLViewerIndex (const QGLViewer *const viewer)
	Returns the index of the QGLViewer `viewer` in the QGLViewerPool().

Visual hints
virtual void	setVisualHintsMask (int mask, int delay=2000)
	Defines the mask that will be used to drawVisualHints().

virtual void	drawVisualHints ()
	Draws viewer related visual hints.

virtual void	resetVisualHints ()
	Reset the mask used by drawVisualHints().

Detailed Description

A versatile 3D OpenGL viewer based on QGLWidget.

It features many classical viewer functionalities, such as a camera trackball, manipulated objects, snapshot saving and much more. Its main goal is to ease the development of new 3D applications.

New users should read the introduction page to get familiar with important notions such as sceneRadius(), sceneCenter() and the world coordinate system. Try the numerous simple examples to discover the possibilities and understand how it works.

Usage

To use a QGLViewer, derive you viewer class from the QGLViewer and overload its draw() virtual method. See the simpleViewer example for an illustration.

An other option is to connect your drawing methods to the signals emitted by the QGLViewer (Qt's callback mechanism). See the callback example for a complete implementation.

Definition at line 73 of file qglviewer.h.

Member Enumeration Documentation

enum ClickAction

protected

Defines the possible actions that can be binded to a mouse click using setMouseBinding(int,ClickAction,bool,int).

See the mouse page for details.

Definition at line 984 of file qglviewer.h.

enum KeyboardAction

protected

Defines the different actions that can be associated with a keyboard shortcut using setShortcut().

See the keyboard page for details.

Definition at line 930 of file qglviewer.h.

enum MouseAction

Defines the possible actions that can be binded to a mouse motion (a click, followed by a mouse displacement).

These actions may be binded to the camera() or to the manipulatedFrame() (see QGLViewer::MouseHandler) using setMouseBinding().

Definition at line 997 of file qglviewer.h.

enum MouseHandler

protected

Defines the different mouse handlers: camera() or manipulatedFrame().

Used by setMouseBinding(), setMouseBinding(int, ClickAction, bool, int) and setWheelBinding() to define which handler receives the mouse events.

Definition at line 978 of file qglviewer.h.

Constructor & Destructor Documentation

~QGLViewer ( )

virtual

Virtual destructor.

The viewer is replaced by NULL in the QGLViewerPool() (in order to preserve other viewer's indexes) and allocated memory is released. The camera() is deleted and should be copied before if it is shared by an other viewer.

Definition at line 226 of file qglviewer.cpp.

Member Function Documentation

void aboutQGLViewer ( )

virtualslot

Displays the help window "About" tab.

See help() for details.

Definition at line 2295 of file qglviewer.cpp.

QtKeyboardModifiers addKeyFrameKeyboardModifiers ( ) const

Returns the keyboard modifiers that must be pressed with a pathKey() to add the current camera position to a KeyFrame path.

It can be Qt::NoModifier, Qt::ControlModifier, Qt::ShiftModifier, Qt::AltModifier, Qt::MetaModifier or a combination of these (using the bitwise '|' operator).

Default value is Qt::AltModifier. Defined using setAddKeyFrameKeyboardModifiers().

See also playPathKeyboardModifiers().

Note: If you use Qt version 2 or 3, the Qt::KeyboardModifiers is actually a Qt::ButtonState. The Modifier postfix is replaced by Button in the enums' names (Qt::ControlButton, Qt::AltButton, ...).

Definition at line 2707 of file qglviewer.cpp.

virtual void animate ( )

inlinevirtualslot

Scene animation method.

When animationIsStarted(), this method is in charge of the scene update before each draw(). Overload it to define how your scene evolves over time. The time should either be regularly incremented in this method (frame-rate independent animation) or computed from actual time (for instance using QTime::elapsed()) for real-time animations.

       Note that KeyFrameInterpolator (which regularly updates a Frame) does not use this method
       to animate a Frame, but rather rely on a QTimer signal-slot mechanism.

See the animation example for an illustration.

Definition at line 656 of file qglviewer.h.

void animateNeeded ( )

signal

Signal emitted by the default animate() method.

Connect this signal to your scene animation method or overload animate().

bool animationIsStarted ( ) const

inline

Return true when the animation loop is started.

During animation, an infinite loop calls animate() and draw() and then waits for animationPeriod() milliseconds before calling animate() and draw() again. And again.

Use startAnimation(), stopAnimation() or toggleAnimation() to change this value.

See the animation example for illustration.

Definition at line 623 of file qglviewer.h.

int animationPeriod ( ) const

inline

The animation loop period, in milliseconds.

When animationIsStarted(), this is delay waited after draw() to call animate() and draw() again. Default value is 40 milliseconds (25 Hz).

This value will define the currentFPS() when animationIsStarted() (provided that your animate() and draw() methods are fast enough).

If you want to know the maximum possible frame rate of your machine on a given scene, setAnimationPeriod() to 0, and startAnimation() (keyboard shortcut is Enter). The display will then be updated as often as possible, and the frame rate will be meaningful.

Note: This value is taken into account only the next time you call startAnimation(). If animationIsStarted(), you should stopAnimation() first.

Definition at line 638 of file qglviewer.h.

float aspectRatio ( ) const

inline

Returns the aspect ratio of the viewer's widget (width() / height()).

Definition at line 329 of file qglviewer.h.

bool axisIsDrawn ( ) const

inline

Returns true if the world axis is drawn by the viewer.

Set by setAxisIsDrawn() or toggleAxisIsDrawn(). Default value is false.

Definition at line 115 of file qglviewer.h.

void axisIsDrawnChanged ( bool drawn )

signal

This signal is emitted whenever axisIsDrawn() changes value.

QColor backgroundColor ( ) const

inline

Returns the background color of the viewer.

This method is provided for convenience since the background color is an OpenGL state variable set with glClearColor(). However, this internal representation has the advantage that it is saved (resp. restored) with saveStateToFile() (resp. restoreStateFromFile()).

Use setBackgroundColor() to define and activate a background color.

Attention: Each QColor component is an integer ranging from 0 to 255. This differs from the float values used by glClearColor() which are in the 0.0-1.0 range. Default value is (51, 51, 51) (dark gray). You may have to change foregroundColor() accordingly.; This method does not return the current OpenGL clear color as glGet() does. Instead, it returns the QGLViewer internal variable. If you directly use glClearColor() or qglClearColor() instead of setBackgroundColor(), the two results will differ.

Definition at line 186 of file qglviewer.h.

void beginSelection ( const QPoint & point )

protectedvirtual

This method should prepare the selection.

It is called by select() before drawWithNames().

The default implementation uses the GL_SELECT mode to perform a selection. It uses selectBuffer() and selectBufferSize() to define a glSelectBuffer(). The GL_PROJECTION is then set using gluPickMatrix(), with a window selection size defined by selectRegionWidth() and selectRegionHeight(). Finally, the GL_MODELVIEW matrix is set to the world coordinate system using qglviewer::Camera::loadModelViewMatrix(). See the gluPickMatrix() documentation for details.

You should not need to redefine this method (if you use the GL_SELECT mode to perform your selection), since this code is fairly classical and can be tuned. You are more likely to overload endSelection() if you want to use a more complex select buffer structure.

Definition at line 1253 of file qglviewer.cpp.

GLuint bufferTextureId ( ) const

Returns the texture id of the texture created by copyBufferToTexture().

Use glBindTexture() to use this texture. Note that this is already done by copyBufferToTexture().

Returns 0 is copyBufferToTexture() was never called or if the texure was deleted using glDeleteTextures() since then.

Definition at line 4093 of file qglviewer.cpp.

float bufferTextureMaxU ( ) const

inline

Returns the texture coordinate corresponding to the u extremum of the bufferTexture.

The bufferTexture is created by copyBufferToTexture(). The texture size has powers of two dimensions and the buffer image hence only fills a part of it. This value corresponds to the u coordinate of the extremum right side of the buffer image.

Use (0,0) to (bufferTextureMaxU(), bufferTextureMaxV()) texture coordinates to map the entire texture on a quad.

Definition at line 605 of file qglviewer.h.

float bufferTextureMaxV ( ) const

inline

Same as bufferTextureMaxU(), but for the v texture coordinate.

Definition at line 607 of file qglviewer.h.

qglviewer::Camera* camera ( ) const

inline

Returns the associated qglviewer::Camera, never NULL.

Definition at line 268 of file qglviewer.h.

Referenced by RenderWorld::draw(), RenderWorld::init(), RenderWorld::keyPressEvent(), and RenderWorld::resourceChanged().

bool cameraIsEdited ( ) const

inline

Returns true if the camera() is being edited in the viewer.

Set by setCameraIsEdited() or toggleCameraIsEdited(). Default value is false.

The current implementation is limited: the defined camera() paths (see qglviewer::Camera::keyFrameInterpolator()) are simply displayed using qglviewer::Camera::drawAllPaths(). Actual camera and path edition will be implemented in the future.

Definition at line 141 of file qglviewer.h.

void cameraIsEditedChanged ( bool edited )

signal

This signal is emitted whenever cameraIsEdited() changes value.

QGLViewer::ClickAction clickAction	(	int	state,
		bool	doubleClick,
		QtMouseButtons	buttonsBefore
	)		const

Same as mouseAction(), but for the ClickAction set using setMouseBinding().

Definition at line 3147 of file qglviewer.cpp.

void closeEvent ( QCloseEvent * e )

protectedvirtual

Overloading of the QWidget method.

Saves the viewer state using saveStateToFile() and then calls QGLWidget::closeEvent().

Definition at line 1132 of file qglviewer.cpp.

void copyBufferToTexture	(	GLint	internalFormat,
		GLenum	format = `GL_NONE`
	)

slot

Makes a copy of the current buffer into a texture.

Creates a texture (when needed) and uses glCopyTexSubImage2D() to directly copy the buffer in it.

Use internalFormat and format to define the texture format and hence which and how components of the buffer are copied into the texture. See the glTexImage2D() documentation for details.

When format is c GL_NONE (default), its value is set to internalFormat, which fits most cases. Typical internalFormat (and format) values are GL_DEPTH_COMPONENT and GL_RGBA. Use GL_LUMINANCE as the internalFormat and GL_RED, GL_GREEN or GL_BLUE as format to capture a single color component as a luminance (grey scaled) value. Note that GL_STENCIL is not supported as a format.

The texture has dimensions which are powers of two. It is as small as possible while always being larger or equal to the current size of the widget. The buffer image hence does not entirely fill the texture: it is stuck to the lower left corner (corresponding to the (0,0) texture coordinates). Use bufferTextureMaxU() and bufferTextureMaxV() to get the upper right corner maximum u and v texture coordinates. Use bufferTextureId() to retrieve the id of the created texture.

Here is how to display a grey-level image of the z-buffer:

copyBufferToTexture(GL_DEPTH_COMPONENT);
glMatrixMode(GL_TEXTURE);
glLoadIdentity();
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_REPLACE);
glEnable(GL_TEXTURE_2D);
startScreenCoordinatesSystem(true);
glBegin(GL_QUADS);
glTexCoord2f(0.0, 0.0);                                 glVertex2i(0, 0);
glTexCoord2f(bufferTextureMaxU(), 0.0);                 glVertex2i(width(), 0);
glTexCoord2f(bufferTextureMaxU(), bufferTextureMaxV()); glVertex2i(width(), height());
glTexCoord2f(0.0, bufferTextureMaxV());                 glVertex2i(0, height());
glEnd();
stopScreenCoordinatesSystem();
glDisable(GL_TEXTURE_2D);

Use glReadBuffer() to select which buffer is copied into the texture. See also glPixelTransfer(), glPixelZoom() and glCopyPixel() for pixel color transformations during copy.

Call makeCurrent() before this method to make the OpenGL context active if needed.

Note: The GL_DEPTH_COMPONENT format may not be supported by all hardware. It may sometimes be emulated in software, resulting in poor performances.; The bufferTextureId() texture is binded at the end of this method.

Definition at line 4036 of file qglviewer.cpp.

float currentFPS ( )

inline

Returns the current averaged viewer frame rate.

This value is computed and averaged over 20 successive frames. It only changes every 20 draw() (previously computed value is otherwise returned).

This method is useful for true real-time applications that may adapt their computational load accordingly in order to maintain a given frequency.

This value is meaningful only when draw() is regularly called, either using a QTimer, when animationIsStarted() or when the camera is manipulated with the mouse.

Definition at line 340 of file qglviewer.h.

void displayMessage	(	const QString &	message,
		int	delay = `2000`
	)

Briefly displays a message in the lower left corner of the widget.

Convenient to provide feedback to the user.

message is displayed during delay milliseconds (default is 2 seconds) using drawText().

This method should not be called in draw(). If you want to display a text in each draw(), use drawText() instead.

If this method is called when a message is already displayed, the new message replaces the old one. Use setTextIsEnabled() (default shortcut is '?') to enable or disable text (and hence messages) display.

Definition at line 998 of file qglviewer.cpp.

bool displaysInStereo ( ) const

inline

Returns true if the viewer displays in stereo.

The QGLViewer object must be created with a stereo format to handle stereovision:

QGLFormat format;
format.setStereoDisplay( TRUE );
QGLViewer viewer(format);

The hardware needs to support stereo display. Try the stereoViewer example to check.

Set by setStereoDisplay() or toggleStereoDisplay(). Default value is false.

Stereo is performed using the Parallel axis asymmetric frustum perspective projection method. See Camera::loadProjectionMatrixStereo() and Camera::loadModelViewMatrixStereo().

The stereo parameters are defined by the camera(). See qglviewer::Camera::setIODistance(), qglviewer::Camera::setPhysicalDistanceToScreen(), qglviewer::Camera::setPhysicalScreenWidth() and qglviewer::Camera::setFocusDistance().

Definition at line 368 of file qglviewer.h.

QDomElement domElement	(	const QString &	name,
		QDomDocument &	document
	)		const

virtual

Returns an XML QDomElement that represents the QGLViewer.

Used by saveStateToFile(). restoreStateFromFile() uses initFromDOMElement() to restore the QGLViewer state from the resulting QDomElement.

name is the name of the QDomElement tag. doc is the QDomDocument factory used to create QDomElement.

The created QDomElement contains state values (axisIsDrawn(), FPSIsDisplayed(), isFullScreen()...), viewer geometry, as well as camera() (see qglviewer::Camera::domElement()) and manipulatedFrame() (if defined, see qglviewer::ManipulatedFrame::domElement()) states.

Overload this method to add your own attributes to the state file:

QDomElement Viewer::domElement(const QString& name, QDomDocument& document) const
{
// Creates a custom node for a light
QDomElement de = document.createElement("Light");
de.setAttribute("state", (lightIsOn()?"on":"off"));
// Note the include of the ManipulatedFrame domElement method.
de.appendChild(lightManipulatedFrame()->domElement("LightFrame", document));
// Get default state domElement and append custom node
QDomElement res = QGLViewer::domElement(name, document);
res.appendChild(de);
return res;
}

See initFromDOMElement() for the associated restoration code.

Attention: For the manipulatedFrame(), qglviewer::Frame::constraint() and qglviewer::Frame::referenceFrame() are not saved. See qglviewer::Frame::domElement().

Definition at line 3778 of file qglviewer.cpp.

virtual void draw ( )

inlineprotectedvirtual

The core method of the viewer, that draws the scene.

If you build a class that inherits from QGLViewer, this is the method you want to overload. See the simpleViewer example for an illustration.

The camera modelView matrix set in preDraw() converts from the world to the camera coordinate systems. Vertices given in draw() can then be considered as being given in the world coordinate system. The camera is moved in this world using the mouse. This representation is much more intuitive than the default camera-centric OpenGL standard.

Attention: The GL_PROJECTION matrix should not be modified by this method, to correctly display visual hints (axis, grid, FPS...) in postDraw(). Use push/pop or call camera()->loadProjectionMatrix() at the end of draw() if you need to change the projection matrix (unlikely). On the other hand, the GL_MODELVIEW matrix can be modified and left in a arbitrary state.

Reimplemented in RenderWorld.

Definition at line 809 of file qglviewer.h.

void drawArrow	(	float	length = `1.0f`,
		float	radius = `-1.0f`,
		int	nbSubdivisions = `12`
	)

static

Draws a 3D arrow along the positive Z axis.

length, radius and nbSubdivisions define its geometry. If radius is negative (default), it is set to 0.05 * length.

Use drawArrow(const Vec& from, const Vec& to, float radius, int nbSubdivisions) or change the ModelView matrix to place the arrow in 3D.

Uses current color and does not modify the OpenGL state.

Definition at line 3413 of file qglviewer.cpp.

Referenced by RenderWorld::drawArrow(), drawArrow(), drawAxis(), and drawLight().

void drawArrow	(	const qglviewer::Vec &	from,
		const qglviewer::Vec &	to,
		float	radius = `-1.0f`,
		int	nbSubdivisions = `12`
	)

static

Draws a 3D arrow between the 3D point from and the 3D point to, both defined in the current ModelView coordinates system.

See drawArrow(float length, float radius, int nbSubdivisions) for details.

Definition at line 3433 of file qglviewer.cpp.

References drawArrow(), and Vec::norm().

void drawAxis ( float length = 1.0f )

static

Draws an XYZ axis, with a given size (default is 1.0).

The axis position and orientation matches the current modelView matrix state: three arrows (red, green and blue) of length length are drawn along the positive X, Y and Z directions.

Use the following code to display the current position and orientation of a qglviewer::Frame:

glPushMatrix();
glMultMatrixd(frame.matrix());
QGLViewer::drawAxis(sceneRadius() / 5.0); // Or any scale
glPopMatrix();

The current color and line width are used to draw the X, Y and Z characters at the extremities of the three arrows. The OpenGL state is not modified by this method.

axisIsDrawn() uses this method to draw a representation of the world coordinate system. See also QGLViewer::drawArrow() and QGLViewer::drawGrid().

Definition at line 3461 of file qglviewer.cpp.

References drawArrow().

Referenced by KeyFrameInterpolator::drawPath().

void drawFinished ( bool automatic )

signal

Signal emitted at the end of the QGLViewer::paintGL() method, when frame is drawn.

Can be used to notify an image grabbing process that the image is ready. A typical example is to connect this signal to the saveSnapshot() method, so that a (numbered) snapshot is generated after each new display, in order to create a movie:

connect(viewer, SIGNAL(drawFinished(bool)), SLOT(saveSnapshot(bool)));

The automatic bool variable is always true and has been added so that the signal can be connected to saveSnapshot() with an automatic value set to true.

void drawGrid	(	float	size = `1.0f`,
		int	nbSubdivisions = `10`
	)

static

Draws a grid in the XY plane, centered on (0,0,0) (defined in the current coordinate system).

size (OpenGL units) and nbSubdivisions define its geometry. Set the GL_MODELVIEW matrix to place and orientate the grid in 3D space (see the drawAxis() documentation).

The OpenGL state is not modified by this method.

Definition at line 3529 of file qglviewer.cpp.

void drawLight	(	GLenum	light,
		float	scale = `1.0f`
	)		const

protectedvirtual

Draws a representation of light.

Called in draw(), this method is useful to debug or display your light setup. Light drawing depends on the type of light (point, spot, directional).

The method retrieves the light setup using glGetLightfv. Position and define your lights before calling this method.

Light is drawn using its diffuse color. Disabled lights are not displayed.

Drawing size is proportional to sceneRadius(). Use scale to rescale it.

See the drawLight example for an illustration.

Attention: You need to enable GL_COLOR_MATERIAL before calling this method. glColor is set to the light diffuse color.

Definition at line 769 of file qglviewer.cpp.

References drawArrow(), Frame::matrix(), and Vec::normalize().

void drawNeeded ( )

signal

Signal emitted by the default draw() method.

Connect this signal to your main drawing method or overload draw(). See the callback example for an illustration.

void drawText	(	int	x,
		int	y,
		const QString &	text,
		const QFont &	fnt = `QFont()`
	)

Draws text at position x, y (expressed in screen coordinates pixels, origin in the upper left corner of the widget).

The default QApplication::font() is used to render the text when no fnt is specified. Use QApplication::setFont() to define this default font.

You should disable GL_LIGHTING and GL_DEPTH_TEST before this method so that colors are properly rendered.

This method can be used in conjunction with the qglviewer::Camera::projectedCoordinatesOf() method to display a text attached to an object. In your draw() method use:

qglviewer::Vec screenPos = camera()->projectedCoordinatesOf(myFrame.position());

drawText((int)screenPos[0], (int)screenPos[1], "My Object");

See the screenCoordSystem example for an illustration.

Text is displayed only when textIsEnabled() (default). This mechanism allows the user to conveniently remove all the displayed text with a single keyboard shortcut.

See also displayMessage() to drawText() for only a short amount of time.

Use QGLWidget::renderText(x,y,z, text) instead (Qt version >= 3.1) if you want to draw a text located at a specific 3D position instead of 2D screen coordinates (fixed size text, facing the camera).

The GL_MODELVIEW and GL_PROJECTION matrices are not modified by this method.

Attention: This method uses display lists to render the characters, with an index that starts at 2000 by default (see the QGLWidget::renderText() documentation). If you use more than 2000 Display Lists, they may overlap with these. Directly use QGLWidget::renderText() in that case, with a higher listBase parameter (or overload fontDisplayListBase with Qt4).; There is a problem with anti-aliased font with nVidia cards and Qt versions lower than 3.3. Until this version, the fnt parameter is not taken into account to prevent a crash. It is replaced by a fixed font that should be compatible with the qtconfig anti-aliased font configuration (disable this option otherwise).

Note: This method uses QGLWidget::renderText() if your Qt version is greater or equal to 3.1, otherwise it uses (and requires) GLUT. When GLUT is used, only the fnt size attribute (set with QFont::setPixelSize() or QFont::setPointSize()) is taken into account. Also note that in that case each call to drawText() changes the camera projection matrix and restores it back (using startScreenCoordinatesSystem() and stopScreenCoordinatesSystem()). If you call this method several times and it slows down your frame rate, consider factorizing the context changes.

Definition at line 866 of file qglviewer.cpp.

Referenced by RenderWorld::draw().

void drawVisualHints ( )

virtual

Draws viewer related visual hints.

Displays the new qglviewer::Camera::revolveAroundPoint() when it is changed. See the mouse page for details. Also draws a line between qglviewer::Camera::revolveAroundPoint() and mouse cursor when the camera is rotated around the camera Z axis.

See also setVisualHintsMask() and resetVisualHints(). The hint color is foregroundColor().

Note: These methods may become more interesting one day. The current design is too limited and should be improved when other visual hints must be drawn.

Limitation : One needs to have access to visualHint_ to overload this method.

Removed from the documentation for this reason.

Definition at line 3311 of file qglviewer.cpp.

virtual void drawWithNames ( )

inlineprotectedvirtual

This method is called by select() and should draw selectable entities.

Default implementation is empty. Overload and draw the different elements of your scene you want
to be able to select. The default select() implementation relies on the \c GL_SELECT, and requires
that each selectable element is drawn within a \c glPushName() - \c glPopName() block. A typical
usage would be (see the <a href="../examples/select.html">select example</a>):

void Viewer::drawWithNames() {
   for (int i=0; i<nbObjects; ++i) {
      glPushName(i);
      object(i)->draw();
      glPopName();
   }
}

The resulting selected name is computed by endSelection(), which setSelectedName() to the integer
id pushed by this method (a value of -1 means no selection). Use selectedName() to update your
selection, probably in the postSelection() method.

\attention If your selected objects are points, do not use \c glBegin(GL_POINTS); and \c glVertex3fv()
in the above \c draw() method (not compatible with raster mode): use \c glRasterPos3fv() instead.

Reimplemented in RenderWorld.

Definition at line 910 of file qglviewer.h.

void endSelection ( const QPoint & point )

protectedvirtual

This method is called by select() after scene elements were drawn by drawWithNames().

It should analyze the selection result to determine which object is actually selected.

The default implementation relies on GL_SELECT mode (see beginSelection()). It assumes that names were pushed and popped in drawWithNames(), and analyzes the selectBuffer() to find the name that corresponds to the closer (z min) object. It then setSelectedName() to this value, or to -1 if the selectBuffer() is empty (no object drawn in selection region). Use selectedName() (probably in the postSelection() method) to retrieve this value and update your data structure accordingly.

This default implementation, although sufficient for many cases is however limited and you may have to overload this method. This will be the case if drawWithNames() uses several push levels in the name heap. A more precise depth selection, for instance privileging points over edges and triangles to avoid z precision problems, will also require an overloading. A typical implementation will look like:

glFlush();
// Get the number of objects that were seen through the pick matrix frustum.
// Resets GL_RENDER mode.
GLint nbHits = glRenderMode(GL_RENDER);
if (nbHits <= 0)
setSelectedName(-1);
else
{
// Interpret results: each object created values in the selectBuffer().
// See the glSelectBuffer() man page for details on the buffer structure.
// The following code depends on your selectBuffer() structure.
for (int i=0; i<nbHits; ++i)
if ((selectBuffer())[i*4+1] < zMin)
setSelectedName((selectBuffer())[i*4+3])
}

See the multiSelect example for a multi-object selection implementation of this method.

Definition at line 1313 of file qglviewer.cpp.

void fastDraw ( )

protectedvirtual

Draws a simplified version of the scene to guarantee interactive camera displacements.

This method is called instead of draw() when the qglviewer::Camera::frame() is qglviewer::ManipulatedCameraFrame::isManipulated(). Default implementation simply calls draw().

Overload this method if your scene is too complex to allow for interactive camera manipulation. See the fastDraw example for an illustration.

Definition at line 525 of file qglviewer.cpp.

QColor foregroundColor ( ) const

inline

Returns the foreground color used by the viewer.

This color is used when FPSIsDisplayed(), gridIsDrawn(), to display the camera paths when the cameraIsEdited().

Attention: Each QColor component is an integer in the range 0-255. This differs from the float values used by glColor3f() which are in the range 0-1. Default value is (180, 180, 180) (light gray).

Use qglColor(foregroundColor()) to set the current OpenGL color to the foregroundColor().

void getClickButtonState	(	ClickAction	ca,
		int &	state,
		bool &	doubleClick,
		QtMouseButtons &	buttonsBefore
	)		const

int mouseButtonState	(	MouseHandler	handler,
		MouseAction	action,
		bool	withConstraint = `true`
	)		const

void setMouseBinding	(	int	state,
		ClickAction	action,
		bool	doubleClick = `false`,
		QtMouseButtons	buttonsBefore = `Qt::NoButton`
	)

void setMouseBindingDescription	(	int	state,
		QString	description,
		bool	doubleClick = `false`,
		QtMouseButtons	buttonsBefore = `Qt::NoButton`
	)

void setMouseGrabberIsEnabled	(	const qglviewer::MouseGrabber *const	mouseGrabber,
		bool	enabled = `true`
	)

int wheelButtonState	(	MouseHandler	handler,
		MouseAction	action,
		bool	withConstraint = `true`
	)		const

WorldSim - 1.2.3

Signals

Public Member Functions

Display of visual hints

Viewer's colors

Scene dimensions

Associated objects

Mouse grabbers

State of the viewer

Display methods

Snapshots

Buffer to texture

Animation

Help window

Drawing methods

Mouse, keyboard and event handlers

Object selection

Keyboard customization

Mouse customization

State persistence

QGLViewer pool

Visual hints

Detailed Description

Usage

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation