Tutorial 1: Turn It On

Boiler plate code
Required assets
Memory model of the high level pieces

One measure of the useability of a library is how much boilerplate code it takes to get it going. SDL, Lilith, and OpenGL combined are about 20 lines of code - I feel pretty good about that. Hopefully the coding part of getting Lilith3D up and running will be easy good.

If you are building from the provided Makefile or Project file, it is pretty straighforward. When building from your own code, paths can be tricky. Read the the windows and linux setup.

All the required resources, and some extra, are supplied with the source distribution.

Also, with v1.4+, be sure you have "using namespace grinliz" and "using namespace lilith3d" at the top of your cpp files in order to use the Grinning Lizard Utilities.

The Coordinate System

From the point of view of the terrain, Z is up. Positive X is due East. Positive Y is due North. 0 degrees around the Z aris is the direction of the positive X axis (East).

Tutorial 1: Initialize SDL and Initialize Lilith

Note that error checking has been removed for the sake of readability in the tutorials. I suggest, strongly, you add it back in.

Basic SDL initialization is left up to you. At a minimum, you should use the following flags:

SDL_Init( SDL_INIT_VIDEO | SDL_INIT_NOPARACHUTE | SDL_INIT_TIMER )

Your game may need additional SDL initialization tags as well. You can initialize the video surface yourself - but it's easier to let Lilith3D do the work for you.

SDL_Surface* surface = Lilith3D::SetSDLVideoMode( SCREEN_WIDTH, SCREEN_HEIGHT, 0, false );

And then finally the following:

InitLilith3D();

Initializes the Lilith OpenGL system, which loads extensions Lilith requires. This must preceed all Lilith code.

Tutorial 1: Textures and Models

So after initializing the basic graphics systems, we load textures and models. Resources before anything else? Okay...granted, that's a bit odd. Lilith likes to pre-load all textures and models. You don't have to, but there's no way to unload...so generally everything that is needed for a instance of the engine is loaded before the engine.

But we just want to display the simplest possible thing...why textures and models? The terrain renderer actually needs them to render the basic world. These are easily loaded with utility calls to bring everything in.

 ResourcePool* resourcePool = new ResourcePool();
 resourcePool->SetImportPath( "../graphics/" ); 
 resourcePool->LoadRequiredAssets();

 resourcePool->SetImportPath( "../grdemo/" );

The first lines gets a pointer to the ResourcePool. The second line sets the location of the assets used by the engine. LoadRequiredAssets() brings in the engine assets, after which the import path is changed from the location for the required graphics to the location for the demo graphics.

Lilith supports a wide range of image source formats for textures - anything that can be loaded by SDL_image.

Textures can be 24 bit (or lower) without alpha channel, and alpha channel is fully supported for 32 bit images.
Textures should be square and a power of 2. Typically 64x64, 128x128, etc.

Tutorial 1: Engine Initialization

Lilith3D* lilith = new Lilith3D();

Yeah! The engine is created. Note that nothing is displayed on the screen yet. That comes in:

Tutorial 1: Event Loop

Pretty much a standard SDL event loop, written so it never waits on events. "Escape" or closing the window will exit the loop. The loop I won't go in to - check out SDL.

However, this bit at the end:

 lilith->BeginDraw();
 lilith->Draw();
 lilith->EndDraw();
SDL_GL_SwapBuffers();

is critical as you might imagine. The 3 draw functions well...draw. They take everything that happens and put in on the screen. (There are advanced uses for instructions between the 3 draws, but we won't get in to that.) The final SDL_GL_SwapBuffers() commits the back buffer to your monitor.

We then sneak in an empty 'Game' object that we'll build up in the tutorials to follow.

Tutorial 1: Cleanup

We're almost ready to go. After the loop completes, we should free resources. This occurs in opposite order of construction.

delete the Game object
delete the Lilith object
delete the ResourcePool.
call SDL_Quit to shut down SDL.

Conclusion

And you're done! That's a simple, complete working program.

Compile it, run it, and check out: One silly looking mountain and a completely immobile camera wade endlessly through time.

It's a good place to start from.