The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenGL-PLG-0.03
River stage zero No dependents
1 ++
/ OpenGL::PLG

NAME

OpenGL::PLG - Create, manipulate and render PoLyGon objects and files

VERSION

Version 0.03

SYNOPSIS

    use OpenGL::PLG;

    # create a new PoLyGon object
    my $plg = OpenGL::PLG->new();

    # define a few vertices with an
    # ID as a last argument
    $plg->set_vertex( 0.0,  1.0, 0.0, 1 );
    $plg->set_vertex( 1.0, -1.0, 0.0, 2 );
    $plg->set_vertex(-1.0, -1.0, 0.0, 3 );

    # if you ommit the ID, it will add in the
    # first free ID slot, and return that ID number.
    my $id = $plg->set_vertex(0.5, 0.5, 0.5);
    print "vertex inserted with id $id\n";  # '4', in our case here
    
    # you can also set a lot of them simultaneously.
    # The code below does exactly the same as above
    # (overriding previously set values)
    $plg->set_vertices( {
            1 => [ 0.0,  1.0, 0.0],
            2 => [ 1.0, -1.0, 0.0],
            3 => [-1.0, -1.0, 0.0],
          });
    
    # create a polygon using above vertices chosen 
    # by vertex "ID". The first value must indicate
    # the size of the polygon, i.e., the size of 
    # the array.
    $plg->set_polygon(3, 1,2,3);

    # after vertices and polygons are created, you
    # can fetch them like this:
    my @v_ids       = $plg->get_polygon( 1 );
    my @coordinates = $plg->get_vertex( $v_ids[0] );

    # you can even get all vertices from a given polygon
    # in an array ref:
    my $vertices = $plg->get_vertices_from_polygon( 2 );
   
    # you can see the OpenGL code necessary to render
    # the model inside:
    print $plg->dump_code();

    # The above command outputs (in this case):
    # -----------------------------------------
    #
    # glBegin(GL_POLYGON);
    #   glVertex3f(0.0, 1.0, 0.0);
    #   glVertex3f(1.0, -1.0, 0.0);
    #   glVertex3f(-1.0, -1.0, 0.0);
    # glEnd();
    
    # you can optionally dump the generated code
    # directly to a file:
    $plg->dump_code_to_file('triangle.render');
    
    # or write a file in raw PLG format
    $plg->write_to_file('mytriangle.plg');
    
    # finally, you can delete vertices 
    # and polygons at will by ID
    $plg->delete_polygon(1);
    $plg->delete_vertex(4);

You can also parse standard PLG files and even render your code in an OpenGL program. The following snippet is a tiny working program that does that (keys 'x', 'y' and 'z', when pressed, will rotate the 3d model on each axis):

    use Time::HiRes qw(usleep);
    use OpenGL qw(:all);
    
    use OpenGL::PLG;
    
    my $dino = OpenGL::PLG->new();
    $dino->parse_file('trex.plg');
   
    my ($rx, $ry, $rz) = (0.0, 0.0, 0.0);
    glutInit;  
    glutInitDisplayMode(GLUT_RGB | GLUT_DOUBLE);  
    glutCreateWindow("Sample PLG Renderer");  
    glutDisplayFunc(\&DrawGLScene);  
    glutIdleFunc(\&DrawGLScene);
    glutKeyboardFunc(\&keyPressed);
    glClearColor(0.0, 0.0, 0.0, 0.0);
    InitGL(640, 480);
    glutMainLoop;  
    
    sub InitGL {
        my ($width, $height) = @_;
        glMatrixMode(GL_PROJECTION);
        glLoadIdentity;
        gluPerspective(65.0, $width/$height, 0.1, 100.0);
        glMatrixMode(GL_MODELVIEW);
    }

    sub DrawGLScene {
        glClear(GL_COLOR_BUFFER_BIT);  
        glLoadIdentity;
        glTranslatef(0.0, 0.0, -5.0); 
        glRotatef($rz, 0, 0, 1);
        glRotatef($rx, 1, 0, 0);
        glRotatef($ry, 0, 1, 0);
        glPolygonMode(GL_FRONT_AND_BACK, GL_LINE);
    
        $dino->render();
    
        glutSwapBuffers;
        usleep (50000);
    }

    sub keyPressed {
        my ($key, $x, $y) = @_;
        if ($key == ord('z') ) {
            $rz = ($rz + 2.0) % 360.0;
        }
        elsif ( $key == ord('x') ) {
            $rx = ($rx + 2.0) % 360.0;
        }
        elsif ( $key == ord('y') ) {
            $ry = ($ry + 2.0) % 360.0;
        }
    }

DESCRIPTION

OpenGL::PLG is a class for OpenGL polygon objects. It lets you easily create and manipulate 3d polygon models. It also reads and writes files in raw PLG format, dumps OpenGL code and renders the 3d model (if you have Perl OpenGL installed).

METHODS

Note: This is a rather new module so the API and standard behavior might slightly change in the future. Please submit any feature requests for new methods and/or any (minor) behavior adjustment. Thanks!

An OpenGL::PLG container has the following methods:

General

new()

Creates a new PoLyGon object.

File Manipulation

parse_file( FILENAME )

Reads a given file in PLG format and parse it into the object. A PLG file is a text file that starts by listing vertices (x, y, z), one per line. Each vertex line may optionally end with a fourth value, consisting of the vertex id (if the id is not supplied, the vertex id is incremental, starting with 1). A blank line separates the vertex list from the polygon list, the latter consisting of two lines: one with the number of vertices in the polygon, and another with each vertice's id.

Some sample PLG files can be found here: http://orion.lcg.ufrj.br/compgraf1/past/downloads/modelos/

render()

Renders OpenGL code to display the object (i.e. the collection of polygons forming whatever-it-is-they-form). Note that using this outside of an OpenGL program will most likely *NOT* produce the expected results (see example in the USAGE section for a way to actually render the image on the screen with this). This method needs the Perl OpenGL library to work.

dump_code()

Dumps a string containing the OpenGL code to display the object (i.e. the collection of polygons forming whatever-it-is-they-form). Use this to see the code that will be produced by render() should you use it inside an OpenGL display. You do *NOT* need OpenGL to use this, as it will just output the code, not eval it.

dump_code_to_file( FILENAME )

This is the same as dump_code(), but will write the string to a given file instead of giving it back to the user. This is useful if you want to use the OpenGL code in another language (like C or C++).

write_to_file( FILENAME )

This will write the object's vertices and polygons to a file, in raw PLG format. This is the exact reverse of parse_file().

Vertex Manipulation

get_vertex( ID )

Returns an array containing the wanted vertex coordinates (by its id).

get_vertices_from_polygon( ID )

Returns an array reference containing all vertex coordinates inside a given polygon, already resolved (instead of just the vertices' id number from get_polygon).

set_vertex( X, Y, Z [, ID] )

Create a vertex in position x, y, z. You can optionally specify an id for it ( >= 1 ), and PLG will put your vertex in that slot, replacing any pre-existant vertex there. Otherwise we'll place it in the last available id slot. It returns the ID where the vertex is stored.

set_vertices( { ID1 => [X, Y, Z], ID2 => ... } )

Same as set_vertex(), but lets you create several vertices at once by passing a hash reference with the vertex ID as key, and the X-Y-Z position as value (an array reference).

delete_vertex( ID )

Deletes a given vertex by its id number. The first included vertex has id "1", while the last one is total_vertices(). Circular references work, so you can get to the last vertex via a -1 id and so on. The id "0" does not exist. If you try to use it, you'll get an error. Also note that, once you delete a vertex, the id's of the vertices following it will be decreased by one.

total_vertices()

Returns the total number of vertices in the object.

Polygon Manipulation

get_polygon( ID )

Returns an array containing the wanted polygon (by its id).

set_polygon( N_VERTICES, @VERTICES )

Add a polygon shape into the object. The first parameter indicates the number of vertices in the polygon. Next follows the list of vertices ids. This function does not return anything, but croak's if the number of vertices is not the same as expected. It returns the ID number where the polygon is stored.

delete_polygon( ID )

Deletes a given polygon by its id number. The first included polygon has id "1", while the last one is total_polygons(). Circular references work, so you can get to the last polygon via a -1 id and so on. The id "0" does not exist. If you try to use it, you'll get an error. Also note that, once you delete a polygon, the id's of the polygons following it will be decreased by one.

total_polygons()

Returns the total number of polygons in the object.

CONFIGURATION AND ENVIRONMENT

OpenGL::PLG requires no configuration files or environment variables.

DEPENDENCIES

None. But the render() method will only work if you have the Perl OpenGL module installed.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

There are a few other raw PLG formats available out-there. I'll try to adjust OpenGL::PLG to be able to parse and output to those in the near future.

Please report any bugs or feature requests to bug-opengl-plg at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=OpenGL-PLG. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc OpenGL::PLG

You can also look for information at:

AUTHOR

Breno G. de Oliveira, <garu at cpan.org>

ACKNOWLEDGEMENTS

A big thank you for grafman's OpenGL Perl module (and original author Stan Melax), which is a lot of fun to play with. Kudos also to everyone who helped the Perl OpenGL project along the way (and the OpenGL community itself).

COPYRIGHT & LICENSE

Copyright 2008 Breno G. de Oliveira, all rights reserved.

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