It’s been several months since I last looked at this material, mainly because I’ve been spending time with my new son, so some of it is a little rusty in my memory. Hopefully I get it all right!

Any time you’re confronted with a performance issue, the first thing you should do is fire up a profiler. Often, it can be tempting to just plow into the code and search for hot spots by hand, and you may even have a good lot of success going that route. But chances are, it’ll take you a lot longer then if you use a profiler. You might end up making micro-optimizations that have no real impact on performance, but makes your code less maintainable, and that is something that you should definitely avoid.

So, on that note, we’ll run Bayts in Shark and see what we can come up with. For this test, I’m going to use the Time Profile mode, with a time limit of 30 seconds. These are usually the default settings for Shark. Since Bayts is currently so simple, with no user interaction and no real launch time work, we can just launch the app and let it run for the 30 seconds, then stop it when it’s done, and we’ll get a pretty good sample. In more complicated projects, you’ll often need to get to a certain point in the game before starting the sampling. Either way, you’ll want to launch the app, then find it in Shark’s processes list and either click Shark’s Start button, or press Option+Esc.

Running the current version of Bayts through Shark’s Time Profile will give you something looking a little like this:

From this, we can see that we’re spending a bit over 13% of our time in a lua function, luaS_newlstr. Well, we probably could easily blame Lua at this point, but it would be better to see where this function is getting called from, it might still be due to inefficiencies in our code. Shark lets us drill down for a closer look:

Now we see that nearly all of the time in luaS_newlstr is within one of our functions, lua_pushbayt. As you’ll recall from last time, this function pushes all of the information about a Bayt object onto Lua’s stack so it can be used in a Lua function.

I didn’t dig too much into the Lua code, but I’m willing to bet that there’s not too much we could do to improve the performance of luaS_newlstr. So how about avoiding it altogether, or at least try to minimize how much we call it?

To start, we need to look at what code path actually leads us through luaS_newlstr - we aren’t calling it directly from lua_pushbayt. Fortunately, it’s not too hard to figure out, especially since we already have a snapshot of the appropriate call stack in Shark. Looks like there’s a function in between, lua_setfield. A quick glance at the source for lua_pushbayt confirms, we call this function a boatload of times:

void lua_pushbayt(lua_State* L, const Bayt& b)
{
    lua_createtable(L, 0, 12);

    int tableIdx = lua_gettop(L);

    lua_pushvector(L, b.getPosition());
    lua_setfield(L, tableIdx, "position");

    lua_pushvector(L, b.getLastPosition());
    lua_setfield(L, tableIdx, "last_position");
    ...

It goes on from there for quite a while.

Do we really need to put all of this information on Lua’s stack? Let’s take a look at the one steering behavior we implemented in Lua:

function SteeringTest(bayt, friends, enemies)
   local change = { [0] = 0, [1] = 0, [2] = 0 }
   local i

   for i = 1, friends.NearbyBaytCount - 1, 1 do
      local index = friends.indexes[i]

      if friends[index].id ~= bayt.id then
         change = vectorAdd(change, friends[index].velocity)
      end
   end

   change = setVectorMagnitude(change, bayt.minUrgency)

   return change
end

In this example, it looks like we inspect only 3 fields from any given Bayt: id, velocity, and minUrgency. So, for this function at least, we’re pushing a whole lot of stuff onto Lua’s stack that never gets used. And we know that doing so is somewhat expensive. What to do?

We could assume this function is pretty exemplary and try only pushing these three pieces of data onto the stack. But that is a major assumption backed by almost no evidence, and has the potential to be far too limiting to people wishing to write new scripts.

Another solution is to not push any data about the Bayt onto the stack, but instead just give the Lua script a handle which it can pass back to some functions we’ll supply to get the data it needs. That seems like a much better general solution. So let’s give it a shot.

Lua has a mechanism called “light user data” which allows you to give some Lua code an opaque piece of data that the runtime is not allowed to change, but which can be passed back into your custom code. We’ll use that mechanism to push handles to Bayts onto the Lua stack, instead of the whole object as we did before. What will be the handle? Why, a pointer to the Bayt, of course!

Now our huge lua_pushbayt function has been reduced to a single line of code:

void lua_pushbayt(lua_State* L, const Bayt& b)
{
    lua_pushlightuserdata(L, const_cast(&b));
}

Of course, we have to provide a way for the Lua script to get data it’s interested in. This will be done with a set of functions taking the form:

extern "C" int lua_getBaytPosition(lua_State *L)
{
    validateArgumentCount(L, 1);
    
    Bayt* b = lua_tobayt(L, lua_gettop(L));

    if (b)
    {
        lua_pushvector(L, b->getPosition());
    }
    else
    {
        lua_pushvector(L, BaytVector(3, 0.0));
    }

    return 1;    
}

There is a function like this for every member of a Bayt object that we want to expose to Lua script. The function lua_tobayt is as straightforward as lua_pushbayt:

Bayt* lua_tobayt(lua_State* L, int index)
{
    return static_cast(lua_touserdata(L, index));
}

So, what does this buy us? Quite a bit, actually. We’ve gone from “go-get-a-cup-of-coffee-between-frames” slow to, on my machine, around 80fps. For comparison, the pure C++ version runs at about 115fps on this machine. Hmm, still losing quite a bit. But, then again, we knew we would when switching to using a scripting language. Still seems like a lot, though… Let’s look at Shark again.

It does look like we spend a little bit of extra time allocating and deallocating memory, but nothing too significant. Technically, we could probably do better than we are right now, but to be honest, I don’t think it’s worth it at the moment. If this system becomes more complex, and involves more scripting, then we’ll revisit the issue, but for now, it’s Good Enough.

The improved version of Bayts can be found, as always, in the Google Code SVN repository:

http://programmicon.googlecode.com/svn/tags/LuaScripting-0.03

Lua is a very popular scripting system for games. There are a lot of very good reasons to use Lua in your game. It’s fast, lightweight, and free. Embedding the Lua runtime in your application is supposed to be very easy. Today, we’ll take a look at doing just that. We’re going to embed Lua into Bayts, making it possible to script new steering behaviors in Lua.

If you want to compile the code for this example, follow the appropriate “Getting Started” link in the heading of this page. When it’s time to check code out of SVN, you’ll want to use the URL https://programmicon.googlecode.com/svn/tags/LuaScripting-0.02. If you’ve already checked out earlier code, you can save yourself some time by switching to the new tag instead. Inside your workspace:

svn switch https://programmicon.googlecode.com/svn/tags/LuaScripting-0.02

This will bring your local workspace up to date. Unfortunately, because I did some restructuring of the ThirdParty directory between IntroducingBayts-0.01 and LuaScripting-0.02, you’ll still end up re-grabbing all of the third party libraries. I promise I won’t do it again, so in the future you won’t have to!

Lua is distributed as a library written in C. It can be built for many platforms, and is pretty easy to configure for your specific needs (for example, you can replace the underlying C type used to represent numbers to an integral type, for use on an embedded platform that doesn’t have hardware floating point number support).

Integrating Lua into your code is pretty straightforward. There is a relatively simple interface for calling Lua functions from C, and calling C functions from Lua. Arguments and return values in both cases are pushed onto a stack that Lua maintains. I won’t go into the specifics of how this is done, because there already exists excellent documentation for doing so. Instead, I’ll focus on the specifics of integrating Lua into Bayts.

Design

The ultimate goal of this exercise is to make it possible to create new steering behaviors for Bayts using the Lua scripting language. It should be as easy as possible for the script writer to create new steering scripts. Fortunately, the task is fairly simple, so creating a clean interface in this case is easy. We will require the Lua script to have just one function, which will take as arguments the bayt in question, as well as the list of friendly bayts and (for future expansion) the list of enemy bayts. The function definition in Lua might look like this:

function SteeringBehavior(bayt, friends, enemies)

Bayts will be represented by a Lua table, with fields for each of the publicly accessible class member variables of the C++ representation of the bayt. The bayts will be mutable, but we will be passing them by value, so changes made to a bayt in Lua will be discarded.

Vectors will also be represented by Lua tables, and will have a functional interface for performing operations on them. For instance, to add two vectors, the Lua scripter would call a function called vectorAdd:

newVector = vectorAdd(vectorA, vectorB)

The function must return a vector, which will be the behavior’s contribution to the updated velocity vector.

Implementation, Vectors

Since pushing bayts on to the Lua stack will require us to push vectors onto the Lua stack, we’ll cover vectors first. As stated in the design, vectors will be represented as a Lua table, which will be indexed by number, like a C array. We could index it by the coordinate names, or even use both. Lua tables are versatile enough that a single table can be indexed by both numbers and strings. However, for simplicity’s sake, we’ll stick with just the numbers. Contrary to what is apparently Lua tradition, the table will be 0-based, like a C array. So, the x-coordinate will be at index 0, y at 1, and z at 2, which is the same representation as the C++ vector class we’re using.

With this in mind, the code to push and pop a vector onto and off the Lua stack is simple enough for me to present it here in whole:

void lua_pushvector(lua_State* L, const BaytVector& v)
{
    lua_createtable(L, 3, 0);

    int tableIdx = lua_gettop(L);

    lua_pushnumber(L, 0);
    lua_pushnumber(L, v[0]);
    lua_settable(L, tableIdx);

    lua_pushnumber(L, 1);
    lua_pushnumber(L, v[1]);
    lua_settable(L, tableIdx);

    lua_pushnumber(L, 2);
    lua_pushnumber(L, v[2]);
    lua_settable(L, tableIdx);
}

BaytVector lua_tovector(lua_State* L, int index)
{
    BaytVector retval(3);

    lua_pushnumber(L, 0);
    lua_gettable(L, index);
    retval[0] = lua_tonumber(L, lua_gettop(L));
    lua_pop(L, 1);

    lua_pushnumber(L, 1);
    lua_gettable(L, index);
    retval[1] = lua_tonumber(L, lua_gettop(L));
    lua_pop(L, 1);

    lua_pushnumber(L, 2);
    lua_gettable(L, index);
    retval[2] = lua_tonumber(L, lua_gettop(L));
    lua_pop(L, 1);
    
    return retval;
}

If you’ve looked at the Lua API documentation, you’ll see that we’re following the API’s naming convention for functions to push and pop values onto and off of the Lua stack. This is purely for consistency, and is not a requirement of the Lua API.

Our Lua vector library provides a fairly complete set of mathematical operations, which are implemented C++ functions, which we make available to Lua. Here is the function to add two vectors, for example:

extern "C" int lua_vectorAdd(lua_State *L)
{
    int n = lua_gettop(L);
    BaytVector v(3, 0.0);
    for (int i = 1; i <= n; ++i)
    {
        v+= lua_tovector(L, i);
    }
    lua_pushvector(L, v);
    return 1;
}

This function, and others like it, actually take a variable number of arguments, so you can add up several vectors all in one function call. You can see we use the lua_tovector function listed above to convert from the Lua vector arguments to the C++ vectors we can actually operate on. The final result is then pushed back onto the stack, using the lua_pushvector function, and the function returns 1, telling Lua that we’ve placed a single return value on the stack.

The other functions in the vector library take this same basic form.

Implementation, Bayts

Pushing bayts onto the Lua stack is pretty much the same as doing the vectors, only with a whole lot more information. We put every value that is available to C++ steering behaviors in the Lua table, indexed by sensible names such as “velocity” and “desired_speed”.

There are really no operations other than data retrieval that the Lua script can perform on a bayt, so the only functionality provided is to push and pop bayts onto and off of the Lua stack.

Implementation, Nearby bayt lists

In order to create a worthwhile steering behavior, the script needs to be able to access information about other nearby bayts. We’ll provide a list each for nearby friendly bayts and nearby enemy bayts (for future use).

As with the vectors and bayts, the bayt lists will be implemented as a table. We’ll take advantage of the fact that Lua tables can be indexed by both strings and numbers for this purpose. All of the bayts in the list will be indexed by number, starting with 0, like a C array. Other information, such as the number of nearby bayts, their indexes in the bayt list, and their distances from the bayt in question have a string index, like records.

Implementation, Lua Script Manager

To tie everything together, we’ll create a Lua Script Manager. This script manager will take on the task of loading Lua scripts and making them available to the steering engine. For the purposes of this exercise, the script manager will be exceedingly simple. It will load all of the Lua scripts it finds in a specified directory. It will also provide a means by which a Lua steering behavior can be added to a bayt flock. For now, the names of Lua steering behavior functions will have to be hard coded in the C++ code. This will be addressed at some time in the future.

Implementation, The Code

All of the Lua specific functionality is isolated in its own directory in the source tree, called Script/Lua. Look there for further details about the C++ implementation of the integration of Lua into Bayts.

Lua Steering Behavior

For the purposes of this example, I rewrote the MatchHeadingBehavior behavior in Lua. You’ll see in main.cpp that I’ve commented out the C++ version. You’ll find the Lua version in the LuaScripts directory, in a file called test.lua. Here’s how it looks:

function SteeringTest(bayt, friends, enemies)
   local change = { [0] = 0, [1] = 0, [2] = 0 }
   local i

   for i = 1, friends.NearbyBaytCount - 1, 1 do
      local index = friends.indexes[i]

      if friends[index].id ~= bayt.id then
        change = vectorAdd(change, friends[index].velocity)
      end
   end

   change = setVectorMagnitude(change, bayt.minUrgency)

   return change
end

We start by creating a Lua table which mimics the form we use for Bayt vectors, initialized to 0. I’d say this is actually a design flaw - the scripter shouldn’t have to know how the data types are represented.

Next, we loop through the nearby bayts, and add their velocity to our contribution. Just like in the C++ version, we finish up by making sure the result vector has a magnitude equal to the bayt’s minimum urgency, and returning the contribution.

Some Notes

The very first thing you will probably notice when you run this version of Bayts is that it is slow. We’re talking go-get-a-cup-of-coffee-between-frames slow. There are several very good reasons for this performance issue. In my next post, we’ll tackle the performance and see if we can’t get it back up to a more reasonable level.

I know there are a number of people out there who dislike Boost. From what I’ve seen, they are generally the same people who dislike the C++ Standard Library. It really seems to be an almost religious thing, and you can read many arguments for and against both libraries on other blogs, newsgroups, and gopher. Well, maybe not gopher so much…

I’m not going to try to sway those of you who dislike Boost or the C++ Standard Library. But I am going to be using them both, heavily, in the code presented here. Just a fair warning.

So, if you don’t already have Boost installed, please grab it and install it. There’s a very good Getting Started guide at the Boost website. The next batch of code I present here depends on the Boost Filesystem library, and it requires at least version 1.34.1. If you already have a 1.33.x version, you’ll need to upgrade. Fortunately, Boost installs itself into versioned directories by default, so you can have 1.33 installed side-by-side with 1.34, if need be.

UPDATE, 7/2/08: Boost is now in version 1.35. I’ve got ahead and made the switch, and I won’t promise that code presented here doesn’t depend on it. In other words, if you plan to follow along, then you’ll need Boost 1.35!

So now that we all agree (it was my persuasive argument, wasn’t it?), we’re going to consider some of the options for adding scripting abilities to a game engine. Along the way, we’ll add some scripting abilities to Bayts. In particular, we’ll make it possible to create new steering behaviors using script.

As with most things, there are really two main options for adding scripting support to your game. Use a pre-existing, off-the-shelf solution, or develop your own. Several more decisions have to be made once you pick one of those two options, but that’s where it all starts.

If you’ve read any of my previous posts, you’ll probably guess that using an off-the-shelf solution would be my preference. You may be right but, more than most situations, this one is not quite so clear-cut.

For one thing, even if you use an off-the-shelf solution, it’s not actually going to work out of the box. The very nature of scripting support requires a fair amount of customization on your part. While it doesn’t seem terribly likely, it is absolutely possible that the glue for an off-the-shelf solution would outweigh the work of creating a new solution for a particular problem domain.

With that in mind, we’ll start by examining a very popular open source scripting language called Lua. It’s light weight, highly portable, and is used in many games, both commercial and otherwise. We may then take a look at some other off-the-shelf solutions, and include them in our study, for completeness’ sake.

Finally, we’ll take a look at creating our own small domain specific language. We’ll go through the process of defining the requirements of the language, coming up the syntax and semantics, and implementing it as an extension to Bayts. Unlike Lua, this will not be a general purpose language. We will be including features we need to define steering behaviors — and nothing else.

This exercise is not intended as a competition, and there will be no winner or loser. Each of the items we’ll be covering has its advantages and uses. Which one is right depends on your particular situation. Different jobs require different tools. Hopefully by the time we’re done, we’ll be better able to figure out when to reach for the Ball Pein, and when to reach for the Cross Pein.

So, we’re not going to be creating a game engine, at least not today. Instead, I decided to start with something smaller, and simpler, upon which we can more easily add new features, the sorts of features that a modern game engine will need.

With that, I’d like to introduce you to Bayts, an implementation of flocking behavior. The name was suggested as a joke by my good friend Matthew. A joke it may have been, but it stuck.

If you aren’t already familiar with flocking behavior, take a look at Boids, the earliest known implementation. There are also articles about it in Game Programming Gems and Game Programming Gems 2. You should really have a look at least at the Boids page, because I am not going to go into any detail about what flocking behaviors are or how they work, at least not in this post.

The implementation we’re going to be working on is influenced pretty heavily by the one in Game Programming Gems. In many ways, though, it’s simpler. For example, the camera is fixed, and the bayts are represented by AAB’s, rather than arrows pointing in the direction of movement. This is intentional; I wanted the code to be as simple as possible, while still being flexible.

ANN aside, or more Other People’s Code

One of the problems that must be solved for implementing flocking behavior is a nearest neighbor search. Most example implementations of flocking behaviors that I’ve seen use a brute-force search, simply iterating over every single member of the flock, calculating its distance from the current member, and keeping track of the closest one(s). This works fine for small flocks, but very quickly gets bogged down when the number of members increases. There are alternative algorithms available for the nearest neighbor search, such as KD-trees, but these algorithms tend to be complex enough that they overshadow the actual flocking behavior algorithms. Which is, I suspect, why most flocking example code you find just sticks with the brute-force search.

Well, to be perfectly honest, I wasn’t terribly happy with that situation. I wanted our flock to have hundreds, maybe even thousands of members. But I also didn’t want to be overwhelmed trying to implement a better nearest neighbor algorithm. So I did what I always recommend - I got lazy. I searched around a bit, and found ANN: A Library for Approximate Nearest Neighbor Searching.

ANN is a C++ library for performing exact and approximate nearest neighbor searches, and is released under the LGPL. The library supports a few different data structures and algorithms for performing the nearest neighbor search, including KD-trees and box-decomposition trees. The interface is pretty straightforward. All of this makes it pretty much a perfect match for what I was looking for.

Bayts also depends on a couple other open source libraries:

• TMV, which I’ve discussed before. I’ve modified the version in the source repository so that it can be built with Visual C++ 2005. I’ve sent the patch to the original author, and he’s planning to include it in the next release.
• freeglut, an open source implementation of GLUT. (Not used on Mac OS X).

All of the dependent libraries are already in the source repository, so you will not have to go and get them individually.

Get It

I’m not really going to discuss Bayts any more in this post, as it’s already gone on long enough, but it will form the basis of several discussions going forward. If you want to get Bayts and try it out, you should follow these directions:

• Mac OS X
• Windows
• Linux

The directions are somewhat general, since they will be basically the same for future Programmicon projects, but since this is the first time I’m presenting code in this way, all of the examples in the instructions are for Bayts. If you follow the instructions, you should end up with a working Bayts executable.

I’d also like to point out that all of the projects I’ll be presenting here will be using CMake for its build system. Even if you have no plans to download the code I present here, I strongly recommend you check CMake out. It’s very powerful, but much easier to deal with then plain Makefiles, and definitely less of a hassle than the GNU Autotools, especially for Windows users. In a nutshell, you create some build configuration files, just like with every other build system. Then you run your project through the CMake tool, and it will generate a project for your native build system - be it make, Xcode, Visual Studio, etc.

The creators of CMake strongly recommend that you perform “out-of-source” builds. In other words, your build results, intermediate files, and anything else that the build process generates goes into a totally separate directory from your source files. For people used to using an IDE, this is probably nothing shocking. But, while Autotools and make and allow you to do this, it’s not necessarily obvious how, and it seems that few people do it. Since CMake makes it so stupidly easy, I don’t see a reason not to follow the recommendation, and tons of reasons to follow it. For one thing, it just keeps your source directory nice and clean. Just check out the Running CMake documentation.

One final note. Most all of the code I post here is cross-platform, and I’ve tested it on OS X, Windows XP, and Linux. There will be exceptions, which I will note when I post.

With all that said, I’ll be introducing our first project shortly…

Not to say there aren’t reasons to not want to use someone else’s code. There’s a lot of issues to consider. It can be difficult to assess the actual quality of the code. And, while doing so, you have to be careful not to pick nits (”This is supposed to be C++ code, but all of the files have a .C extension! This code must be horrible!”). There’s also documentation. Some very nice code comes with no documentation, some horrible code comes with extensive documentation. Licensing. If you’re planning to ever sell or give away your software, you’d better be sure the code you use has a license you can deal with. And, of course, finding the code in the first place can seem to be almost as much of a chore as just writing it yourself.

Almost, but often not quite. The benefits you can reap if you find a nice, well written, well documented bit of code that fits your needs can easily outweigh all of those issues, except perhaps if it has a nasty license. And, sometimes, even that can be dealt with.

This post started yesterday, when I discovered a subtle, but fatal bug in some vector math code I had written (for this blog, in fact). It was dumb, just a typo, but it took longer then I would have liked to track down. After that, I decided it would probably be a good idea to put together a test suite for the code, and find any other issues that might be lurking before I move on.

But, see, I’m lazy. And it was almost time to go to work, anyway.

I realized that there were probably dozens - nay, hundreds - of open source vector math libraries out there. If I were lucky, I’d be able to find a really good one, and heck, maybe it’d even have support for matrix math, too. Which I’d also be needing in the future.

So I went a-searchin’. I started with trusty old Google, but decided I ought to narrow the search a bit and took a peak at Sourceforge, where I found (the creatively named) Template Matrix/Vector Class Library for C++ by Mike Jarvis. TMV for short.

This library is definitely overkill for the little projects I’ll be using it for. But, it does everything I need, uses a coding style I enjoy, includes a very thorough test suite, and is well documented. The only thing that might bother me about it is that it’s licensed under the GPL 2, but since I’m just using it for little open sourced demo programs anyway, I’d say that’s fine.

Now I have nice vector math functionality, and complete matrix math support for when I’ll need it in the future. And thanks to the test suite, I can be confident in the results I get out of it. I barely lifted a finger.

This is just one example. In a future episode, I will be introducing you to yet another piece of someone else’s code that I’m using.

Anyway, at this point I’m rambling. The point of all of this is that there are lots of problems that need solving when developing software. Many of them have been solved over, and over, and over again. Do you really need to be spending your time solving them again? Well, maybe if your boss tells you to. But if you have the ability to be lazy about it, and find an already existing solution to use then, well, why wouldn’t you? I heartily recommend laziness.

If you’re not familiar with the concept of data serialization, the basic idea is to take a data structure and put it into a flattened form that can then be written to disk, sent across a network, or copied to another chunk of memory. Once a data structure has been serialized, you should be able to turn around and deserialize it, and get the same data structure. Sounds easy initially, but it turns out there are quite a few complications. Perhaps the biggest complications come from dealing with pointers and references. When you deserialize the data structure, you have no guarantee - indeed, no expectation - that pieces of the structure will be in the same locations in memory. Generally speaking, this problem is solved by keeping track of every pointer in the structure, what they’re supposed to point to, and their actual locations in the new data structure. Then, once every item to be deserialized is built up, you walk through all of these pointers and fix them up (usually referred to as linking) to point to the new, correct memory locations.

Now, this is probably a good time to mention that I am lazy. If I can avoid writing code, I usually do.

With all of that said, I’m going to pull a fast one on you. We’re not going to implement serialization today. No sir! You see, the Boost library already contains pretty nice support for data serialization. It does very nearly everything I want, it’s got a pretty nice interface, and boy-oh-boy does it save a lot of work. That’s not to say it’s a free ride, but certainly a lot better than starting from scratch. There’s plenty of great documentation for it on the Boost web site. A very quick summary: you’ll have to write some fairly simple functions to serialize your data. The serialization library already knows how to handle PODs, pointers, and references. So, an example might look like this:

class foo
{
   public:
      foo() : a(0), b('a') {}
   private:
      int a;
      char b;

      friend class boost::serialization::access;
      template
      void serialize(Archive & ar, const unsigned int version)
      {
         ar & a;
         ar & b;
      }
};

The first thing you might notice is the strange use of the & operator in function serialize. This operator is equivelent to >> when serializing data, and << when deserializing data. In simple cases such as this, this allows you to write a single function to handle both operations. Of course, not all situations are this simple, but there are plenty of tools in the serialization library to allow you to handle the more complicated cases.

One thing the Boost serialization library does not have out of the box is a portable binary archive format. There is an example in the documentation that can deal with different endianness of integers, and has the added benefit that it does some very minor compression of integral data. It does not, however, deal with floating point numbers. Also, the endianness of the archive data is hard coded to little endian. So, even if your primary platform is big endian, you’ll either have to change the archive code itself or always pay for byte swaps, even though they’re unnecessary. So, I’ve decided to create a custom portable binary archive format.

I should say here that, by portable, what I really mean is portable between most common desktop platforms. Right now, that means to me x86 and PPC. So we will only need to handle swapping bytes between little and big endian formats. Both platforms use IEEE 754 floating point representation, so floats and doubles will also require nothing more than a byte swap.

Fortunately, Boost Serialization makes it fairly easy to create your own archive format, and the process of doing so is well documented. I’ll just talk about the archive output code here; the input code is nearly identical and, as always, can be found in the Programmicon SVN Repository.

First of all, I’ll use the endianness utilities I talked about before to handle all of the byte swapping. Also, the archive itself will have a template parameter to specify the endianness of the archive. The Boost Serialization documentation is pretty good about explaining how to start creating your own archive format, so I won’t repeat all of that. Instead, I’ll just focus on the specifics of our portable format.

Since our archive will be a binary format, we’ll start by subclassing boost::archive::binaryoarchiveimpl. I haven’t bothered to look into the actual code for binaryoarchiveimpl, but the way we have to inherit from it makes it pretty clear it uses the Curiously Recurring Template Pattern:

template
class portable_oarchive :
    public boost::archive::binary_oarchive_impl >

In order to handle swapping our bytes, we will need to provide a set of save() functions, overridden for each data type we want to handle. We also need to provide a templatized version of this function to handle anything we don’t want to byte swap (such as strings and whatnot). Here’s a chunk of the code:

// Here's our fall through function. Any data type we don't directly handle will be handled here. Not that this means anything 
// that comes through this function will not be byte swapped. Since we will be overridding this function for all of the types we
// DO want byte swapped, that will be just fine.
template
void save(const T & t)
{
   boost::archive::binary_oarchive_impl::save(t);
}

// Here's an example of a data type that we DO want to byte swap.  We'll need a function like this for every type we swap.
void save(int16 t)
{
   t = swapBytes(t);
   this->save_binary(&t, sizeof(int16));
}

The “default” save function is pretty simple, just passing its responsibility on to the base class. The override for the int16 data type isn’t much more complicated. We simply swap bytes using one of the endianness tools I presented earlier. This is effectively a no-op if dataEndianness and HostEndianness are the same. After that, we pass the data on to a function that comes from binaryoarchiveimpl to actually write the data to the archive. And, that’s it! We just provide similar functions for each data type we want to handle, specifically int16, uint16, int32, uint32, int64, uint64, float, and double.

That’s really pretty much all there is to the portable archive format. I think the actual code for this thing is smaller than this stupid blog post! Of course, there are still all of the details of how to integrate this stuff into your code, and deciding what data actually needs to be serialized. But that is all outside of the scope of this post, which has gone on for long enough already, so I’ll leave that stuff as an exercise for the reader.

int hostToLittle(int);
unsigned int hostToLittle(unsigned int);
int hostToBig(int);
unsigned int hostToBig(unsigned int);

and on and on and on. Each function body has a preprocessor switch, determining whether it should actually swap the bytes or not. It was big, it was nasty, and it was a pain to maintain. But, it worked.

Now, I’m planning to put my code out for the whole wide world to see, and while maybe there’s only one or two of you who will actually look at it, I sure didn’t want to put that mess out there. So, I set out to clean it up.

The first step was simple, I just moved the actual byte swapping code out of the individual functions for each data type. The result was three new functions, one each for 2 bytes, 4 bytes, and 8 bytes. That at least opened up the possibility of creating platform specific implementations (such as using lwbrx on ppc, for instance). There’s still a ton of code, though, and lots of preprocessor conditionals.

So, I decided to consider using templates to simplify the code further. For some strange reason, my first thought was not to templatize all of those functions for each different supported data type. I know that is probably the more obvious first step, but it simply didn’t occur to me. Instead, I thought I could use templates to get rid of most of those preprocessor conditionals.

I use boost’s endian.hpp header to determine the host’s endianness. This header provides a handful of preprocessor macros that tell can help you determine the endianness of your host. The first step was to get this information out of the hands of the preprocessor, and give it to the compiler. That was easy:

enum Endianness
{
   BigEndian,
   LittleEndian,
#if defined(BOOST_BIG_ENDIAN)
   HostEndianness = BigEndian
#elif defined(BOOST_LITTLE_ENDIAN)
   HostEndianness = LittleEndian
#else
#error BeeLib only supports big and little endian systems.
#endif
};

You may notice that error condition and wonder “what the heck is that doing there, aren’t all machines big or little endian?” The truth is, any machine this code is likely to run on is, in fact, big or little endian. But there also exists a class of CPUs that are middle-endian, and perhaps even a few other oddities. While I doubt anyone will ever try to build this on something so exotic, if they do, this will show them exactly where and what the error is, instead of in some other part of code where they try to use HostEndianness.

Initially, I wrote a template class, with all of those same functions from before as static members, something like this:

template
class ByteSwapper
{
   static int swapBytes(int);
   static unsigned in swapBytes(unsigned int);
   ...
};

and then template specialization for each of the four possible combinations of endiannesses. That’s right, four implementations of each of those functions:

template<> int swapBytes(int in) { return in; }
template<> int swapBytes(int in) { return in; }
template<> int swapBytes(int in) { return swapBytes4(in); }
template<> int swapBytes(int in) { return swapBytes4(in); }

Ick! That is, I think, worse than the original! Surely we can do better than that!

Of course we can! The next iteration let me cut that list of functions in half, by adding a template parameter to decide if we should swap bytes or not. I never checked this version into source control, so this is from memory, and it almost certainly has some mistakes, but it looked something like this:

template
class ByteSwapper
...
template<> int swapBytes(int in) { return swapBytes4(in); }
template<> int swapBytes(int in) { return in; }

Now that’s not so bad, but, you guessed it, we can still do better! What’s stopping us, for instance, from templatizing on the type of data we’re being asked to swap, so we only need one pair