01: Minimal Gel2D Application

This tutorial will show you the simplest and quickest way to set up a Gel2D app.

First, include the Gel2D Basics header; this will give you access to most of the common Gel2D classes.
We're also going to use the gel namespace, which will save use the trouble of having to qualify all of our objects with gel.

#include <gel2d/Basics>

using namespace gel;

Next comes the all familiar program entry point.
The integer running will be used later as the conditional variable for the game loop.

int main(int argc, char *argv[])
{
    bool running = true;

Before calling any Gel2D functions, you should start the game engine by calling start() from the GelEngine class. All member functions in GelEngine are static, so it's easier to call the functions directly instead of creating a needless object.

    GelEngine::start();

Now we create our window. Just like GelEngine, all member functions in GelWindow are static.
If you're feeling lazy, you can call createWindow() without any parameters at all, as they are set to reasonable defaults.
The following code snippet fills out all possible parameters, which include the window's title, width, height, bpp, mode, and style.

    GelWindow::createWindow("Minimal Gel2D Application", 800, 600, 32, GEL_WINDOWED, GEL_WND_MIN );

Create a timer. This timer will be used in the game loop to lock the fps (frames per second) to a fixed rate.

    GelTimer timer;

This is an object you will be using a lot: GelSprite. It is more or less the equivalent of what is conventionally referred to as a sprite, and it is the most common way to get a graphic rendered to the screen.

If you browse the API docs, you'll notice that GelSprite is a type of GelObject, as is most of the other renderable objects that you will be using on a regular basis. This gives them all a common base of functions such as setting position, rotation, and scaling; which, needless to say, is very useful in polymorphic situations.

Here is the most common way to instantiate a sprite: specify the size, position, and rotation. Dimensions and coordinates are in pixels, rotation is in degrees.

    GelSprite sprite(Gel2dVec(128, 128), Gel2dVec(400, 300), 0);

Without a texture, the sprite will just be drawn a flat color.

Create a new texture, with the directory of the image you want to use, and the file format of the image. In this case we're using a PNG image, so we fill out the 2nd parameter with IMG_PNG.
Apply the texture to the sprite by calling setTexture() with the address of the new texture you created as the parameter.

    GelTexture tex("./media/lyteStudio.png", IMG_PNG);
    sprite.setTexture(&tex);

We'll need a camera to orient our scene when the time comes to render.

    GelCamera cam;

Finally, we can start the game loop!
We use the standard while loop with the variable running that we created earlier.

    while( running )

Remember the timer we created earlier?
Call setFPS() from it with the frame rate that you want. 60 frames per second is fairly common.

        timer.setFPS(60);

What this function does is it measures the fps and the time since the last frame (frame delta). It then takes into account how many frames per second you want, and compensates accordingly by sleeping for a small amount of time.
Locking the fps is fairly important. Without it, your computer would just render as fast as it could, causing the frame rate to fluctuate drastically. It would also put a lot of needless strain on your CPU, which would be especially bad for laptops and mobile devices.

Now it's time to render the scene.
Call render() from the camera to orient the scene, then render the sprite.

        GelEngine::getRenderSystem()->beginScene();
        cam.render();
        sprite.render();
        GelEngine::getRenderSystem()->endScene();

Now you should poll for events.
This function call polls for events for the window, input, etc. Very important.

        GelWindow::pollEvents();

And now another very important line. This is where we're given the opportunity to terminate the game loop.
There are many different ways to do this, but here's a common one.

        running = !GelInput::keyPressed(GEL_KEY_ESC) && GelWindow::getParam(GEL_WND_OPEN);

The preceding code snippet gives the variable running the value returned by the state of the escape key and window. If the escape key is pressed, the function keyPressed() will return true, so it is reversed to give the opposite effect by using the ! operator. That means when the escape key is pressed, it will give running the value false, which will terminate the game loop.
Similarly, if the window is still open, getParam(GEL_WND_OPEN); will return true; if not, the game loop will be terminated.

More information on input handling will be made available in another tutorial.

Once the game loop has been terminated, you should shutdown the engine.

    GelEngine::shutdown();

Congratulations!

You've learned the basics to setting up a game environment with Gel2D.
However, you should know that this is not always the best way to write a game.
A more powerful and object-oriented approach is available using the GelAppBase; but that's a tutorial for another day. :-)

source code:

main.cpp

#include <gel2d/Basics>

using namespace gel;

int main(int argc, char *argv[])
{
    bool running = true;

    // Start up the game engine
    GelEngine::start();

    // Create a new window
    GelWindow::createWindow("Minimal Gel2D Application", 800, 600, 32, GEL_WINDOWED, GEL_WND_MIN );

    // Create a timer
    GelTimer timer;

    // Create a new sprite
    GelSprite sprite(Gel2dVec(128, 128), Gel2dVec(400, 300), 0);

    // Create a new texture
    GelTexture tex("./media/lyteStudio.png", IMG_PNG);
    sprite.setTexture(&tex);

    // Setup camera
    GelCamera cam;

    // Game loop
    while( running )
    {
        // Lock FPS
        timer.setFPS(60);

        // Render scene
        GelEngine::getRenderSystem()->beginScene();
        cam.render();
        sprite.render();
        GelEngine::getRenderSystem()->endScene();

        // Poll for events
        GelWindow::pollEvents();

        running = !GelInput::keyPressed(GEL_KEY_ESC) && GelWindow::getParam(GEL_WND_OPEN);
    }

    // Clean up and shut down
    GelEngine::shutdown();
}

01: Minimal Gel2D Application

See Also:

Prerequisites:

Skill Level:

This tutorial will show you the simplest and quickest way to set up a Gel2D app.

Congratulations!