/ 
OpenGL-Simple-Viewer-0.02
River stage zero No dependents
/ OpenGL::Simple::Viewer

NAME

OpenGL::Simple::Viewer - Simple 3D geometry viewer using GLUT

SYNOPSIS

use OpenGL::Simple::Viewer;
use OpenGL::Simple::GLUT qw(:all);

glutInit;

my $v = new OpenGL::Simple::Viewer(
              draw_geometry => sub { glutSolidTeapot(1.0); }
);

glutMainLoop;

ABSTRACT

This module uses OpenGL::Simple and OpenGL::Simple::GLUT to provide a quick and simple geometry viewer. If you just want to view a single biomolecule, or throw some polygons at the screen and make sure they come out looking OK, then this module might be for you. If you want to write a first-person-shooter or comprehensive visualization toolkit, this module is probably not for you.

DESCRIPTION

This package provides a simple OpenGL geometry viewer, through the GLUT library. An instance of OpenGL::Simple::Viewer opens a GLUT window, and renders some geometry provided through a callback subroutine; the geometry can be rotated, translated, and zoomed using the mouse.

When the viewer moves around, the window must be redrawn; this usually entails clearing the window, redrawing the background, setting the correct position and orientation, and then drawing the geometry. By default, all you need to supply is a subroutine which draws the geometry; everything else is taken care of. User-defined backgrounds can be set through a callback.

An OpenGL::Simple::Viewer object can be treated as a hashref with several user-adjustable properties:

position

This is a reference to an array of three numbers, corresponding to the position of the viewer with respect to the geometry in 3D space.

orientation

This is a Math::Quaternion representing the orientation of the geometry.

translatescale,zoomscale

These control translation and zooming speeds.

METHODS

new
my $v = new OpenGL::Simple::Viewer; # Should Just Work.

my $v2 = new OpenGL::Simple::Viewer(
       title => 'Shiny window',        # Set window title
       nearclip => 0.1,                # Near clipping plane
       translatescale => 0.01,         # Mouse translation speed
       zoomscale => 0.02,              # Mouse zoom speed
       screenx => 256,                 # Initial window dimensions
       screeny => 256,
       sphererad => 256*0.5,           # Virtual trackball size
       displaymode => GLUT_RGBA | GLUT_DOUBLE | GLUT_DEPTH,
                                       # Window display mode

       initialize_gl => sub {
               glClearColor(0,0,1,1);  # Blue background
       },

       draw_background => sub {
               # Clear the window before drawing geometry
               glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT);
       },

       # Draw a teapot.
       draw_geometry => sub { glutSolidTeapot(1.0); },

);

This method opens up a new GLUT window with some useful event callbacks set, and returns an OpenGL::Simple::Viewer object to represent it. glutInit() should have been called beforehand, to set up the GLUT library.

new() takes either a hash or a reference to a hash of arguments, which can include:

title

Sets the title of the window.

nearclip

Sets the distance of the near clipping plane. Anything closer to the viewer than this will not be displayed.

translatescale

Sets the scale of mouse translation; the larger the scale, the faster the geometry will move for a given mouse motion.

zoomscale

Sets the scale of mouse zooming; the larger the scale, the faster the geometry will move for a given mouse motion.

screenx,screeny

Sets the initial size of the window.

sphererad

Sets the radius of the virtual trackball sphere.

displaymode

Initial arguments to glutInitDisplayMode.

initialize_gl

This is a subroutine which is called once the window has been created, to set up initial GL state such as lighting, texture environment, background colour, etc. By default it sets a black background and a white light. If this argument is set to undef, then no GL state will be changed.

draw_geometry

Every time the viewer moves around, the geometry must be redrawn in its new position. This argument is a coderef which is called to redraw the geometry; you can put any GL calls you like in here.

draw_background

When a redraw event occurs, this routine is called first, before the viewer is oriented or the geometry drawn. It can be used to draw a background image.

make_reshapefunc

This method returns a callback subroutine which can be passed to glutReshapeFunc, and which sets the OpenGL::Viewer::Simple state after a window is resized. You are free to set your own reshape callback by calling glutReshapeFunc(); if you ever want the old one back, then simply

glutReshapeFunc($viewer->make_reshapefunc);
make_displayfunc

Similarly to make_reshapefunc(), this returns the default display callback subroutine.

make_mousefunc

Similarly to make_reshapefunc(), this returns the default mouse click callback subroutine.

make_motionfunc

Similarly to make_reshapefunc(), this returns the default mouse motion callback subroutine.

mouserotatemotion ($x0,$y0,$x1,$y1)

This method takes four arguments, corresponding to a motion from ($x0,$y0) to ($x1,$y1). It interprets the motion as the user dragging on a virtual trackball sitting on the window, and rotates the geometry accordingly. The radius of the trackball is set through the sphererad property.

mousetransmotion ($x0,$y0,$x1,$y1)

This method takes the coordinates of a mouse drag event, and interprets it as a translation. The magnitude of the translation can be set through the translatescale property.

mousetransmotion ($dz)

This method takes a single argument representing the length of a mouse drag event, and zooms the geometry accordingly, controlled by the zoomscale property.

enslave

This method takes a list of OpenGL::Simple::Viewer objects, and sets them all to receive motion events from the object on which the method is invoked. If you have two viewers, $v1 and $v2, then

$v1->enslave($v2);

means that dragging the mouse around in viewer $v1 will cause both $v1 and $v2 to move; however, mouse-dragging in viewer $v2 will only cause it to move, and not $v1.

decouple

This method takes a list of Viewer objects, and decouples their motion from that of the object on which it was invoked.

$v1->decouple($v2,$v3);

is the inverse of

$v1->enslave($v2,$v3);
gang_together

This method takes a list of OpenGL::Simple::Viewer objects, and couples together their motion, so that mouse dragging in any of them will cause all of them to move.

$v1->gang_together($v2,$v3);

is the same as

OpenGL::Simple::Viewer::gang_together($v1,$v2,$v3)

and will couple the motion of $v1,$v2, and $v3.

SEE ALSO

OpenGL::Simple, OpenGL::Simple::GLUT

AUTHOR

Jonathan Chin, <jon-opengl-simple-viewer@earth.li>

COPYRIGHT AND LICENSE

Copyright 2004 by Jonathan Chin

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.