December 2004 Archives

All~

The observant among you might notice that I missed last week's summary. With the hubbub and confusion of the holidays, I blame ninjas, in particular Ryu Hyabusa. Given that Christmas is next weekend and New Years is the weekend after that, what you are like to see in the future are a pair of ten-day summaries or some other equally irregular pattern. If you are thinking of using the dates of my summaries to seed a random number generator, I would advise against it as I can be really easily bought ;-). Without more ado, I give you this fortnight's summary starting with:

Perl 6 Language

Lexical Scope of Parametric Declaration Blocks

Ashley Winters wanted to know the differences between type parameter lists and sub parameter lists. Luke Palmer could not think of any.

Object Representation

Abhijit Mahabal noticed that S12 allowed one to supply an object layout to bless() and wondered if one could really have two instances of the same class with different layouts. Larry admitted that he had probably not intended for that to be the case.

Capturing into a Hash, Hypothetically

Patrick R. Michaud wondered about capturing things into a hash in S05, as <ident> now captures. Larry admitted that it was probably supposed to be (<<ident>>) but also noticed that this exposed a blind spot in the design. He ruminated about this blind spot and ways to solve it. After much churning, he decided that it would be possible to perform multiple different (but identically named) rule captures by adding information after a dash a la <ws-1> <ws-2> <ws-3>.

This article is the second in a series aimed at building a full 3D engine in Perl. The first article, Building a 3D Engine in Perl, covered basic program structure, opening an OpenGL window using SDL, basic projection and viewing setup, simple object rendering, object transformations, and depth ordering using the OpenGL depth buffer.

Editor's note: see also the rest of the series, lighting and movement, and profiling your application.

This time, I'll discuss rotating and animating the view, SDL event and keyboard handling, and compensating for frame rate variations. As a bonus, I'll demonstrate some real-world refactoring, including a conversion from procedural to (weakly) object-oriented code. Before I start, however, there were a couple of issues discovered since the first article went live:

• In the first article, I wrote "orthogonal projection." This should be "orthographic projection," which reminds me again that no matter how many times you proofread, you can still miss the bug--in code or in prose. Unfortunately, prose is a bit harder to write tests for.

• Todd Ross discovered a problem with SDL on FreeBSD 5.3, which caused the code to die immediately with "Bad system call (core dumped)." A short while later, he reported the workaround. He set his LD_PRELOAD environment variable with a little magic, and everything worked fine:

  setenv LD_PRELOAD /usr/lib/libc_r.so

  His research method is a good one to follow if you should encounter a similar problem. He installed another SDL_Perl application, in this case Frozen Bubble. Once he was sure it worked, he checked the code in the launcher script and found the magic shown above. A quick test confirmed that this worked for his code as well.

  Frozen Bubble is a 2D application, so if it works fine but your OpenGL programs don't, check to make sure that OpenGL works at all. Unix variants should supply the glxinfo and glxgears programs. Use glxinfo to gather details on your OpenGL driver; it serves as both a sanity check and a good addition to bug reports. glxgears does a simple animated rendering of meshing gears. This tells you whether OpenGL works correctly (at least for basic stuff) and what performance your OpenGL driver and hardware can provide. Both programs work under X on Apple's OS X 10.3 as well.

Keep your comments, questions, and bug reports coming! I'd like to recognize your contribution in the next article, but if you'd rather remain anonymous, that's fine too.

Without further ado, let's start. If you want try the code at each stage without all the typing, download the example source code. It includes a README.steps file that should help you follow along more easily.

Moving the Viewpoint

At the end of the last article, our scene had a set of axis lines roughly in the center of the screen, with a big white cube behind them and a rotated flat yellow box to the right:

sub draw_view
{
    draw_axes();

    glColor(1, 1, 1);
    glPushMatrix;
    glTranslate( 0, 0, -4);
    glScale( 2, 2, 2);
    draw_cube();
    glPopMatrix;

    glColor(1, 1, 0);
    glPushMatrix;
    glTranslate( 4, 0, 0);
    glRotate( 40, 0, 0, 1);
    glScale(.2, 1, 2);
    draw_cube();
    glPopMatrix;
}

Let's move that white cube to the right by changing the first glTranslate call as follows:

glTranslate( 12, 0, -4);

Now the right side of the window cuts off the white box. If I wanted to fix that while maintaining the relative positions of all the objects, there are a few possible changes I could make:

• Use a wider projection (FOV) angle to see more of the scene at once. Unfortunately, it's already at 90 degrees, which is fairly wide. The perspective effect is already very strong; much wider, and the rendering will look too distorted.
• Individually move all objects in the scene the same distance to the left. This would certainly work, but is a lot of effort, especially when there are many objects in the scene.
• Move the viewpoint right to recenter the view. This is my preference.

I want to move the viewpoint to the right, a positive X direction, so I add +6 to the X component of the viewing translation:

sub set_view_3d
{
    glTranslate(6, -2, -10);
}

Now the scene is even farther to the right. The problem is that OpenGL combines the transformations used to modify the view (viewing transformations) with those used to transform objects in the scene (modeling transformations) in the modelview matrix. OpenGL has no way to know whether I intend any given modelview transformation to alter the view or the objects in the scene; it treats all of them as altering the objects. By translating +6 X, I effectively moved every object 6 units to the right, rather than moving my viewpoint right as intended.

I hinted at the solution before: moving the viewpoint right is equivalent to moving all objects in the scene to the left. The solution to this problem is to reverse the sign of the translation:

sub set_view_3d
{
    glTranslate(-6, -2, -10);
}

This puts the viewpoint at (6, 2, 10) where I wanted it, roughly recentering the scene. Now you can see why the viewing translation from the first article moved the viewpoint to a point slightly above (+Y) and some distance closer to the user (+Z) than the origin. I simply reversed the signs of the viewpoint coordinates I wanted, (0, 2, 10).

The scene is now centered, but with this static view, it's difficult to tell the true location and relative sizes of the objects in the scene. Perhaps I can rotate the view a bit to see this. I'll rotate it 90 degrees counterclockwise (positive rotation) around the Y axis:

sub set_view_3d
{
    glTranslate(-6, -2, -10);
    glRotate(90, 0, 1, 0);
}

Well, that certainly rotated things, but it's still hard to see where the objects really are. Why did the scene end up all over on the left like that and with the axis lines in front?

Animating the View

To understand what's really going on with an odd transformation, it helps me to turn it into a short animation. I start the animation with a very small transformation and keep increasing it until well past the intended level. This way, I can see the effect of both smaller and larger changes.

To do this, I need a few more frames in the animation. I can do this by changing the last line in draw_frame:

$done = 1 if $frame == 10;

I also want the rotation to animate with each frame:

sub set_view_3d
{
    glTranslate(-6, -2, -10);
    glRotate(18 * $frame, 0, 1, 0);
}

This chops the rotation into 18 degree increments, starting at frame 1 with an 18 degree rotation and ending at frame 10 with a 180 degree rotation.

Running this program shows what is happening. The scene rotates counterclockwise around its origin, the intersection point of the axis lines. I wanted to rotate the viewpoint, but I rotated the objects instead. Just reversing the sign won't do the trick. That will rotate the scene the other direction (clockwise), but it won't rotate around the viewpoint--it will still rotate around the scene origin.

In the first article, I described how to visualize a series of transforms by thinking about transforming the local coordinate system of the objects in a series of steps. Looking at the code above, you can see that it first translates the scene origin away and then rotates around that new origin. To rotate around the viewpoint, I need to rotate first and then translate the scene away:

sub set_view_3d
{
    glRotate(18 * $frame, 0, 1, 0);
    glTranslate(-6, -2, -10);
}

This now rotates around the viewpoint, but because it rotates 180 degrees starting from dead ahead, the scene ends up behind the viewpoint. To start the view so that the scene is on one side and then rotates to be on the other, I simply offset the angle:

sub set_view_3d
{
    glRotate(-90 + 18 * $frame, 0, 1, 0);
    glTranslate(-6, -2, -10);
}

At frame 1, the rotation angle is -90 + 18 * 1 = -72 degrees. At frame 10, the angle is -90 + 18 * 10 = 90 degrees. Perfect.

Stop and Turn Around

There's only one little problem: it's going the wrong way! I wanted to do a counterclockwise rotation of the view, but that should make the scene appear to rotate clockwise around the viewpoint. Imagine standing in front of a landmark, taking a picture. Looking through the viewfinder, you might notice that the landmark is a bit left of center. To center it, turn slightly left (counterclockwise as seen from above, or around +Y in the default OpenGL coordinate system). This would make the landmark appear to move clockwise around you (again as seen from above), moving it from the left side of the viewfinder to the center.

In this case, reverse the angle's sign:

sub set_view_3d
{
    glRotate(90 - 18 * $frame, 0, 1, 0);
    glTranslate(-6, -2, -10);
}

In fact, every transformation of the view is equivalent to the opposite transformation of every object in the scene. You must reverse the sign of the coordinates in a translation, reverse the sign of the angle in a rotation, or take the inverse of the factors in a scaling (shrinking the viewer to half size makes everything appear twice as big). As we saw before, you must reverse the order of rotation and translation as well.

Scaling is a special case. Inverting the factors works, but you must still do the scaling after the translation to achieve the expected effect, rather than following the rule for rotation and translation and reversing the transformation order completely. The reason is that scaling before the translation scales the translation also. Scaling by (2, 2, 2) would double the size of all of the objects in the scene, but it would also put them twice as far away, making them appear the same size. I'll skip the code for this and leave it as an exercise for the reader. Go ahead, have fun.

If you decide to give view scaling a try, remember that all distances will change. This affects some non-obvious things such as the third and fourth arguments to gluPerspective (the distance to the nearest and farthest objects OpenGL will render).

Smoothing It Out

After watching these animations for a while, the jerkiness really begins to bother me, and because I doubled the number of animation frames, it takes twice as long to finish a run. Both of these problems relate to the second-long sleep at the end of draw_frame. I should be able to fix them by shortening the sleep to half a second:

sleep .5;

Chances are, that doesn't yield quite the respected result. On my system, there's a blur for a fraction of a second, and the whole run is done. Unfortunately, the builtin Perl sleep function only handles integer seconds, so .5 truncates to 0 and the sleep returns almost instantly.

Luckily, SDL provides a millisecond-resolution delay function, SDL::Delay. To use it, I add another subroutine to handle the delay, translating between seconds and milliseconds:

sub delay
{
    my $seconds = shift;

    SDL::Delay($seconds * 1000);
}

Now, changing the sleep call to delay fixes it:

delay(.5);

The movement is faster and it only takes five seconds to complete the entire animation again, but this code still wastes the available performance of the system. I want the animation to be as smooth as the system allows, while keeping the rotation speed (and total time) constant. To implement this, I need to give the code a sense of time. First, I add another global to keep the current time:

my ($time);

At this point, my editor likely just sprayed his screen with whatever he's drinking and coughed "Another global?!?" I'll address that later in this article during the refactoring.

To update the time, I need a couple more functions:

sub update_time
{
    $time = now();
}

sub now
{
    return SDL::GetTicks() / 1000;
}

now calls SDL's GetTicks function, which returns the time since SDL initialization in milliseconds. It converts the result back to seconds for convenience elsewhere. update_time uses now to keep the global $time up to date.

main_loop uses this to update the time before rendering the frame:

sub main_loop
{
    while (not $done) {
        $frame++;
        update_time();
        do_frame();
    }
}

Because this version won't artificially slow the animation, I make two changes to draw_frame. I remove the delay call and change the animation end test to check whether the time has reached five seconds, instead of whether frame ten has been drawn.

sub draw_frame
{
    set_projection_3d();
    set_view_3d();
    draw_view();

    print '.';
    $done = 1 if $time >= 5;
}

Finally, set_view_3d must base its animation on the current time instead of the current frame. Our current rotation speed is 18 degrees per frame. With 2 frames per second, that comes to 36 degrees per second:

sub set_view_3d
{
    glRotate(90 - 36 * $time, 0, 1, 0);
    glTranslate(-6, -2, -10);
}

This version should appear much smoother. On my system, the dots printed for each frame scroll up the terminal window. If you run this program multiple times, you'll notice the number of frames (and hence dots) varies. Small variations in timing from numerous sources cause a frame now and then to take more or less time. Over the course of a run, this adds up to being able to complete a few frames more or less before hitting the five second deadline. Visually, the rotation speed should appear nearly constant because it calculates the current angle from the current time, whatever that may be, rather than the frame number.

Refactoring for Fun and Clarity

Now that the animation is smooth, I'm almost ready to add some manual control using SDL events. That's a big topic and involves a lot of code. It's always a good idea before a big change to step back, take a look at the exisiting code, and see if it needs a clean up.

The basic procedure is as follows:

• Find one obvious bit of ugliness.
• Make a small atomic change to clean it up.
• Test to make sure everything still works.
• Lather, rinse, repeat until satisfied.

Unfortunately, it's occasionally necessary to make one part of the code a little uglier while cleaning up something else. The trick is eventually to clean up the freshly uglified piece.

Refactoring the View

And on that note, let's add another global! I don't like the hardcoding of set_view_3d. I'd like to convert that into a data structure of some kind, so I define a view object:

my ($view);

This needs an update routine, so here's a simple one:

sub update_view
{
    $view = {
        position    => [6, 2, 10],
        orientation => [-90 + 36 * $time, 0, 1, 0],
    };
}

This is simply the position and orientation of the virtual viewer (before the sign reversal needed by the viewing transformations). I need to call this in the main loop, just before calling do_frame:

sub main_loop
{
    while (not $done) {
        $frame++;
        update_time();
        update_view();
        do_frame();
    }
}

At this point, running the program should show that nothing much changed because I haven't actually changed the viewing code--the new code runs in parallel with the old code. Using the new code requires replacement of set_view_3d:

sub set_view_3d
{
    my ($angle, @axis) = @{$view->{orientation}};
    my ($x, $y, $z)    = @{$view->{position}};

    glRotate(-$angle, @axis);
    glTranslate(-$x, -$y, -$z);
}

Running the program should again show that nothing visually changed, indicating a successful refactoring. At this point, you may wonder what this has gained; there's a new global and a dozen or so more lines of code. The new code has several benefits:

• The concepts of animating the view parameters and setting the current view in OpenGL are now separate, as they should be.
• Hoisting the update_view call up to main_loop next to the update_time call begins to collect all updates together, cleaning up the overall design.
• The new code hints at further refactoring opportunities.

In fact, I can see several problem places to refactor next, along with some reasons to fix them:

1. The mess of globals, since I just added one.
2. Updating $done in draw_view (mixing updates and OpenGL work again) to continue collecting all updates together.
3. Pervasive hardcoding in draw_view, for all the same reasons I refactored set_view_3d.

The Great Global Smashing

The globals situation is out of hand, so now seems a good time to fix that and check off the first item of the new "pending refactoring" list. First, I need to decide how to address the problem.

Here's the current globals list:

my ($done, $frame);
my ($conf, $sdl_app);
my ($time);
my ($view);

In this mess, I see several different concepts:

• Configuration: $conf
• Resource object: $sdl_app
• Engine state: $done, $frame
• Simulated world: $time, $view

I'll create from these groupings a single engine object laid out like so (variables show where the data from the old globals goes):

{
    conf     => $conf,
    resource => {
        sdl_app => $sdl_app,
    },
    state    => {
        done    => $done,
        frame   => $frame,
    },
    world    => {
        time    => $time,
        view    => $view,
    }
}

This is a fairly radical change from the current code, so to be safe, I'll do it in several small pieces, testing after each version that everything still works.

The first step is to add a constructor for my object:

sub new
{
    my $class = shift;
    my $self  = bless {}, $class;

    return $self;
}

This is pretty much the garden variety trivial constructor in Perl 5. It blesses a hash reference into the specified class and then returns it. I also need to change my START code to use this new constructor to create an object and call main as a method on it:

START: __PACKAGE__->new->main;

This snippet constructs a new object, using the current package as the class name, and immediately calls the main method on the returned object. main doesn't have any parameters, so calling it as a method won't affect it (there are no existing parameters that would be shifted right by a new invocant parameter). I never store the object in a variable as a form of self-imposed stricture. Because the object only exists as the invocant of main, I must convert every routine that accesses the information in the object to a method and change all calls to those routines as well.

Let It Flow

Testing at this point shows all still works, so the next change is to make main flow the object reference through to its children by calling them as methods:

sub main
{
    my $self = shift;

    $self->init;
    $self->main_loop;
    $self->cleanup;
}

Testing this shows that, again, all is fine, as expected. init and main_loop are changed in the obvious fashion (cleanup doesn't do much, so it doesn't need to change now):

sub init
{
    my $self = shift;

    $| = 1;

    $self->init_conf;
    $self->init_window;
}

sub main_loop
{
    my $self = shift;

    while (not $done) {
        $frame++;
        $self->update_time;
        $self->update_view;
        $self->do_frame;
    }
}

Notice that I have not changed the references to $done and $frame in main. It's important to make only a single conceptual change at a time during refactoring, to minimize the chance of making an error and not being able to figure out which change caused the problem. I'll return to these references in a bit. Testing this version shows that all is well, so I continue:

sub do_frame
{
    my $self = shift;

    $self->prep_frame;
    $self->draw_frame;
    $self->end_frame;
}

sub draw_frame
{
    my $self = shift;

    $self->set_projection_3d;
    $self->set_view_3d;
    $self->draw_view;

    print '.';
    $done = 1 if $time >= 5;
}

Again, for this pass, I ignore $done and $time in draw_frame. At this point, I've pretty much exhausted all of the changes that amount to simply turning subroutine calls into method calls and the code still works as advertised.

Replacing the Globals

With this working, I start into more interesting territory. It's time to move the globals into their proper place in the object. First up are the state variables $done and $frame in main_loop:

sub main_loop
{
    my $self = shift;

    while (not $self->{state}{done}) {
        $self->{state}{frame}++;
        $self->update_time;
        $self->update_view;
        $self->do_frame;
    }
}

and the last line of draw_frame:

$self->{state}{done} = 1 if $time >= 5;

As they are no longer globals, I remove their declarations as well. I will have to come back to draw_frame again when cleaning up $time. One change per pass--it's very easy to follow a long chain of related changes before doing a test run and find out you made a mistake. Somewhere. Argh. In this case, I resist the urge to keep changing the code and do another test run immediately to find that indeed all still works.

Next up is the world attribute $view:

sub update_view
{
    my $self = shift;

    $self->{world}{view} = {
        position    => [6, 2, 10],
        orientation => [-90 + 36 * $time, 0, 1, 0],
    };
}

sub set_view_3d
{
    my $self = shift;

    my $view           = $self->{world}{view};
    my ($angle, @axis) = @{$view->{orientation}};
    my ($x, $y, $z)    = @{$view->{position}};

    glRotate(-$angle, @axis);
    glTranslate(-$x, -$y, -$z);
}

In set_view_3d, it seemed clearest to make a lexical $view loaded from the object. This allowed me to leave the rest of the function clean and unchanged. Testing after the above changes and removing the global declaration for $view shows that all is good.

Next up are $conf and the resource object $sdl_app, following much the same pattern as before:

sub init_conf
{
    my $self = shift;

    $self->{conf} = {
        title  => 'Camel 3D',
        width  => 400,
        height => 400,
        fovy   => 90,
    };
}

sub init_window
{
    my $self = shift;

    my $title = $self->{conf}{title};
    my $w     = $self->{conf}{width};
    my $h     = $self->{conf}{height};

    $self->{resource}{sdl_app}
        = SDL::App->new(-title  => $title,
                        -width  => $w,
                        -height => $h,
                        -gl     => 1,
                       );
    SDL::ShowCursor(0);
}

sub set_projection_3d
{
    my $self   = shift;

    my $fovy   = $self->{conf}{fovy};
    my $w      = $self->{conf}{width};
    my $h      = $self->{conf}{height};
    my $aspect = $w / $h;

    glMatrixMode(GL_PROJECTION);
    glLoadIdentity;
    gluPerspective($fovy, $aspect, 1, 1000);

    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity;
}

sub end_frame
{
    my $self = shift;

    $self->{resource}{sdl_app}->sync;
}

The first time I did this, it broke. I had forgotten to make the changes to set_projection_3d. Thanks to use strict, the error was obvious, and a quick fix later, everything worked again.

Last but not least, it's time to fix the remaining world attribute $time:

sub update_time
{
    my $self = shift;

    $self->{world}{time} = now();
}

In update_view, I continue with my tactic of creating lexicals and leaving the remaining code alone:

my $time = $self->{world}{time};

Finally, the last line of draw_frame changes again:

$self->{state}{done} = 1
    if $self->{world}{time} >= 5;

The first test run of the completed refactoring uncovered a typo that gave an obscure warning. Thankfully, I only had to check the few changed lines since the last test, and the typo was easily found. With things working again, The Great Global Smashing is complete. The once completely procedural program is now on its way to claiming object orientation. (Boy will I be happy to switch to Perl 6 OO syntax! Perl 6 OO keeps the visual clarity of pure procedural code while gaining several powerful benefits not available in Perl 5. I could fake the clearer syntax with judicious use of source filtering, but that's another article.)

This seems to me like enough refactoring for now, so it's back to the main thrust of development: keyboard control.

The Big Event

Keyboard handling is a special case of SDL event handling, and not an entirely trivial case at that. I'll start with the basic structure for processing SDL events and handle a much simpler event first. To access SDL events, I need to load the SDL::Event module:

use SDL::Event;

Like SDL::App, the code needs to keep track of an SDL::Event resource object to access the event queue. In addition, I need to keep track of which routine I'll use to process each event type. This is a new kind of data, so I add a new branch to the engine object for various lookup tables. To set up both of these, I add a new initialization function:

sub init_event_processing
{
    my $self = shift;

    $self->{resource}{sdl_event} = SDL::Event->new;
    $self->{lookup}{event_processor} = {
        &SDL_QUIT    => \&process_quit,
    };
}

SDL event types are constants in the general SDL constant convention (UPPERCASE with a leading SDL_ marker). The event type for quit events is SDL_QUIT, which I associate with the process_quit routine using a subroutine reference.

A new line at the end of init calls the initialization routine:

$self->init_event_processing;

Every time through, the main loop should process events before updating the view (after I add keyboard control, the view should update using the latest user input). The contents of the loop in main_loop are now as follows:

$self->{state}{frame}++;
$self->update_time;
$self->do_events;
$self->update_view;
$self->do_frame;

do_events is very simple at this stage, just calling process_events to, er, process pending SDL events:

sub do_events
{
    my $self = shift;

    my $queue = $self->process_events;
}

The Event Processing Loop

process_events is where all the magic happens:

sub process_events
{
    my $self = shift;

    my $event  = $self->{resource}{sdl_event};
    my $lookup = $self->{lookup}{event_processor};
    my ($process, $command, @queue);

    $event->pump;
    while (not $self->{state}{done} and $event->poll) {
        $process = $lookup->{$event->type} or next;
        $command = $self->$process($event);
        push @queue, $command if $command;
    }

    return \@queue;
}

The first couple of lines provide shorter names for the previously stored SDL::Event object and event processor lookup table. The rest of the variables respectively store:

• A reference to the processing routine for the current event
• The internal command to convert the event into
• The queue of commands collected from incoming events

The core of the code starts by telling the SDL::Event object to gather any pending operating system events in preparation for the processing loop, using the pump method. The processing loop checks to make sure that a previous event has not flagged the done state, which helps to improve responsiveness to quit events. Assuming that this has not happened, the loop requests the next SDL event using SDL::Event::poll. poll returns a false value when there are no events ready for pickup, thereby exiting the loop.

The first line inside the loop uses the event type to look up the proper event processing routine. If there is none, I use next to loop again and check the next event. Otherwise, the next line calls the processing routine as a dynamically chosen method to handle the event. If the processing routine determines that the event requires additional work, it should return a command packet to be queued. If the event should be ignored, the processor should simply return a false value.

The last line within the loop adds the command packet (if any) to the queue awaiting further processing. Once the loop processes all available SDL events, process_events returns the queue so that do_events can perform the next stage of processing.

It may seem confusing that each time through the loop the code reuses the same $event. You might expect SDL::Event::poll to return the next waiting event (and perhaps undef when none remain). Instead, the SDL API specifies that poll copies the data from the next entry in the event queue into the event object, returning a true or false status indicating whether this operation succeeded. As with some of the OpenGL quirks, SDL_Perl copies this odd interface directly, easing the transition for programmers used to the C API.

A consequence of this interface decision is that the event processing routine must make a copy of any data from the SDL event object needed for later. The call to SDL::Event::poll in the next iteration of the processing loop will overwrite any data left in the SDL event object, so simply storing the object reference won't work.

The process_quit routine doesn't need to save any data; it only matters that an SDL_QUIT event occurred:

sub process_quit
{
    my $self = shift;

    $self->{state}{done} = 1;
    return 'quit';
}

process_quit first sets the done state flag, which causes the loop in process_events to exit early and, more importantly, exits main_loop. It returns the simplest type of command packet, a string indicating the quit command. At this point, there's no code to process this command further, but this keeps things parallel with the keyboard version I'll show next.

What does all this buy us? For starters, we can now (finally) quit the program using the window manager before the animation runs its course. On my system, that means clicking the 'X' on the window's title bar. Still, that's not the same as having a quit key (which I find much more convenient).

Key Binding

To add a quit key, I first need to decide which key should quit the program. I'd choose the Escape key because that makes mnemonic sense to me, but everyone has their favorite, so I'll allow that to be a configuration setting. To do this, I extend the configuration hash with a new bind section:

sub init_conf
{
    my $self = shift;

    $self->{conf} = {
        title  => 'Camel 3D',
        width  => 400,
        height => 400,
        fovy   => 90,
        bind   => {
            escape => 'quit',
        }
    };
}

Now anyone who wants to choose a different quit key can simply change the keyboard bindings hash. In fact, several keys could be associated with the same command, so that either the Escape key or 'q' would exit the program. The hash value corresponding to each specified key is the command packet issued when the user presses that key. This one matches the command packet I'd chosen for the window manager quit message earlier.

Next, I need to process keypress events, which have the event type SDL_KEYDOWN. I add another entry to the event_processor hash:

sub init_event_processing
{
    my $self = shift;

    $self->{resource}{sdl_event} = SDL::Event->new;
    $self->{lookup}{event_processor} = {
        &SDL_QUIT    => \&process_quit,
        &SDL_KEYDOWN => \&process_key,
    };
}

and define the key processor as follows:

sub process_key
{
    my $self = shift;

    my $event   = shift;
    my $symbol  = $event->key_sym;
    my $name    = SDL::GetKeyName($symbol);
    my $command = $self->{conf}{bind}{$name} || '';

    return $command;
}

process_key starts by extracting the key symbol from the SDL event. Key symbols are rather opaque for our purposes, so I request the key name matching the extracted key symbol using SDL::GetKeyName. This produces a friendly key name that I look up in the key bindings hash to find the appropriate command packet. If there is none, no matter; that key isn't bound yet so it yields an empty command packet. process_key then returns the command packet to add to the queue for further processing.

Handling Command Packets

At this point, the code converts a press of the Escape key into a quit command packet, but do_events ignores that packet because it does not process the command queue it receives from process_events. To make something happen, I first need to associate each known command with an action routine. I create a new lookup hash for this association, initialized in init_command_actions:

sub init_command_actions
{
    my $self = shift;

    $self->{lookup}{command_action} = {
        quit      => \&action_quit,
    };
}

As usual, I call this at the end of init:

$self->init_command_actions;

It's now time to fill out do_events:

sub do_events
{
    my $self   = shift;

    my $queue  = $self->process_events;
    my $lookup = $self->{lookup}{command_action};
    my ($command, $action);

    while (not $self->{state}{done} and @$queue) {
        $command = shift @$queue;
        $action  = $lookup->{$command} or next;
        $self->$action($command);
    }
}

This is similar in form to process_events. Instead of processing events from SDL's internal queue to create a queue of command packets, it processes queued command packets into actions to perform. The loop starts as usual by checking that the done is not true and that there are still commands pending in the queue.

Within the loop, it shifts the next command off the front of the queue. The next line determines the action routine associated with the command. If it cannot find one, it uses next to skip to the next command. Otherwise, it calls the action routine as a dynamically chosen method with the command packet as a parameter. This allows a single action routine to process several similar commands while still being able to tell the difference between them. I'll need this later for processing movement keys.

For all of that, action_quit is very simple; it just flags done:

sub action_quit
{
    my $self = shift;

    $self->{state}{done} = 1;
}

At this point, the Escape key really will quit the program early, and the window manager quit still works as well.

Now that the user can quit whenever desired, I can finally remove the incongruous end of draw_frame. It's no longer necessary to force the program to end after five seconds, and the dots printed each frame have outlived their usefulness. The routine now looks like this:

sub draw_frame
{
    my $self = shift;

    $self->set_projection_3d;
    $self->set_view_3d;
    $self->draw_view;
}

Now, if you wait long enough after the objects disappear on the right, the view rotates all the way around, and the scene appears again on the left. This version of the routine is much cleaner and incidently closes the next open refactoring issue (changing engine state within a drawing routine) for free.

Controlling the View

Now that the code can handle keypress events, it's time to control the view using the keyboard.

Instead of having the view completely recalculated every frame, I'd rather have each keypress modify the existing view state. To specify the initial state, I add another initialization routine:

sub init_view
{
    my $self = shift;

    $self->{world}{view} = {
        position    => [6, 2, 10],
        orientation => [0, 0, 1, 0],
        d_yaw       => 0,
    };
}

The new entry, d_yaw, tells update_view if there is a pending change (aka delta, hence the leading d_) in facing. The code so far can only handle yaw (left and right rotation), so that's the only delta key needed right now.

init calls this routine as usual in its new last line:

$self->init_view;

update_view applies the yaw delta to the view orientation, then zeroes out d_yaw so that it won't continue to affect the rotation in succeeding frames (without the user pressing the rotation keys again):

sub update_view
{
    my $self   = shift;

    my $view   = $self->{world}{view};

    $view->{orientation}[0] += $view->{d_yaw};
    $view->{d_yaw}           = 0;
}

A command action assigned to the yaw_left and yaw_right commands updates d_yaw:

sub init_command_actions
{
    my $self = shift;

    $self->{lookup}{command_action} = {
        quit      => \&action_quit,
        yaw_left  => \&action_move,
        yaw_right => \&action_move,
    };
}

To assign keys for these commands, I update the bind hash in init_conf:

bind   => {
    escape => 'quit',
    left   => 'yaw_left',
    right  => 'yaw_right',
}

The big change is the new command action routine action_move:

sub action_move
{
    my $self = shift;

    my $command     = shift;
    my $view        = $self->{world}{view};
    my $speed_yaw   = 10;
    my %move_update = (
        yaw_left  => [d_yaw =>  $speed_yaw],
        yaw_right => [d_yaw => -$speed_yaw],
    );
    my $update = $move_update{$command} or return;

    $view->{$update->[0]} += $update->[1];
}

action_move starts by grabbing the command parameter and current view. It then sets the basic rotation speed, measured in degrees per key press. Next, the %move_update hash defines the view update associated with each known command. If it knows the command, it retrieves the corresponding update. If not, action_move returns.

The last line interprets the update. The view key specified by the first element of the update array is incremented by the amount specified by the second element. In other words, receiving a yaw_left command causes the routine to add $speed_yaw to $view->{d_yaw}; a yaw_right command adds -$speed_yaw to $view->{d_yaw}, effectively turning the view the opposite direction.

With these changes in place, the program starts up looking directly at the scene as it appeared near the beginning of this article. Each press of the left or right arrow keys turns the view ten degrees in the appropriate direction (remember that the scene appears to turn the opposite direction around the view). Holding the keys down does nothing; only a change from unpressed to pressed does anything, and it only rotates the view one increment. This, as they say, is suboptimal.

Angular Velocity

In order to solve this, the code has to change from working purely in terms of angular position to working in terms of angular velocity. Pressing a key should start the view rotating at a constant speed, and it should stay that way until the key is released.

Velocity goes hand in hand with time. In particular, for each frame, update_view needs to know how much time has passed since the last frame to determine the change in angle matching the rotation speed. To compute this time delta, the first change is to make sure the code always has a valid world time by initializing it at program start:

sub init_time
{
    my $self             = shift;

    $self->{world}{time} = now();
}

Of course, this requires another line at the end of init:

$self->init_time;

With this in place, I can change update_time to record the time delta for each frame:

sub update_time
{
    my $self = shift;

    my $now  = now();

    $self->{world}{d_time} = $now - $self->{world}{time};
    $self->{world}{time}   = $now;
}

I've made a few changes that shouldn't affect the behavior of the program, and I'm about to make several more that definitely will change the behavior, so now is a good time for a quick sanity test. All is fine, so it's time to contemplate the design for the remaining code.

Continuing Commands

There are really two classes of keyboard commands that I want to handle:

• Single-shots like quit, drop_object, and pull_pin
• Continuing commands like yaw_left and scream_head_off

To differentiate them, I borrow an existing game convention and use a leading + to indicate a continuing command. This changes the bind mapping in init_conf:

bind   => {
    escape => 'quit',
    left   => '+yaw_left',
    right  => '+yaw_right',
}

and the command_action lookup:

sub init_command_actions
{
    my $self = shift;

    $self->{lookup}{command_action} = {
          quit       => \&action_quit,
        '+yaw_left'  => \&action_move,
        '+yaw_right' => \&action_move,
    };
}

To process the key release events, I need to assign an event processor for the SDL_KEYUP event. I'll reuse the existing process_key routine:

sub init_event_processing
{
    my $self = shift;

    $self->{resource}{sdl_event} = SDL::Event->new;
    $self->{lookup}{event_processor} = {
        &SDL_QUIT    => \&process_quit,
        &SDL_KEYUP   => \&process_key,
        &SDL_KEYDOWN => \&process_key,
    };
}

process_key needs some training to be able to differentiate the two types of events:

sub process_key
{
    my $self    = shift;

    my $event   = shift;
    my $symbol  = $event->key_sym;
    my $name    = SDL::GetKeyName($symbol);
    my $command = $self->{conf}{bind}{$name} || '';
    my $down    = $event->type == SDL_KEYDOWN;

    if ($command =~ /^\+/) {
        return [$command, $down];
    }
    else {
        return $down ? $command : '';
    }
}

The new code (everything after the my $command line) first sets $down to true if the key is being pressed or to false if the key is being released. The remaining changes replace the old return $command line. For continuing commands (those that start with a +), there's a new class of command packet, containing both the $command and the $down boolean to indicate whether the command should begin or end. Single-shot commands (those without a leading +), send a simple command packet only for keypresses; they ignore key releases.

To handle the new class of command packets, I update do_events as well:

sub do_events
{
    my $self   = shift;

    my $queue  = $self->process_events;
    my $lookup = $self->{lookup}{command_action};
    my ($command, $action);

    while (not $self->{state}{done} and @$queue) {
        my @args;
        $command          = shift @$queue;
        ($command, @args) = @$command if ref $command;

        $action = $lookup->{$command} or next;
        $self->$action($command, @args);
    }
}

The only new code is inside the loop. It starts off by assuming that the command packet is a simple one, with no arguments. If the command turns out to be a reference instead of a string, it unpacks it into a command string and some arguments. The $action lookup remains unchanged, but the last line changes slightly to add @args to the parameters of the action routine. If there are no arguments, this has no effect, so a single-shot action routine such as action_quit can remain unchanged.

View, Meet Velocity

The view needs to keep track of the current yaw velocity and the velocity delta when the user presses or releases a key; I initialize them to 0 in init_view:

sub init_view
{
    my $self = shift;

    $self->{world}{view} = {
        position    => [6, 2, 10],
        orientation => [0, 0, 1, 0],
        d_yaw       => 0,
        v_yaw       => 0,
        dv_yaw      => 0,
    };
}

update_view needs a few more lines to handle the new variables:

sub update_view
{
    my $self   = shift;

    my $view   = $self->{world}{view};
    my $d_time = $self->{world}{d_time};

    $view->{orientation}[0] += $view->{d_yaw};
    $view->{d_yaw}           = 0;

    $view->{v_yaw}          += $view->{dv_yaw};
    $view->{dv_yaw}          = 0;
    $view->{orientation}[0] += $view->{v_yaw} * $d_time;
}

After adding any velocity delta to the current yaw velocity, this method multiples the total yaw velocity by the time delta for this frame to determine the change in orientation. This is accumulated with the current orientation and any other facing change for this frame.

Finally, I update action_move to handle the new semantics:

sub action_move
{
    my $self = shift;

    my ($command, $down) = @_;
    my $sign             = $down ? 1 : -1;
    my $view             = $self->{world}{view};
    my $speed_yaw        = 36;
    my %move_update      = (
        '+yaw_left'  => [dv_yaw =>  $speed_yaw],
        '+yaw_right' => [dv_yaw => -$speed_yaw],
    );
    my $update = $move_update{$command} or return;

    $view->{$update->[0]} += $update->[1] * $sign;
}

The $sign variable converts the $down parameter from 1/0 to +1/-1. I changed the last line of the routine to multiply the delta by this sign before updating the value. Adding a negated value is the same as subtracting the original value; this means that pressing a key requires adding the update, and releasing it will subtract it back out.

bind   => {
    escape => 'quit',
    left   => '+yaw_left',
    right  => '+yaw_right',
    tab    => '+look_behind',
}

sub init_command_actions
{
    my $self = shift;

    $self->{lookup}{command_action} = {
          quit         => \&action_quit,
        '+yaw_left'    => \&action_move,
        '+yaw_right'   => \&action_move,
        '+look_behind' => \&action_move,
    };
}

my %move_update      = (
    '+yaw_left'    => [dv_yaw =>  $speed_yaw],
    '+yaw_right'   => [dv_yaw => -$speed_yaw],
    '+look_behind' => [d_yaw  =>  180       ],
);

It's been almost nine years since the first release of mod_perl, and it remains a very powerful tool for writing web applications and extending the capabilities of the Apache web server. However, lurking around the corner is Perl 6, which gives us not only a new version of Perl to embed in Apache but an entirely new runtime engine called Parrot. If there is ever going to be a Perl 6 version of mod_perl, Apache must first be able to run Parrot bytecode. This article introduces mod_parrot, an Apache module that allows the execution of Parrot bytecode from within the web server. Like mod_perl, it also gives your code direct access to the Apache API so you can write your own handlers.

What is Parrot?

Parrot is a virtual machine (VM) optimized for dynamic languages like Perl, Python, PHP, and Ruby. Source code written in each of these languages eventually compiles down to bytecode (after some optimizations), which subsequently runs in a virtual machine. Currently, each language runs bytecode with its own VM, but one of Parrot's goals is to provide a single common VM for all dynamic languages. This makes implementing a new language much easier because there's no need to worry about writing a new VM, and this also makes it possible for code in one language to call code or access data structures from another language.

.sub _main
    # load libc.so, where getpid() is defined, and assign it to $P0
    $P0 = loadlib '/lib/libc.so.6'

    # find the function in the library and assign it to $P1
    # 'iv' means that getpid() returns an integer and takes no arguments
    $P1 = dlfunc $P0, 'getpid', 'iv'

    # call getpid() and place result in $I0
    $I0 = $P1( )

    # print the PID
    print $I0
    print "\n"
.end

.sub puts method, prototyped
    .param string data
    .local pmc r
    .local pmc ap_rputs
    .local int offset

    classoffset offset, self, 'Apache::RequestRec'
    getattribute r, self, offset

    # find NCI object for ap_rputs
    find_global ap_rputs, 'Apache::NCI', 'ap_rputs'

    # use NCI to call out to Apache's ap_rputs
    ap_rputs( data, r )
.end

$ perl Configure.pl --parrot-build-dir=../parrot \
  --apxs=/usr/local/apache2/bin/apxs

Generating Makefile...done.
Creating testing infrastructure...done.

Type 'make' to build mod_parrot.

# this namespace is used to identify the handler
.namespace [ 'HelloWorld' ]

# the actual handler
.sub _handler
    # our Apache::RequestRec object
    .local pmc r

    # this will contain Apache constants
    .local pmc ap_constants

    # instantiate the Apache::RequestRec object
    find_type $I0, 'Apache::RequestRec'
    r = new $I0

    # who should we say hello to?
    $S0 = r.'args'( )
    $I0 = length $S0
    if $I0 > 0 goto say_hello
    $S0 = 'world'

say_hello:
    # call the puts method to send some output
    $S1 = 'Hello ' . $S0
    r.'puts'( $S1 )

    # tell Apache that we're finished with this phase
    find_global ap_constants, 'Apache::Constants', 'ap_constants'
    $I0 = ap_constants['OK']
    .pcc_begin_return
        .return $I0
    .pcc_end_return
.end

$ parrot -o HelloWorld.pbc HelloWorld.imc

# mod_parrot initialization
ParrotInit /path/to/lib/ModParrot/init.pbc
ParrotLoad /path/to/lib/Apache/RequestRec.pbc
ParrotLoad /path/to/lib/Apache/Constants.pbc

# our handler
ParrotLoad /path/to/HelloWorld.pbc

<Location /hello>
    SetHandler parrot-code
    ParrotHandler HelloWorld
</Location>

# this namespace is used to identify the handler
.namespace [ 'TestAuthHandler']

# the actual handler
.sub _handler
    # our Apache::RequestRec object
    .local pmc r
    .local string pw
    .local int status

    # this will contain Apache constants
    .local pmc ap_constants
    find_global ap_constants, 'Apache::Constants', 'ap_constants'

    # instantiate the Apache::RequestRec object
    find_type $I0, 'Apache::RequestRec'
    r = new $I0

    # check the password, ignoring the username
    (status, pw) = r.'get_basic_auth_pw'( )
    if pw != 'squawk' goto auth_failure
    $I0 = ap_constants['OK']
    goto auth_return_status

# authentication failed
auth_failure:
    $I0 = ap_constants['HTTP_UNAUTHORIZED']
    goto auth_return_status

# return our status code
auth_return_status:
    .pcc_begin_return
        .return $I0
    .pcc_end_return
.end

<Directory /usr/local/apache/htdocs/private>
	ParrotAuthenHandler TestAuthHandler
	AuthType Basic
	AuthName Private
	Require valid-user
</Directory>

use Apache::Constants ':common';
use Apache::RequestRec;

sub handler(Apache::RequestRec $r)
{
    my ($status, $pw) = $r.get_basic_auth_pw();
    return ($pw eq 'squawk') ? OK : HTTP_UNAUTHORIZED;
}

Perl Taint Test Kata introduced the idea of Perl Test Kata, small exercises designed to improve your understanding of Perl and your ability to write test-driven code. This article is the second in the series.

Import Testing Kata

Perl 5 added the ideas of namespaces and modules, making code reusable and easier to maintain. To allow convenience, it also added an importing mechanism to put code from a module into the current namespace.

Behind the scenes, when you use a module, Perl loads it from disk and, if successful, calls the special method import(). By convention, this generally imports functions. Much of the time, import() mundanely installs subroutines into the current namespace. That's why so many modules use Exporter to provide a default import().

However, it's also a general module-loading hook that can perform many different types of manipulations. For example, Filter::Simple allows the use of source filters to transform code that looks entirely unlike Perl into valid code in the using module. Other modules change their behavior depending on any arguments passed to import(). This includes Test::More and Test::Simple, which interpret their arguments as information about how many tests to run.

use Test::More 'no_plan';

# or

use Test::More tests => 100;

This feature is both powerful and important. Because of its importance, it needs good tests. Because of its power and flexibility, it may seem difficult to test an import() well. Here are three sample implementations for you to practice testing.

Basic Exporting

package Basic::Exports;

use strict;

use base 'Exporter';
use vars '@EXPORT';

@EXPORT = qw( foo bar );

sub foo { 'foo' }
sub bar { 'bar' }

1;

The tests should check that using Basic::Exports exports foo() and bar() to the appropriate namespace and that they return the appropriate values. Another test is that the code use Basic::Exports (); exports neither function.

Optional Exports

package Optional::Exports;

use strict;

use base 'Exporter';
use vars '@EXPORT_OK';

@EXPORT_OK = qw( foo bar baz );

sub foo { 'foo' }
sub bar { 'bar' }
sub baz { 'baz' }

1;

The tests should check that Optional::Exports exports nothing by default and only those functions named, if there are any.

Load-time Behavior

A few modules have curious behavior. My Pod::ToDemo behaves differently when invoked from the command line versus when used within a module. This makes it substantially more difficult to test. Rather than make you reinvent the tests there, here's a simpler custom import() that does different things based on its invocation. If invoked from the command line, it prints a message to standard output. If used from a module, it exports the same foo() subroutine as before.

package Export::Weird;

use strict;

sub import
{
    my ($package, undef, $line) = caller();

    if ( $line == 0 )
    {
        print "Invoked from command-line\n";
    }
    else
    {
        no strict 'refs';
        *{ $package . '::foo' } = sub { 'foo' };
    }
}

1;

The only really tricky test here must exercise the behavior of the module when invoked from the command line. Assume that the documentation of the module suggests invoking it via:

$ perl -MExport::Weird -e 1

The next page explains some techniques for testing these examples. For best results, spend between 30 and 45 minutes working through the kata on your own before looking at the hints. For more information on how modules, use, and require work, see perldoc perlmod and perldoc perlfunc.

Tips, Tricks, and Suggestions

If you've worked your way through writing tests for the three examples, here are the approaches I would take. They're not the only ways to test these examples, but they do work. First, here is some background information on what's happening.

Reloading

To test import() properly, you must understand its implications. When Perl encounters a use module; statement, it executes a two-step process immediately:

BEGIN
{
    require module;
    module->import();
}

You can subvert both of these processes. To force Perl to reload a module, you can delete its entry from %INC. Note that all of the keys of this special hash represent pathnames in Unix format. For example, even if you use Windows or VMS or Mac OS 9 or earlier, loading Filter::Simple successfully should result in %INC containing a true value for the key of Filter/Simple.pm. (You may also want to use the delete_package() function of the Symbol module to clear out the namespace, though beware of the caveats there.) Now you can require the module again.

Re-importing

Next, you'll have to call import() manually. It's a normal class method call, however, so you can provide all of the arguments as you would to a function or method call.

You can also switch packages, though make sure that you qualify any calls to Test::* module functions appropriately:

package Some::Other::Package;

module->import( @args );

main::ok( 1, 'some test label' );

# or 

::ok( 1, 'some test label' );

Testing Exports

There are at least two techniques for checking the import of functions. One is the use of the defined keyword and the other is through the can() class method. For example, tests for Example #1 might be:

use_ok( 'Basic::Exports' );
ok( defined &foo,              'module should export foo()' )
ok( __PACKAGE__->can( 'bar' ), '... and should export bar()' );

To test that these are the right functions, call them as normal and check their return values.

By the way, the presence of the __PACKAGE__ symbol there allows this test to take place in other namespaces. If you haven't imported the ok() test function into this namespace, remember to qualify it, import it manually, or alias it so that the test program will itself run. (It may fail, which is fine, but errors in your tests are difficult and embarrassing to fix.)

Testing Non-Exports

It's difficult to prove a negative conclusively, but if you reverse the condition of a test, you can have good confidence that the module hasn't provided anything unwanted.

use_ok( 'Optional::Exports' );
ok( ! __PACKAGE__->can( 'foo' ),
    'module should not export foo() by default' );

The only tricky part of the tests here is in trying to import functions again. Call import() explicitly as a class method of the module. Switching packages within the test can make this easier; you don't have to unload the module if you do this.

Testing Weird Exports

The easist way to test an import() function that relies on command-line invocation or produces weird side effects that you may not want to handle in your current program is to launch it as a separate program. There are plenty of options for this, from system to fork and exec to tricks with pipes and shell redirection. IPC::Open3 is one good approach, if you want to use it in your test suite:

#! perl

use strict;
use warnings;

use blib;
use IPC::Open3;

use Test::More tests => 3;

use_ok( 'Export::Weird' );

my $pid = open3(
    undef, my $reader, undef,
    $^X, '-Mblib', '-MExport::Weird', '-e', '1'
);

my @out = <$reader>;
is( @out,                                1,
    'cli invocation should print one line' );
is( $out[0], "Invoked from command-line\n",
    '... with the right message' );

$^X represents the path to the Perl binary currently executing this program. The -Mblib switch loads the blib module to set @INC in the program appropriately. Depending on how you've set up your directories and invoke this program, you may have to change this. The other commands follow the invocation scheme given in Example #3.

Conclusion

You should now have several ideas on how to test import() methods of various kinds. For more details, read the tests of Pod::ToDemo or Test::Builder, which play strange games to achieve good test coverage.

If you've found a differently workable approach, I'd like to hear from you. Also, if you have suggestions for another kata (or would like to write one), please let me know.

All~

Last week I asked for help identifying the source of a quotation. One friendly soul suggested Alan J. Perlis, but could not find an actual attribution. It did lead me to find a very applicable (and in my mind funny) quote from Perlis, which I will now inflict upon you all, before your regularly scheduled summary:

When someone says "I want a programming language in which I need only say what I wish done," give him a lollipop. -- Alan J. Perlis

Perl 6 Language

qq:i

Jim Cromie wondered if there could be a qq:i which sometimes interpolates and sometimes doesn't depending on whether the variable had been previously defined. There was some discussion which led to the conclusion that this was just asking for strange bugs.

Getters and Setters

John Siracusa wanted to know if Perl 6 would allow one to expose a member variable to the outside world, but then later intercept assignments to it without actually having to switch to using getters and setters in all of the code that uses the variable. The answer: yes, yes you can.

<< foo >>

In the summer of 2001, the State University of New York at Buffalo (UB) hired a new Provost. She surveyed various school services and came up with a short list of must-do projects. Given the level of competition in higher education, it's no surprise that she felt that we must be able to accept payments over the internet. In general, we try to make it as easy as possible for students and their parents to manage the business side of their education. Electronic payment is a key, new component of that.

How to Start?

Determining how to accept an electronic payment requires skills from a wide variety of groups on campus. So we first put together a committee with representatives from Accounting, Student Accounts, and some offices that wanted to accept electronic payments. My department, Administrative Computing Services, also sat on the committee since we would have to implement the actual technology. Our role was to work with the people who handled the manual payment system and figure out how to automate that system through the web.

We had no experience taking money over the internet, so we looked at our options:

my $encrypt = new encrypt();

# We had several calls like this one, one for each parameter we
# needed to encrypt.
# Each call returned a string with the encrypted data.
my $vendor_code = $encrypt->send_to_vendor($pay_code);

# CGI code to create a form with the encrypted data as hidden fields.
# The form also acted as a confirmation page, so the user saw
# "Please review your information and click to continue".

# Java code at the bottom of the file.
use Inline ( Java => <<'END_OF_JAVA_CODE',
  import xjava.security.Cipher;
  import cryptix.pgp.*;

class encrypt {
  public encrypt(){
  }

  public String send_to_vendor (String value_string){
      PGP pgpObj = new PGP();

      /* Initialize the object with base values. */
     pgpObj.init("/pgp_dir", "client name", "passwd","sender_key_name");

      /* Add the receiver name to the list. */
      pgpObj.addReceiver("vendor name");

     /* Create the encoded string. */
     String encvalue = pgpObj.encodeString(value_string);

     return (encvalue);
   }
}
END_OF_JAVA_CODE
SHARED_JVM => 1,
CLASSPATH => 'paths to cryptix libraries',
);

All~

Welcome to yet another summary. Although Aliya is present for this summary, I think the unnamed gecko with its tongue out will be the one who is helping to bring it to you, aided of course by Nicola Conte and Massive Attack. Rather than try to do something witty about the strange music I am listening to, or the stuffed animals who are assisting me, I will start this summary off with an entirely self-serving request. <abuse>A while ago I saw the quote, "Computer Science is merely the post-Turing Decline of Formal Systems Theory," without an attribution. I have tried to find an attribution for it, but have been unable to find one. If any of you know it, that information would be appreciated.</abuse>

Without too much further ado, I give you Perl 6 Language.

Perl 6 Language

Return Values from a Substitution

Nicholas Clark wondered what kind of return value the s/// operator would return. Larry provided the answer: a match object that does wicked, smart things based on context (Boston is getting to me).

Deep Operators

Matthew Walton wondered about deep operators and return types. No answer yet, but it is still a little early to call in the awesome forces of Warnock.

Perl 6 Compiler

The race between Google and the compiler is over and Google loses. Badly. While, alas, I do not have a pretty interface, you all have links from nntp.perl.org, plus a nifty infant grammar engine to torture.

Parrot Grammar Engine

Patrick R. Michaud (forever after known as Patrick) released a first version of the Perl 6 Grammar Engine (P6GE). Sometime later, he renamed it the Parrot Grammar Engine, as it will be standard in Parrot and PGE sounds better. He asked for people to poke and prod it. Many people did, with quite some glee. Some work has been done adding it to the Parrot build and making it use Parrot's Configure/make system, as well as some cross-platform cleanups. Patrick also put out a request for tests and explained the basic framework already in place. He also explained his short term plans.

• Initial release
• Cross-platform happiness
• Test explanation
• Plans
• The great renaming

Synopses and Apocalypses

Larry has managed to persuade dev.perl.org to host the latest and most up-to-date versions of the Synopses. Consider the former link deprecated. Larry also mentioned that this should probably wait a little while before it hits Slashdot. Dan put a desperate plea not to also, as "I feel obligated to actually *read* the comments on Parrot and Perl 6 stories on Slashdot, at 0."

Parrot Internals

Having fought my way through the lack of Google, I can now return to its calm, warm tones and convenient threading.

RT Data Extraction

Will Coleda pointed out that he has the mystical power to extract and summarize data from RT automatically. Then he asked for suggestions about how to use this power for good or for awesome.

• The request
• For awesome

Locating Shared Libraries

Adam Warner has some trouble locating shared libraries on Debian. Leo pointed out that Debian apparently names these libraries funny things. The he added support for symlinks and asked Adam to provide the appropriate symlinks.

Double v. Float

Adam Warner played around with the Leibniz summation for pi example, but could not get it to be more precise than 3.1431591. It turns out that the print opcode was at fault and that sprintf worked better. In fact, it allows you to print more precision than you actually have. Ain't life in the floating point world a pain? We should all use integers, where pi is exactly 3.

AIX PPC JIT

The ongoing thread of three-letter acronyms finally seems to have run its course, ending in a climactic upgrade to Perl 5.8.5.

New Calling Scheme Proposal

Leo posted a new, calling scheme proposal. Dan stomped on it hard, then posted an updated version of PPD03 (calling conventions). People spent some time fleshing out every little corner of the new doc.

Parrot BASIC and Perl.org Blacklists

This article is the first in a series aimed at building a full 3D engine. It could be the underlying technology for a video game, the visualization system for a scientific application, the walkthrough program for an architectural design suite, or whatever.

Editor's note: see also the rest of the series, events and keyboard handling, lighting and movement, and profiling your application.

First, I'll set some goals and ground rules to help guide the design. I'm all for agile programming, but even the most agile development process needs some basic goals at the outset:

• I'm not going to make little demos. Early on, the engine won't have much functionality, but it should always be a good foundation for future growth.
• The engine must be portable across architectures and operating systems. I will use OpenGL for 3D rendering and SDL for general, operating system interaction, such as input handling and window creation. The engine itself should contain almost no OS-specific code.
• The engine should be operational at every step of the way, from the very beginning. I will flesh it out over time, and there may be some complex concepts that take some time to work through, but at the very least, every article should end with the whole engine working again.
• I'll leave out most error checking to save space and make the central concepts more clear. For the same reasons, there is no included test library. In your own engine, you will want to have both!
• Don't be afraid to experiment. The best way to learn this stuff is to play with it. Start with what's in the articles and add to it. Any time you spend now will repay itself many times over later, because it's easier to understand advanced topics when you have a solid understanding of the earlier topics.

As a final note before we begin, some versions of SDL_Perl have bugs that will affect the engine. If I know of any issues to watch out for, I'll let you know; conversely, if you find any bugs, let me know, and I'll include a note in a following article.

Getting Started

The first step is to rough out a simple structure and make a runnable program right off. Bear with me; there's a fair bit of code here for what it does, but that will simplify things later on. Here's my starting point:

#!/usr/bin/perl

use strict;
use warnings;

my ($done, $frame);

START: main();

sub main
{
    init();
    main_loop();
    cleanup();
}

sub init
{
    $| = 1;
}

sub main_loop
{
    while (not $done) {
        $frame++;
        do_frame();
    }
}

sub do_frame
{
    print '.';
    sleep 1;
    $done = 1 if $frame == 5;
}

sub cleanup
{
    print "\nDone.\n";
}

The first few lines are the usual strict boilerplate, especially important since I'm working without a net (a test library). Then I declare a couple of state variables (a "done" flag and a frame counter), and jump to the main program.

The main program is pretty simple -- initialize, run the main loop for a while, and then clean up. It's typical of how I structure a potentially complex program. The top-level routines should be very simple, clear, and self-documenting. Each conceptual piece is a separate routine, wherein reside all the gritty bits that actually do the real work. I've seen huge programs (hundreds of thousands of lines) where the main procedures started with several hundred lines of initialization before finally branching to the "real" main body at the end. That style is hard to debug, hard to profile, and just plain hard to understand. I avoid it religiously.

Back to the program at hand. init sets autoflush on STDOUT so that partial lines print immediately, which I use later in do_frame.

The main_loop simply loops until $done is true, producing one finished animation frame per loop. Each loop increments the frame counter and calls the actual routine that does the work, do_frame.

do_frame prints a single dot to indicate a frame has begun, and sleeps for a second. When it wakes up, it checks if five frames have completed, flagging $done if so.

With $done set, main_loop ends and control returns to main, which calls the final cleanup. cleanup just notifies the user of a clean exit and ends.

That's a fair amount of code to print two lines of text (over the course of five seconds) and exit; it doesn't even open a rendering window! I'll do that next.

Creating a Window

First, I need to pull in the SDL and OpenGL libraries:

use SDL::App;
use SDL::OpenGL; 

and add a couple more state variables (a config hash and an SDL::App object):

my ($conf, $sdl_app); 

Initialization

I'm going to do two new types of initialization, so I create routines for them and call them from init:

sub init
{
    $| = 1;
    init_conf();
    init_window();
}

sub init_conf
{
    $conf = {
        title  => 'Camel 3D',
        width  => 400,
        height => 400,
    };
}

sub init_window
{
    my ($title, $w, $h) = @$conf{qw( title width height )};

    $sdl_app = SDL::App->new(-title  => $title,
                             -width  => $w,
                             -height => $h,
                             -gl     => 1,
                            );
    SDL::ShowCursor(0);
}

At this point, init_conf just defines some configuration properties used immediately in init_window, which contains the first real SDL meat.

init_window performs two important actions. First, it asks SDL::App to create a new window, with the appropriate title, width, and height. The -gl option tells SDL::App to attach an OpenGL 3D-rendering context to this window instead of the default 2D-rendering context. Second, it hides the mouse cursor (while it's within the new window's border) using SDL::ShowCursor(0).

Three Phases of Drawing

Now that I have a nice new window, I'd like do_frame to do something with it. I'll start by breaking the rendering into three phases: prepare, draw, and finish.

sub do_frame
{
    prep_frame();
    draw_frame();
    end_frame();
}

For now, draw_frame contains exactly what do_frame used to contain:

sub draw_frame
{
    print '.';
    sleep 1;
    $done = 1 if $frame == 5;
}

The new code is in prep_frame and end_frame; let's look at prep_frame first:

sub prep_frame
{
    glClear(GL_COLOR_BUFFER_BIT);
}

This is the first actual OpenGL call. Before I explain the details, it's worth pointing out the OpenGL naming conventions. OpenGL's design allows it to work with programming languages that have no concept of namespaces or packages. In order to work around this, all OpenGL routine names look like glFooBar (CamelCase, no underscores, gl prepended), and all OpenGL constant names look like GL_FOO_BAR (UPPERCASE, underscores between words, GL_ prepended). In older languages, this prevents the OpenGL names from colliding with names used in other libraries. In the Perl world, this isn't an issue for object-oriented modules. Because OpenGL is not object-oriented, SDL_Perl takes advantage of this convention and simply imports all of the names into the current package when you write use SDL::OpenGL.

Note: If you read OpenGL code written in C, you may notice a short string of characters appended to the routine names, such as 3fv. This convention differentiates variants that have different numbers of parameters or whose parameters are different types. In Perl, values know their own type and a function's parameters can vary in number, so this is unnecessary. The Perl bindings simply drop these extra characters and SDL::OpenGL do the right thing for you.

The OpenGL call in prep_frame clears the rendering area to black by calling glClear -- the general OpenGL "clear a buffer" routine -- with a constant that indicates it should clear the color buffer. As the name indicates, the color buffer stores the color for each pixel and is what the user sees. Several other OpenGL buffers exist; I'll describe those later.

The alert reader may wonder why the code clears the color buffer to black as opposed to white or some other color. OpenGL relies heavily on the concept of current state. Many OpenGL routines do not actually request any rendering, instead altering one or more variables in the current state so that the next rendering command will perform its action differently. When a program prepares to use OpenGL, which SDL::App::new does for us, the current state is set to (mostly) reasonable defaults. One of these state variables is the color to use when clearing the color buffer. Its default is black, which I haven't bothered to override.

The remaining routine is end_frame :

sub end_frame
{
    $sdl_app->sync;
}

This asks the SDL::App object to synchronize the window contents with those held in OpenGL's color buffer, so that the user can see the rendered image. In this case, it's a black window for five seconds.

Something to See

It's time to draw something in that window. To do so, I need to do three things:

1. Choose a projection, so that OpenGL knows how I want to look at the scene.
2. Set the view, so OpenGL knows from which direction to view the scene (the viewpoint) and in which direction I wish to look.
3. Define an object in the scene, placed where the viewpoint can see it.

To start, I need another config setting, so I'll add another line to the $conf hash in init_conf:

        fovy   => 90,

Next, for my three new functions, I add three new calls at the top of draw_frame:

sub draw_frame
{
    set_projection_3d();
    set_view_3d();
    draw_view();

Choose a Projection

set_projection_3d is as follows:

sub set_projection_3d
{
    my ($fovy, $w, $h) = @$conf{qw( fovy width height )};
    my $aspect = $w / $h;

    glMatrixMode(GL_PROJECTION);
    glLoadIdentity;
    gluPerspective($fovy, $aspect, 1, 1000);

    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity;
}

This is the first place you can see an indication of the hard part of 3D graphics simmering below the surface -- math, and lots of it. 3D-rendering code often includes a fairly hefty load of linear algebra (matrix math, for those blocking out their high school and college years) and trigonometry. Thankfully, OpenGL does a lot of that math under the covers. I've also defined a fairly simple projection and view, so this hides a lot of the complexity for now (aside from some of the OpenGL function names).

The first section of the routine defines the viewing projection. In the simplest case, that means choosing whether to use an orthogonal projection or a perspective projection. Orthogonal projections have no foreshortening. They commonly appear in architectural and engineering drawings, because parts that are the same size also appear the same size, no matter where they are in the scene.

Perspective projections are what we see in the real world with our own eyes or with a camera; distant objects appear smaller than near objects. It's also what you learn in a perspective drawing art class, in which the first assignment is commonly train tracks going off to the horizon. Tracks farther from the viewer appear closer together as does the spacing between the ties. To replicate the real world, I've chosen a perspective projection.

In OpenGL, you not only have to decide between an orthogonal or perspective projection, you have to define its basic dimensions. In other words, how much can you see? For a perspective projection, you define the vertical field of view (FOV), the aspect ratio of the view, and the distance to the nearest and farthest things visible.

The vertical FOV ($fovy in the code) defines the angle from the viewpoint to the lowest and highest visible parts of the scene. If you imagine drawing what someone would see if she were standing with her eyes at the viewpoint, this represents her vertical peripheral vision. If you imagine a camera instead, this depends on the focal length of the lens. A telephoto lens has a very small FOV because the angle from the camera to the top and bottom visible objects is very small. Conversely, a wide-angle lens has a large FOV, and the FOV for a fisheye lens is even larger, approaching 180 degrees.

The aspect ratio comes directly from the dimensions of the drawing area (width/height). This allows OpenGL to compensate for the stretching effect of a non-square window. In this case, the drawing area is square, so the aspect ratio is 1.

After calculating the window's aspect ratio, I tell OpenGL that I want to modify the projection and to start from a blank slate, using glMatrixMode(GL_PROJECTION) and glLoadIdentity. I then call gluPerspective to define the desired perspective. You probably noticed that gluPerspective begins with glu instead of gl, like all of the other calls we've seen. This is because I'm using one of the GLU (OpenGL Utility) routines to cover up some complexity in the equivalent raw OpenGL sequence.

Finally, I switch back to model/view mode, and once again start with a blank slate, using glMatrixMode(GL_MODELVIEW) and glLoadIdentity. You may wonder why I don't include this in the next routine instead of doing it here. I like to make sure routines that change a commonly used OpenGL state, simply as a side effect of their main purpose, return that state to the way they found it, especially if there is no net performance effect to doing so. In this case, I switch temporarily to projection mode and then switch back to the default model/view mode.

Set the View

The next step is to move the viewpoint to somewhere we can see the scene:

sub set_view_3d
{
    # Move the viewpoint so we can see the origin
    glTranslate(0, -2, -10);
}

I'm going to skip the detailed explanation for now, but in short the glTranslate call leaves the viewpoint a few units away from (and above) the origin of the scene, where I'll place my objects. I keep the default viewing direction, because it happens to point right where I want it to.

Define an Object

I'm going to start with a pretty simple scene -- just one object:

sub draw_view
{
    draw_axes();
}

sub draw_axes
{
    # Lines from origin along positive axes, for orientation
    # X axis = red, Y axis = green, Z axis = blue
    glBegin(GL_LINES);
    glColor(1, 0, 0);
    glVertex(0, 0, 0);
    glVertex(1, 0, 0);

    glColor(0, 1, 0);
    glVertex(0, 0, 0);
    glVertex(0, 1, 0);

    glColor(0, 0, 1);
    glVertex(0, 0, 0);
    glVertex(0, 0, 1);
    glEnd;
}

The lone object is itself quite simple, just three short lines extending from the origin along the X, Y, and Z axes. (I'm using "line" in the OpenGL sense, as a line segment, not the infinite line of rigorous mathematics.)

In OpenGL, when you want to define something to render, you must notify OpenGL when you begin and end the definition; these are the glBegin and glEnd calls. In addition, you must tell OpenGL what type of primitive you will use to create your object. There are several types of primitives, including points, lines, and triangles. In addition, each primitive type has variants based on how several primitives in a sequence connect (independently, connected in a strip, and so on). In this case, I use GL_LINES, indicating independently placed line segments.

I want each line to be a different color to make it easier to tell which is which. To set the current drawing color, I call glColor with an RGB (Red, Green, Blue) triplet. In OpenGL, each color component can range from 0 (none) to 1 (full). Therefore, (1, 0, 0) indicates pure red, (0, 1, 0) is pure green, and so on. A medium gray is (.5, .5, .5). For further mnemonic value, I assign the colors so that the RGB triplets match the coordinates of the endpoints of the lines -- red for the X axis, green for Y, and blue for Z.

For each line, after defining the color, I define the endpoints of the line using glVertex. Each line begins at the origin and extends one unit along the appropriate axis. In other words, this sequence defines a red line from (0, 0, 0) to (1, 0, 0):

    glColor(1, 0, 0);
    glVertex(0, 0, 0);
    glVertex(1, 0, 0);

With these routines in place, we finally have something to look at! As you can see, the X axis points to the right, the Y axis points up, and the Z axis points out of the screen toward the viewer (with OpenGL foreshortening it). Note the delay before the object first appears; that's because the sleep at the end of draw_frame creates a pause before end_frame syncs the screen with the drawing area.

Moving Boxes Around

Next, let's try a box. Anyone who's played a First Person Shooter game knows that their worlds have a surplus of boxes (a.k.a. "crates," "storage containers," and so on ?- oddly, for storage containers, the larger they are, the less they seem to contain). I'll start with a simple cube and add another call for it to the end of draw_view:

sub draw_view
{
    draw_axes();
    draw_cube();
}

Defining the Cube

Here's the code that actually draws the cube:

sub draw_cube
{
    # A simple cube
    my @indices = qw( 4 5 6 7   1 2 6 5   0 1 5 4
                      0 3 2 1   0 4 7 3   2 3 7 6 );
    my @vertices = ([-1, -1, -1], [ 1, -1, -1],
                    [ 1,  1, -1], [-1,  1, -1],
                    [-1, -1,  1], [ 1, -1,  1],
                    [ 1,  1,  1], [-1,  1,  1]);

    glBegin(GL_QUADS);
    foreach my $face (0 .. 5) {
        foreach my $vertex (0 .. 3) {
            my $index  = $indices[4 * $face + $vertex];
            my $coords = $vertices[$index];
            glVertex(@$coords);
        }
    }
    glEnd;
}

That looks pretty hairy, but it's actually not bad. The @vertices array contains the coordinates for a cube two units on a side, centered at the origin, with its sides aligned with the X, Y, and Z axes. The @indices array defines which four vertices belong to each of the six faces of the cube and in what order to send them to OpenGL. The order is very important; I've arranged it so that, as seen from the outside, the vertices of each face draw in counterclockwise order. Using a consistent order helps OpenGL to determine the front and back side of each polygon; I've chosen to use the default counterclockwise order.

After defining those arrays, I mark the beginning of a series of independent quadrilateral primitives using glBegin(GL_QUADS). I then iterate through each vertex of each face, finding the correct set of coordinates and sending them to OpenGL using glVertex. Finally, I mark the end of this series of primitives using glEnd.

Colloquial Perl purists will no doubt wonder why I have chosen C-style loops (with the attendant index math, yuck), rather than making @indices an array of arrays. Mostly I'm just showing that it's not too hard to deal with this type of input data. When the engine reads object descriptions from files, rather than hand-coded routines, the natural output of the file parser may be flattened. It's often easier to do a little index math than to force the parser to output more structured data (and possibly more efficient too, but that's a clear call for benchmarking).

The result is one blue cube. Why blue? Since I never specified a new color to use, OpenGL went back to the current state and looked up the current drawing color. The last line in the axes was drawn in blue and that's still the current color. Hence one blue cube.

Two Colored Boxes

Let's fix that. At the same time, we can move the new cube out of the way of the axes so we can see them again. Heck, I'll go all out and have two cubes -- one to the left of the axis lines, and one to the right. The nice thing is that because I'm just drawing more of something I've already described, I just need to change draw_view:

sub draw_view
{
    draw_axes();

    glColor(1, 1, 1);
    glTranslate(-2, 0, 0);
    draw_cube();

    glColor(1, 1, 0);
    glTranslate( 2, 0, 0);
    draw_cube();
}

Now I set the current color to white using glColor(1, 1, 1) before drawing the first cube, and to yellow using glColor(1, 1, 0) before drawing the second cube. The glTranslate calls should place the first cube two units to the left (along the negative X axis) and the second cube two units to the right (along the positive X axis).

Cumulative Transformations

Unfortunately, no dice. The white cube is two units to the left, but the yellow cube is right on top of the axis lines again, not two units to the right as intended. This happened because glTranslate calls (and the other transformation calls I'll show later) are cumulative. Unlike routines such as glColor that simply set the current state, most transformation calls instead modify the current state in a certain way. Because of this, the first cube starts at (-2, 0, 0), and the second starts at (-2, 0, 0) + (2, 0, 0) = (0, 0, 0) -- right back at the origin again.

The solution to this problem requires peeking under the covers a little bit. OpenGL transformation calls really just set up a special matrix representing the effect that the requested transformation has on coordinates. OpenGL then multiplies the current matrix by this new transformation matrix and replaces the current matrix with the results of the multiplication.

What I need to fix this problem is some way to save the current matrix before performing a transformation, and then restore it after I'm done with it. Thankfully, OpenGL actually maintains a stack of matrices of each type. I just need to push a copy of the current matrix onto the stack before drawing the white cube, and pop that copy off again afterwards to get back to the state before I did my translation. I'm going to do this for both cubes:

sub draw_view
{
    draw_axes();

    glColor(1, 1, 1);
    glPushMatrix;
    glTranslate(-2, 0, 0);
    draw_cube();
    glPopMatrix;

    glColor(1, 1, 0);
    glPushMatrix;
    glTranslate( 2, 0, 0);
    draw_cube();
    glPopMatrix;
}

That's a bit better. The yellow cube now has its origin at (2, 0, 0), just as intended.

Other Transformations

Earlier I referred to other transformation calls; let's take a look at a few of them. First, I'll scale the boxes (change their size). I'm going to scale the left (white) box uniformly -- in other words, scaling each of its dimensions by the same amount. To show the difference, I'll scale the right (yellow) box non-uniformly, with each dimension scaled differently. Here's the new draw_view:

sub draw_view
{
    draw_axes();

    glColor(1, 1, 1);
    glPushMatrix;
    glTranslate(-4, 0, 0);
    glScale( 2, 2, 2);
    draw_cube();
    glPopMatrix;

    glColor(1, 1, 0);
    glPushMatrix;
    glTranslate( 4, 0, 0);
    glScale(.2, 1, 2);
    draw_cube();
    glPopMatrix;
}

For the white box, I just doubled each dimension; the parameters to glScale are X, Y, and Z multipliers. For the yellow box, I shrunk the X dimension by a factor of 5 (multiplied by .2), left Y alone, and doubled the Z dimension. The boxes are now big enough that I've also pushed them farther apart, hence the updated values for glTranslate that place them four units on either side of the scene origin.

Watch the Rotation

I've done translation and scaling; next up is rotation. To save space here, I'll demonstrate on the yellow cube alone. Here's the new code snippet:

    glColor(1, 1, 0);
    glPushMatrix;
    glRotate( 40, 0, 0, 1);
    glTranslate( 4, 0, 0);
    glScale(.2, 1, 2);
    draw_cube();
    glPopMatrix;

The parameters to glRotate are the number of degrees to rotate and the axis around which to do the rotation. In this case, I chose to rotate 40 degrees around the Z axis (0, 0, 1). The direction of rotation follows the general pattern in OpenGL -- a positive value means counterclockwise when looking down the rotation axis toward the origin.

Order of Transforms

This produces a flying yellow box in the upper-right quadrant. Remember when I said that each new transformation is cumulative? The order matters. To understand why, I like to imagine each transformation as moving, rotating, or scaling the coordinate system in which I draw my objects. In this case, by rotating first, I certainly rotated the box, but I really rotated the entire coordinate system in which I defined the box. This meant the glTranslate call that immediately follows the rotation translated out along a rotated X axis, 40 degrees above the scene's X axis, to be precise.

I'll move the rotation after the other two transformations to fix that:

    glTranslate( 4, 0, 0);
    glScale(.2, 1, 2);
    glRotate( 40, 0, 0, 1);

Now the box isn't flying, but it does appear squashed in an odd way. The problem here is that because the nifty, non-uniform scaling happens before the rotation, I'm now trying to rotate through a space where the dimensions are different sizes. Putting the rotation in the middle fixes it:

    glTranslate( 4, 0, 0);
    glRotate( 40, 0, 0, 1);
    glScale(.2, 1, 2);

If you compare this rendering from this version with the program with no glRotate call, you should see that it does the right thing now.

Whoa, Deep!

The last item I wanted to bring up is what to do when something near the back draws after something near the front. To see what I mean, I'll move the white box so that instead of being four units to the left of the scene origin, it is four units behind it (along the negative Z axis). That merely involves changing the white box's glTranslate call from this:

    glTranslate(-4, 0, 0);

to this:

    glTranslate( 0, 0, -4);

As you can see, even though the white box should appear behind the axis lines, it instead appears in front because OpenGL drew it after the axis lines. By default, OpenGL assumes you intended to do this (it is more efficient to make this assumption), but I didn't. To fix this, I need to tell OpenGL to pay attention to the depth of the various objects in the scene and not to overwrite near objects with far ones.

To do this, I need to enable OpenGL's depth buffer. This is similar to the color buffer, which stores the color of every pixel drawn. Instead of storing the color, however, it stores the depth (distance from the viewpoint along the viewing direction) of every pixel. Just like the color buffer, I need to clear the depth buffer each frame. Instead of clearing it to black, OpenGL clears it to the maximum depth value, so that any later rendering within the visible scene will be closer.

I also need to tell OpenGL that it should perform a test each time it wants to draw a pixel, comparing the depth of the new pixel with what's already in the depth buffer. If the new pixel is farther from the viewer than the pixel it is about to replace, it's safe to ignore the new pixel and to leave alone the old color. Here's the updated prep_frame:

sub prep_frame
{
    glClear(GL_COLOR_BUFFER_BIT |
            GL_DEPTH_BUFFER_BIT );

    glEnable(GL_DEPTH_TEST);
}

In this version, I tell glClear to clear both the color buffer and the depth buffer. You can now see why the constant names end with _BIT; they are, in fact, bit masks. The reason for this odd interface is purely efficiency -- some OpenGL implementations can very rapidly clear all requested buffers simultaneously, and making the request for all needed buffers in just one call allows this optimization. As for the choice of bit mask rather than a list of constants, SDL_Perl reflects the underlying C interface, so that people comfortable with that can more easily cross over to using OpenGL under Perl.

The second routine I call, glEnable, is actually one of the most commonly used OpenGL routines, despite the fact that this is the first we've seen of it. Much of the OpenGL current state is a set of flags that tell OpenGL when to do (or not do) certain things. glEnable and the corresponding glDisable set these flags as desired. In this case, I turn on the flag that tells OpenGL to perform the depth test, throwing away pixels drawn in the wrong order.

With these changes, we can now once again see the axis lines, this time in front of the white box where they belong.

Conclusion

The final results may look simple, but we've come a long way. I started with some basic boilerplate and a simple main loop. I didn't even load SDL or OpenGL or open a window. By the end, I'd added a window to draw on; projection and viewing setup; multiple objects of different types, built using different OpenGL primitives, drawn in different colors, and transformed several different ways; and correct handling of out-of-order drawing.

That's a lot for now, but we're just starting. Next time I'll cover moving the viewpoint, SDL keyboard handling, and compensating for frame rate variations. I'll build on the example source code built in this article, so feel free to download it and use it for your own applications.

In the meantime, if you'd like to learn more visit the OpenGL and SDL websites; each contains (and links to) mountains of information.