Spritelib: Dr. Lawlor's Simple 2D Game Library

Dr. Lawlor, CS 202, CS, UAF

There's only one std::cout, but are many, MANY different libraries you can call to get graphical user interfaces.  I've got a big table here, with a little more detail here.

For this class, I wanted to build you guys a very small, simple library to dump out 2D images.  It's called "spritelib".

You can download "spritelib" and a demo game as a Zip or Tar-gzip archive.  To run it on Windows, just unzip and run "main.exe" (it should run anywhere).  To build it on Windows, the easiest approach is just to double-click "main.vcproj"; if you want to build your own project, you'll need to set the include path to include "." (the current directory), and link with freeglut.lib.  On Linux or Mac OS X, there's a Makefile included that should work.

Using Spritelib

There's not much to it.  Start with:

    #include "spritelib/spritelib.h"
    #include "spritelib/spritelib.cpp"

Yes, it's a little weird to just #include another .cpp file.  But this keeps you from having to add the .cpp file to your project, so I don't have to mess with your compiler!

From your main function, you need to call spritelib_run with the window title and size.  This function keeps handling user events forever, and never returns:

    int main() {
        spritelib_run("Sprite Invaders!",800,600);
    }

The basic task of any graphical program is to draw stuff on the screen.  So you need to write this *one* function, which spritelib will call over and over again to draw or animate stuff on the screen:

    void spritelib_draw_screen(spritelib &lib) {
         // draw the screen and respond to user input here
    }

To actually draw stuff on the screen, you use functions from that "spritelib" object.  To read in a texture, use "lib.read_tex".  The only parameter is a filename for the image to read:

        static spritelib_tex sunset=lib.read_tex("sunset.jpg");

Now to draw stuff on the screen, use "lib.draw".  The parameters are: the texture to draw, the x,y coordinates of the center of the rectangle to draw (in pixels, y points down), and the width and height of the rectangle to draw.  There is also an optional rotation angle parameter (in degrees), and a boolean if you want "glow" mode with additive blending instead of just overwriting old pixels.

        lib.draw(sunset, // texture to draw
                300,200, // center point (x,y)
                100,100); // size (w,h)

That's the *only* drawing function there is!  You load up your textures (ideally into statics, so you don't have to re-load them every frame) and draw them onscreen.  That's all there is.

Reading User Data

You can pull a huge amount of user interface information from the spritelib object.  For example, the coordinates of the mouse are at "lib.mousex" and "lib.mousey".  The size of the screen is "lib.screenw" (horizontal size, along x axis) and "lib.screenh" (vertical size, along y axis).  The left mouse button is pressed if "lib.mouseleft" is true, and ditto for "lib.mouseright".

See "spritelib/spritelib.h" for the complete list of stuff inside spritelib.  About the only thing I don't currently provide is arrow or function keys on the keyboard.

Design of spritelib

Spritelib is actually a very simple library.  It's built on top of the standard graphical drawing library OpenGL, which does the rendering.  It uses the Simple OpenGL Image Library "SOIL" to load the images.  Finally, to open windows and read the mouse and keyboard position, spritelib calls GLUT.  One nice thing is that all three of these libraries run on *every* desktop platform: Windows, Mac, Linux, or even weirder older UNIX machines.

Spritelib was a one-night project, so you definitely shouldn't feel constrained by its missing features--either just add 'em, or find a new library!  In particular, if you need sound output and joystick input, a game library like SDL would work better.  If you need menu bars, buttons, and dialog boxes, a full-blown GUI library like Qt would work better.