Lesson 00 - Initializing And Shutting Down The Engine

 *//* 

This lesson will show you how to initialize the basic systems needed by XuqRijBuh -- initializing video mode and Singleton and shutting down. If you're reading the source file directly, instead of the doxygen-generated document, then pay no attention to the "code" and "endcode" tags in each comment.

• This lesson's source code
• Main lesson index

Procedural Overview

• Main function
  • Initialization (video, sound, and whatever else is needed).
  • Initialize game engine singletons (necessary for correct operation of the game engine).
  • Create the Screen object. This is what sets the video mode.
  • Execute game-specific code.
  • Delete the Screen object. This does NOT reset the video mode.
  • Shutdown game engine singletons (necessary for correct operation of the game engine).
  • Shutdown (this is what resets the video mode).

Code Diving!

To start off, the "xrb.hpp" header MUST be included in every source and header file, as it contains definitions necessary for the correct usage and operation of the game engine.

 */
#include "xrb.hpp"

#include "xrb_screen.hpp" // For use of the necessary Screen widget class.
#include "xrb_sdlpal.hpp" // For use of the SDLPal platform abstraction layer.

/* 

Every declaration in the game engine library is within the Xrb namespace. Although this is pedantic, it is used to avoid any possible naming collision. It turns out not to be inconvenient, because of C++'s using keyword. This using statement is used so we don't need to qualify every library type/class/etc with Xrb::

 */
using namespace Xrb;

// This is just a helper function to group all the shutdown code together.
void CleanUp ()
{
    fprintf(stderr, "CleanUp();\n");

    // Shutdown the platform abstraction layer.
    Singleton::Pal().Shutdown();
    // Shutdown the game engine singletons.  This is necessary for the
    // game engine to shutdown cleanly.
    Singleton::Shutdown();
}

int main (int argc, char **argv)
{
    fprintf(stderr, "main();\n");

    /* 

This call initializes the game engine singleton facilities. This must be done, or the engine will just not work. The singletons include:

• ResourceLibrary ensures that we only load one copy of certain resources (textures, fonts, sounds, etc) into memory.
• InputState provides accessors for the immediate state of the keyboard and mouse (and eventually joysticks, etc). This is not the primary or only means for user input, but we'll get to that later.
• KeyMap performs keyboard layout mapping (e.g. Dvorak), which is necessary only on Windows builds because the Windows version of SDL lacks proper key mapping.
• FTLibrary is used transparently by the font system to use the FreeType font rendering facilities (assuming SDLPal is in use). There's nothing to worry about. Trust me.

 */
    Singleton::Initialize(SDLPal::Create, "none");

    /* 

Initialize the platform abstraction layer (Pal). Then set the window caption.

 */
    if (Singleton::Pal().Initialize() != Pal::SUCCESS)
        return 1;

    Singleton::Pal().SetWindowCaption("XuqRijBuh Lesson 00");

    /* 

This call creates the Screen object and initializes the given video mode (800x600, 32 bit color). There is no constraint on the size or aspect ratio of the screen, apart from the ability of your video hardware to handle it. The Screen object is the root widget of the GUI widget hierarchy, and does a bunch of special handling to draw its child widgets properly.

 */
    Screen *screen = Screen::Create(
        800,    // video mode/screen width
        600,    // video mode/screen height
        32,     // video mode pixel bitdepth
        false); // not fullscreen -- for now
    /* 

If the Screen failed to initialize for whatever reason (probably because the system was unable to set the video mode), screen will be NULL. If this happens, print an error message and quit with an error code.

 */
    if (screen == NULL)
    {
        // this shuts down the Pal and singletons.
        CleanUp();
        // return with an error value.
        return 2;
    }

    /* 

Here is where the game code goes. To avoid overloading your brain, for now we'll just pause for 5 seconds.

 */
    {
        fprintf(stderr, "pausing for 5000 milliseconds...\n");
        Singleton::Pal().Sleep(5000);
    }

    /* 

Delete the Screen object, and with it the entire GUI widget hierarchy.

 */
    Delete(screen);
    // this shuts down the Pal and the singletons.
    CleanUp();
    // return with success value.
    return 0;
}
/* 

Exercises

• Change the last parameter passed to Screen::Create -- currently false -- to true. This will cause the application to be run in fullscreen mode. Make sure not to use fullscreen mode while developing/debugging, because hitting a breakpoint while in fullscreen video mode will make your computer a touch ornery.
• With the last parameter to Screen::Create set to true (indicating fullscreen is enabled), change the video mode width, height and bitdepth to various values, seeing what video modes are supported by your hardware.
• Write code that parses the commandline arguments so you can specify what video mode width, height and bitdepth to use from the commandline.

Thus concludes lesson00. Did it hurt? The fuck it didn't.