---

the Grand Unified 3D Game Engine

0.3.0

Concepts

The Grand Unified 3D Game Engine (GAUGE) is more that just a game engine. Many of the underlying classes in GAUGE actually change the way things are programmed at a low level. Before you can dive into the GAUGE class specifications, you should go over these basic concepts.

Smart Pointers

GAUGE makes extensive use of smart pointers. These are pointers which automatically detect when an object is no longer in use and delete it for you. These are somewhat similar to Java pointers, but have some key differences that you need to be aware of.

Here's an example:

GSmartPointer<int> ptr;
ptr = NEW int;
ptr = NULL;

Now, if ptr was just an int*, the above would be a memory leak. The smart pointer, on the other hand, detects that the int is no longer in use, and deletes it automatically. Other than that, a smart pointer works exactly like a regular pointer.

GSmartPointer works through reference-counting. Every object has an integer reference count associated with it. This integer is stored in the four bytes preceding the object, and is allocated automatically by GAUGE's operator new. The reference count starts at zero. Once you set a GSmartPointer to point at that memory chunk, the reference count is incremented. When the GSmartPointer is set to point at something else, the reference count is decremented. If it hits 0 again, the object is deleted.

There are several things to watch out for when using smart pointers:

• Once an object has a smart pointer pointing at it, it's stuck in the smart pointer system. To keep things organized, you should avoid situations where both a smart pointer and a normal pointer point at the same object.
• Do not set a smart pointer to any address which was not at some point returned by operator new. Obviously, such addresses do not have reference counts and can not be deleted, so the program will crash or memory corruption will occur if you do this.
• Circular links are not detected. So, if you have two objects which contain smart pointers pointing at each other, they will never be deleted, even if no other part of the program points at them. This is different from Java.
• The speed of GSmartPointer has not been measured, but it is definately slower that using regular pointers. I do not believe that the speed difference is very large, but you should still use regular pointers whenever it is reasonable to do so.

The main reason to use smart pointers is that you no longer have to worry about who has to delete what. You can have functions which return pointers to objects without any problems.

For example, GDirectory is a class which represents a directory. One of the functions of GDirectory, OpenFile(), returns a smart pointer to a GFile. Now, if GAUGE did not have smart pointers, the function would have to return a normal pointer to a file. Then, you have a problem: Who's responsibility is it to delete the file?

As it turns out, some subclasses of GDirectory will return the same pointer if you open the same file multiple times. So, if the caller were to delete the file, it would cause other parts of the engine to crash if they attempted to access the same file. So, clearly, GDirectory would have to maintain control over when the file is deleted. This means that it would have to have another function, CloseFile(GAUGE3D::GFile GFile* file).

Having to call the GDirectory again to close a file can be a huge problem. For example, say you load up a file, and then pass it on to another class to be processed. Then, you would have to find out from that class when the file needs to be deleted.

The solution to all of this is smart pointers. GDirectory::OpenFile() returns a smart pointer to a GFile. This way, no one has to worry about who has to delete the file. If the directory does not want the file to be deleted, it simply keeps a smart pointer to that file. No CloseFile() function is necessary.

One last note: Writing out "GSmartPointer<MyObject>" can get annoying very quicly. In GAUGE, we use the convention of typedef'ing type names with a prefix of 'p' as being a smart pointer to that object. So, in the header file that defines "MyObject", you'd see this:

typedef GSmartPointer<MyObject> pMyObject;

Using pMyObject makes code much more readable and easier to type.

Plugins

GAUGE makes extensive use of plugins. A plugin is a program module which is dynamically loaded through an external shared library (DLL). The advantage of using plugins is that you can add functionality to the engine without actually editing or re-compiling GAUGE itself.

GAUGE uses plugins to support various file formats. For example, there is a plugin to load 3D Studio model files and another plugin to load Quake2 MD2 models. Even GAUGE's custom model format, GMDL, is loaded (and saved) through a plugin.

GAUGE also uses plugins for many other things. One example is 3D rendering. GAUGE can use either OpenGL or Direct3D for rendering. The engine itself, however, knows nothing about either API. Instead, it uses either the GL or D3D rendering plugin to render images.

For more info about how to load plugins, see the GObjectLoader and GPlugin classes.

More to Come!

There are several other interesting concepts that are slated to be implemented in the next version of GAUGE, including cookies, abstract data chunks, a new threading paradigm, and more.

Now, head on over to the modules section and start exploring!

---