Game engines, part 3.

The API

I am not making this blog into a tutorial for one library or another. Blogs aren't really good for that. Since you're here reading on your own accord, I think you have the will and ability to teach yourself anything. There's plenty of tutorial documentation out there, anyway. What I'm offering in this series is more of a stepping stone - an understanding of the mindset you need to quickly and efficiently conquer the library of your choice.

You have the tools. A brain. Community. But there's something else that's equally useful in becoming self-taught; three letters that every programmer should know: API. Indeed, if you intend to use ANY library, whether for games or for any other project you can imagine, then you'll need to become familiar with this term. It's a bit of a strange, ambiguous acronym, but also very simple.

An API is simply the interface for programming with a library, or anything else. It stands for "Application Programming Interface". It is the vocabulary of what you want to program with. For example: in Allegro, "blit" is the function you use to draw an image on the screen. Just now, I am talking about Allegro's API. Turns out you can also use draw_sprite, and the arguments get reversed when you do ( which is ugly, I believe they're fixing that in the newer versions. ) So now I'm discussing problems with the API. That's a subject that gets talked about a lot, for any library.

A lot of different libraries use very similar APIs, to make migration easier. Ogre3D and Irrlicht, for example, both work the same way:

1. Every object in a Scene is a Node.
2. The Scene Manager controls Nodes.
3. Programmer directly controls Scene Manager

Because they share these similarities, it is easier to jump from one library to the other. They aren't usually exactly the same, however. If you want to use two libraries together, it's best that they use slightly different APIs, or at least enclose the similarities in different namespaces. But they're close enough.

The API is not normally something you have to just up and learn, nor are you required to go in and figure it out by reading the source code. There are programs such as Doxygen which go through source code and efficiantly document the API into web pages. This is almost always done. In fact, here's Ogre3D's:

http://www.ogre3d.org/docs/api/html/

This is a huge library, so it gets an equally huge API. But using the API, you can quickly figure things out. For example:

Q: How do I rotate a 3D object?

A: Well, its basic knowledge that all 3D meshes are attached to Node objects. So what you must rotate is a Node. In the Ogre API, click 'classes' at the top. Under 'N' is Node(Ogre), which means the Node class in namespace Ogre. Click 'Node'

Presto, all the methods you can call on a node object. And only a few pages down, or if you do a find for Rotate, there's yaw, roll, pitch, and two (complicated ) rotate methods. They also show you what arguments they need! Don't know what an argument means? Click it. And if you click on the method name itself, it jumps down to the special comments from the source code in a neat blue box. Very organized, isn't it?

The Allegro API is especially nice. You can download it as a .chm file ( Windows help, but Linux can view it too ), or you can view it online. Allegro has a really solid, easy to read API, with lots of description, and a comfortable theme. You hardly need to look at another tutorial.

There are some languages that are too young to have a great API. If you chose to work with Gosu, you'll have some trouble. Their API is more a series of tutorials, but if you work with Ruby, someone threw one for you together on the Wiki. Thats a good example of why you want to pick a library that favors your particular programming language - stinks to be an odd one out, when you're looking for help. But Gosu's also easy enough that you hardly need references.


The point of all this is that when you're looking into a library you might want to use, go first to its API. You are often tempted to start by looking for a tutorial. Don't do that. There are always tutorials, but APIs that are neat and well documented are vastly superior. Besides, one person's way of coding might just make you more confused ( though there's nothing wrong with looking ).

API Links to look at:

Allegro

Ogre3D

Irrlicht

JMonkey Engine


I suggest you peek at all these links for examples :)