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

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.

AUTHOR

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

COPYRIGHT AND LICENSE

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

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