Enginuity, Part III
Profiling, Settings, and the Kernel;
or, Stop Watching That Military Control Panel
by Richard "superpig" Fine

ADVERTISEMENT '); } if ( ShockMode ) { document.write(''); } else if (!(navigator.appName && navigator.appName.indexOf("Netscape")>=0 && navigator.appVersion.indexOf("2.")>=0)){ document.write(''); } <embed height="250" pluginspage="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash" quality="autohigh" src="http://sns.xiaomei.cc/attachment/temp/1000/56/img/wave/2010/04/4754/photo/img_1270195974_3.%3d" swliveconnect="FALSE" type="application/x-shockwave-flash" width="300" wmode="transparent">&amp;lt;A HREF=&quot;http://www.gamedev.net/banman/a.aspx?Task=Click&amp;amp;ZoneID=26&amp;amp;CampaignID=776&amp;amp;AdvertiserID=140&amp;amp;BannerID=812&amp;amp;SiteID=1&amp;amp;RandomNumber=1853416477&amp;amp;Keywords=&quot; TARGET=&quot;_top&quot;&amp;gt;&amp;lt;IMG SRC=&quot;xml/star/1000/56/img/wave/2010/04/4754/photo/img_1270195979_5.gif&quot; WIDTH=&quot;300&quot; HEIGHT=&quot;250&quot; BORDER=&quot;0&quot;&amp;gt;&amp;lt;/A&amp;gt;</embed>

Download the source code for this article here.

It's time for another helping of game engine goodness. This time we're going to add a simple profiler to the engine, look at working with game settings, and finally move on to the heart of the engine - the Kernel.

This article builds on the code built up in the previous one, so if you've not read it, go do that already.

Runtime Profiler

Have you ever had one of those days when everything seems to be going really slowly? Everyone seems quiet and muffled, as if there's some invisible, thick fog throughout the air. And that's *after* you've had your morning coffee.

Your code will have times like that, too. But while you can just go to sleep and assume that things will be better in the morning, your code isn't going to change itself. So when your framerate's dropped lower than Sanford Wallace, what do you do? It's time for that wonderful process of Optimization.

"Optimizing?" you cry, "Optimizing?! Optimizing is for professional-edition compilers, masochists, and little girly-men! I do not need to optimize!" Er, OK. I'll let you get back to chopping down trees somewhere. To put it to you straight: ALL professional development houses profile and optimize their games. I don't just mean at the end of development, either - it's an ongoing process. You don't want to build something which relies on a particular aspect of an algorithm somewhere else, if you then go in and replace that algorithm because it's too slow. (Well, you don't want to build something which relies on a particular aspect of an algorithm somewhere else *full stop* - to never make assumptions about implementation details is a fairly important object-orientation concept). Because optimization usually involves going back through your code and looking for slow points, it'll help you spot bugs as well.

But before you start ripping apart your algorithms and converting things to assembler, how do you know which parts you should be working on? It's quite possible that the math code you thought was horribly slow isn't actually being called very much, so it's not going to be responsible for your speed problems. What you need is a way of timing bits of your code, to see where you're losing momentum. Enter the Runtime Profiler.

A Profiler, in case any of you haven't figured it out yet, is a tool for timing bits of your code. Professional Profiling tools can analyze your entire game loop, processing the debug information generated by your compiler to give you the very line numbers of the sluggish bits of code responsible for your problem; and, understandably, they cost large amounts of money. So we're not going to do that. We're going for something much simpler - more of a 'manual' approach. I don't mean that you're going to need to go buy a stopwatch; I mean that when you want to time something, you're going to have to make a couple of calls, and the engine will handle it. You'll be able to see what percentage of the game loop's time gets spent on your chosen blocks of code, along with minimum and maximum peaks (so you can watch for when you walk into a crowded room, for example).

Here's a rough overview of how the profiler will look to the user (i.e. you):

• A CProfileSample object is created with a given name at the beginning of the block of code. It starts the timer.
• At the end of the block of code, the CProfileSample object is destroyed (either explicitly, or by letting it fall out of scope). It stops the timer.
• When starting up the engine, you set a pointer to an object derived from CProfilerOutputHandler, which is responsible for logging/drawing the statistics the way you want.
• Static functions of CProfileSample allow you to reset the statistics for individual samples or for all samples in the system.

Not exactly hard. You can just enclose a block of questionable code in curly braces, put a CProfileSample sample("MyProfileSample"); line at the beginning of it, and the profiler will do the rest. Neat, hmm? Of course, such ease-of-use comes with a price, and that price is the difficulty of the implementation. But given that you can just download the source code I already made for you, what do you care? ;)

Two of the important things about a profiler are that it has to be passive (because if it interferes with the code we're timing, the test is pointless), and that it has to minimize overhead. There's no point using the profiler if it takes longer to time the code than it does to execute it! So, we avoid the more costly operations - things like dynamic memory allocation (hence creating the CProfileSample on the stack rather than from the heap).

Another useful feature we want to add is a parent/child relationship setup. Say I profile my ErrorLogging routine, and it's horribly slow - ideally, I'd like to then profile *within* that sample to see which parts of the code are slowing it down. It's more useful when you're higher up - for example, I profiled my Server routine (yes, I've written it already :) ), and found that it was using up to 6% of the loop time (compared with the other tasks which were using around 0.2%). So, I added extra profiling samples within the server routine, and discovered that the section I had expected to be slowest - the socketGroup updater - was actually fine, and it was the gamestate broadcast message routine that was causing the problem.

Also - a relatively simple addition - it might well be useful to see how many times per frame a block is executed. If you see something using 20% of your loop time, but it's being called 1000 times, you perhaps don't need to worry so much about optimising the routine itself - it would possibly be more efficient to try and make fewer calls to it.

So how do we work? Upon creation of a CProfileSample object, it needs to do a few things:

• Record the current 'topmost' sample - that's the parent sample, the sample 'enclosing' our new one
• Retrieve the sample's statistics and data from storage by searching using the profile name, or create a new set of data for the sample
• Increment the number of times this sample has been executed this frame
• Flag this sample as being active
• Increment the global number of open samples
• Lastly, as close as possible to finishing, record the current time as the sample's start time.

There's also the issue of the 'topmost sample.' Given that we're eventually going to display the statistics in the form of percentages, we need to know what '100%' *is*, time-wise, so that we can work out what fraction of it 0.06 seconds would be. The easiest way to do this is to rule that there will be a 'main game loop' sample, which will have no parent sample (it will be topmost). When creating a CProfileSample as a topmost sample, it should record the start and end times in special global variables; that way, the times will be available to all samples to calculate their percentages. More on this later, when we actually look at the statistics function.

(It's worth noting, in case some of you find this all sounds a little familiar, that I'm basing my design on Steve Rabin's profiler in Game Programming Gems 1, though I've added my own little improvements to it. The GPG books are an excellent series, and should be on the shelf of any serious game developer).

We can wrap almost all of our profiler up in the CProfileSample class. Take a look:

class CProfileSample
{
public:
  CProfileSample(std::string sampleName);
  ~CProfileSample();

  static void Output();

  static void ResetSample(std::string sampleName);
  static void ResetAll();

  static IProfilerOutputHandler *outputHandler;

protected:
  //index into the array of samples
  int iSampleIndex;
  int iParentIndex;

  inline float GetTime(){ return ((float)SDL_GetTicks())/1000.0f; }

  static struct profileSample
  {
    profileSample()
    {
      bIsValid=false; 
      dataCount=0;
      averagePc=minPc=maxPc=-1;
    }

    bool bIsValid;    //whether or not this sample is valid to be used
    bool bIsOpen;     //is this sample currently being profiled?
    unsigned int callCount; //number of times this sample has been executed
    std::string name; //name of the sample
    
    float startTime;  //starting time on the clock, in seconds
    float totalTime;  //total time recorded across all executions of this sample
    float childTime;  //total time taken by children of this sample

    int parentCount;  //number of parents this sample has
                      //(useful for neat indenting)

    float averagePc;  //average percentage of game loop time taken up
    float minPc;      //minimum percentage of game loop time taken up
    float maxPc;      //maximum percentage of game loop time taken up
    unsigned long dataCount; //number of times values have been stored since
                             //sample creation/reset
  } samples[MAX_PROFILER_SAMPLES];
  static int lastOpenedSample;
  static int openSampleCount;
  static float rootBegin, rootEnd;
};

There's quite a lot there... in the public section of the class, you've got the standard constructor and deconstructor - slightly more significant than usual in this class as we'll see in a minute - and the constructor takes the name of the sample you want to use (that is, the 'unique name' you use to recognise the block of code you're profiling). The rest are all static members; an Output() function to send all the statistics to the output handler, ResetSample/ResetAll functions for resetting sample values, and a static pointer to the aforementioned output handler, an object derived from IProfilerOutputHandler (which is an abstract class).

Then we move down into the protected section of the class, and things get a little more interesting.

The first thing I want to draw your attention to is the profileSample structure. Because each CProfileSample object is created and destroyed every time you execute the code you're profiling, we can't keep it's vital statistics as member data; this is the 'storage' I referred to earlier. There's a basic constructor to flag the structure as invalid (so that it will be initialised when it gets used). The comments should be fairly self-explanatory; all of those members will, of course, be covered in more detail when we come to use them.

Besides the profileSample structure there's not much in the protected section. You've got iSampleIndex and iParentIndex - the sample numbers for this sample and the parent sample respectively - and an inlined GetTime() function, which returns the time since a fixed point (such as app startup) in seconds.

There's also four static variables at the end there. lastOpenedSample records the index of the sample that was last started - the 'top of the stack,' so to speak, and it is used to set the iParentIndex upon creation of a CProfileSample. openSampleCount simply tracks how many samples are currently open - it gets used to set parentCount. Finally, rootBegin and rootEnd are the 'special global variables' I said the topmost sample would have to store its start and end times in. Got all that? Good. Let's look at the functions themselves.

CProfileSample::CProfileSample(std::string sampleName)
{
  //The first thing we need to do is restore our previous pieces of sample
  //data from storage. That is, look in the samples[] array to see if there's
  //a valid sample with our name on it
  int i=0;
  //If we don't find it, we're going to need to create a new sample, and rather
  //than looping through the list a second time we store the first non-valid
  //index that we find this time round
  int storeIndex=-1;
  for(i=0;i<MAX_PROFILER_SAMPLES;++i)
  {
    if(!samples[i].bIsValid)
    {
      if(storeIndex<0)storeIndex=i;
    }else{
      if(samples[i].name==sampleName)
      {
        //this is the sample we want
        //check that it's not already open
        //assert only works in debug builds, but given that you don't use
        //the profiler in release builds, it doesn't really matter
        assert(!samples[i].bIsOpen &&
          "Tried to profile a sample which was already being profiled");
        //first, store its index
        iSampleIndex=i;
        //the parent sample is the last opened sample
        iParentIndex=lastOpenedSample;
        lastOpenedSample=i;
        //and the number of parents is the number of open
        //samples (excluding ourselves)
        samples[i].parentCount=openSampleCount;
        ++openSampleCount;
        samples[i].bIsOpen=true;
        //increment the number of times we've been called
        ++samples[i].callCount;
        ///finally (more or less) store the current time to start the sample
        samples[i].startTime=GetTime();
        //if this has no parent, it must be the 'main loop' sample, so copy
        //to the global timer as well
        if(iParentIndex<0)rootBegin=samples[i].startTime;
        //done
        return;
      }
    }
  }
  //we've not found it, so it must be a new sample
  //use the storeIndex value to store the new sample
  assert(storeIndex>=0 && "Profiler has run out of sample slots!");
  samples[storeIndex].bIsValid=true;
  samples[storeIndex].name=sampleName;
  iSampleIndex=storeIndex;
  iParentIndex=lastOpenedSample;
  lastOpenedSample=storeIndex;
  samples[i].parentCount=openSampleCount;
  openSampleCount++;
  samples[storeIndex].bIsOpen=true;
  samples[storeIndex].callCount=1;

  //init the statistics for this sample
  samples[storeIndex].totalTime=0.0f;
  samples[storeIndex].childTime=0.0f;
  samples[storeIndex].startTime=GetTime();
  if(iParentIndex<0)rootBegin=samples[storeIndex].startTime;
}

Pretty simple. It seeks out the existing sample, and if it can't find it, it set up a new one; either way, the sample is set up for this run of the profiler. That should be fairly simple (I hope) - we do a little more processing in the destructor, and the bulk of the statistics calculations in the Output() function. Here's the destructor:

CProfileSample::~CProfileSample()
{
  float fEndTime=GetTime();
  //phew... ok, we're done timing
  samples[iSampleIndex].bIsOpen=false;
  //calculate the time taken this profile, for ease of use later on
  float fTimeTaken = fEndTime - samples[iSampleIndex].startTime;

  if(iParentIndex>=0)
  {
    samples[iParentIndex].childTime+=fTimeTaken;
  }else{
    //no parent, so this is the end of the main loop sample
    rootEnd=fEndTime;
  }
  samples[iSampleIndex].totalTime+=fTimeTaken;
  lastOpenedSample=iParentIndex;
  --openSampleCount;
}

As you can see, the first thing we do is to stop the clock. Once we've done that, we can relax a little when it comes to speed overhead... we cleanup the sample, updating the statistics for this sample on this frame, and the parent sample (if there is one). We then 'pop the stack' - reset the lastOpenedSample and openSampleCount values to what they were before we started profiling (assuming nobody has done anything stupid like try to construct and destruct CProfileSamples out-of-order). Also fairly simple. So let's move on to the Output() function, which calculates all the statistics for a given sample across the entire app, and sends them to the OutputHandler:

void CProfileSample::Output()
{
  assert(outputHandler && "Profiler has no output handler set");
  
  outputHandler->BeginOutput();

  for(int i=0;i<MAX_PROFILER_SAMPLES; ++i)
  {
    if(samples[i].bIsValid)
    {
      float sampleTime, percentage;
      //calculate the time spend on the sample itself (excluding children)
      sampleTime = samples[i].totalTime-samples[i].childTime;
      percentage = ( sampleTime / ( rootEnd - rootBegin ) ) * 100.0f;

      //add it to the sample's values
      float totalPc;
      totalPc=samples[i].averagePc*samples[i].dataCount;
      totalPc+=percentage; samples[i].dataCount++;
      samples[i].averagePc=totalPc/samples[i].dataCount;
      if((samples[i].minPc==-1)||(percentage<samples[i].minPc))
        samples[i].minPc=percentage;
      if((samples[i].maxPc==-1)||(percentage>samples[i].maxPc))
        samples[i].maxPc=percentage;

      //output these values
      outputHandler->Sample(samples[i].minPc,
                samples[i].averagePc,
                samples[i].maxPc,
                samples[i].callCount,
                samples[i].name,
                samples[i].parentCount);

      //reset the sample for next time
      samples[i].callCount=0;
      samples[i].totalTime=0;
      samples[i].childTime=0;
    }
  }

  outputHandler->EndOutput();
}

So we begin with a quick check that we actually *have* an output handler, followed by a call to outputHandler->BeginOutput() to allow our output handler to clear buffers, print headers, or whatever it wants.

Then we move on to the more interesting stuff. Firstly, the time spent on the sample in itself is calculated - that is, the total time spent on the sample, minus the time spent on children. This time is then turned into a percentage of the time taken for the whole loop to run, making it easier to work with (because it'll be roughly the same across different-speed machines; a chunk of code will be slower, but so will everything else). Next we calculate our statistics. We take the current average, and multiply it by the number of samples taken so far (dataCount) - that gives us the total time spent on this sample since the profiler was started/reset. We add our new value, increment the number of values in the data, and divide again to get the average back. Then, a pair of quick checks let us update the maximum and minimum percentages, if required.

Then we move on to sending the data to the OutputHandler. If you don't see how that's done, I probably can't help you. :)

Lastly, we reset the sample for the next loop. Given that the Output function should be called once per frame - ideally at the end of the game loop, outside of the top-level sample (as we'll see later this article) - it's the 'tick point' that we can use to reset things without worrying. Once all the samples are processed, the outputHandler's EndOutput() function is called, again to allow it to perform whatever clean-up processing is necessary.

The only other functions in CProfileSample are ResetSample and ResetAll - all they need to do is set the bIsValid flags for the appropriate sample(s), so I won't go over them here. Instead, let's move on to the output handler we're going to use for the time being - CProfileLogHandler.

Before we do that, it's necessary to look briefly at the IProfilerOutputHandler class. You've seen all the functions it provides already:

class IProfilerOutputHandler
{
public:
  virtual void BeginOutput()=0;
  virtual void Sample(float fMin, float fAvg, float fMax,
                      int callCount, std::string name, int parentCount)=0;
  virtual void EndOutput()=0;
};

It's just a simple abstract (interface) class, allowing you to derive any class from it to handle profiler output. The class I've derived from it for you is CProfilerLogHandler:

class CProfileLogHandler : public IProfilerOutputHandler  
{
public:
  void BeginOutput();
  void EndOutput();
  void Sample(float fMin, float fAvg, float fMax,
              int callCount, std::string name, int parentCount);
};

void CProfileLogHandler::BeginOutput()
{
  CLog::Get().Write(LOG_APP,IDS_PROFILE_HEADER1);
  CLog::Get().Write(LOG_APP,IDS_PROFILE_HEADER2);
}

void CProfileLogHandler::EndOutput()
{
  CLog::Get().Write(LOG_APP,"n");
}

void CProfileLogHandler::Sample(float fMin, float fAvg, float fMax,
                   int callCount, std::string name, int parentCount)
{
  char namebuf[256], indentedName[256];
  char avg[16], min[16], max[16], num[16];

  sprintf(avg, "%3.1f", fAvg);
  sprintf(min, "%3.1f", fMin);
  sprintf(max, "%3.1f", fMax);
  sprintf(num, "%3d",   callCount);

  strcpy( indentedName, name.c_str());
  for( int indent=0; indent<parentCount; ++indent )
  {
    sprintf(namebuf, " %s", indentedName);
    strcpy( indentedName, namebuf);
  }

  CLog::Get().Write(LOG_APP,IDS_PROFILE_SAMPLE,min,avg,max,num,indentedName);
}

And that, ladies and gentlemen, prints a profile table to the APP logfile. IDS_PROFILE_HEADER1 and IDS_PROFILE_HEADER2 are the two header lines that make up the table column names and underlining; IDS_PROFILE_SAMPLE is a simple string to put the statistics into the right places. The only really noteworthy thing here is the fact that the name gets indented relative to the parentCount - making it much easier to see parent/child relationships in the logs. EndOutput() logs a newline, just to space things out in my logs (because we're calling this once per frame, so we get a lot of them in the logs). Here's a sample of the output:

  Min :   Avg :   Max :   # : Profile Name
--------------------------------------------
  0.0 :  96.6 : 100.0 :   1 : Kernel task loop
  0.0 :   0.6 :   6.3 :   1 :  Renderer
  0.0 :   0.1 :   6.3 :   1 :  Server
  0.0 :   0.7 : 100.0 :   1 :   Flushing socketGroup
  0.0 :   0.0 :   6.2 :   1 :   Processing messages
  0.0 :   1.4 :   6.3 :   1 :   Server state update
  0.0 :   0.5 :   6.7 :   1 :  Client

So you should see that the Avg (average) values roughly add up to 100% (give or take a little due to floating-point truncation). The Min and Max values tend to be of limited use - they're better if you examine profiler output over a specific section of the game by calling ResetAll at the beginning of the section, because otherwise startup in particular tends to produce some freak values (as you see there). So, I can immediately see that if I need to make my game faster, I ought to look into the Server State Update code first - as opposed to the message processor, which I thought would be the worst culprit (and it actually has an average time of <0.1%).

Settings

There comes a time in every engine's life when you, or the user, wants to customise something about it's operation. Perhaps you'd like to run it at a higher screen resolution, or turn off the sound. You have the luxury of the code, so you can go in and change what you want, and just recompile; but the user can't do that. It's time for a user-targeted settings mechanism.

So how do we expose our settings in a flexible, reusable way? We want them all in a central place - so that a CSettingsManager can load into them with ease - but we don't want to hard-code them (especially given that your game will probably add it's own settings to the engine's list). We need to handle different types of setting - floats, ints, strings, and so on. We also need to handle 'single' settings versus 'multiple' settings - that is, settings which contain a list of values, such as the maps in the map rotator for a multiplayer server.

We're going to use another utility object, a distant cousin of one introduced in the previous article: a Dator (loose relative of Functor). As you may have guessed from the name, a dator is an object which wraps a data member (as opposed to a Functor which wraps a function). Because we need to establish a single format for all data to be passed to the dator in (even if it then gets converted to another specific type), we're going to say that a dator accepts std::strings as input; it will then convert from that std::string to the format it's been templated to handle, using a trick borrowed from boost:lexical_cast, that you'll see in a minute.

It may also be necessary to have a list of dators for some reason. Because Dator<int> and Dator<float> are considered distinctly seperate types, we can't put them in a list together; instead we have to establish a common base class for all dators and have a list of that. Here's the base class:

class BaseDator : public IMMObject
{
protected:
  BaseDator(){}
  BaseDator(BaseDator &b){(*this)=b;}
public:
  virtual BaseDator &operator =(std::string &s)=0;
  virtual BaseDator &operator +=(std::string &s)=0;
  virtual BaseDator &operator -=(std::string &s)=0;
  virtual bool operator ==(std::string &s)=0;
  virtual bool operator !=(std::string &s)=0;

  virtual bool hasMultipleValues()=0;

  virtual operator std::string()=0;
};

You can see how all the operators take std::strings as parameters (and have return types, this time!), establishing it as the 'global type' for dators to transfer values in and out. There's also hasMultipleValues() - overridden by derived classes to indicate whether the dator works with a single value (like a normal variable) or a set of values (a std::list). Finally, there's an operator to convert the value back to a std::string for other uses. Pretty much all of these functions are pure virtual, and the constructors are protected: you're not going to be instantiating this directly, folks. :)

template<class T>
class Dator : public BaseDator
{
protected:
  T& target;
  T toVal(std::string &s)
  {
    std::stringstream str;
    str.unsetf(std::ios::skipws);
    str<<input;
    T res;
    str>>res;
    return res;
  }
  std::string toString(T &val)
  {
    std::stringstream str;
    str.unsetf(std::ios::skipws);
    str<<val;
    std::string res;
    str>>res;
    return res;
  }
public:
  Dator(T& t) : target(t) {}
  BaseDator &operator =(std::string &input)
    { target=toVal(input); return *this; }
  BaseDator &operator +=(std::string &input)
    { target+=toVal(input); return *this; }
  BaseDator &operator -=(std::string &input)
    { target-=toVal(input); return *this; }
  bool operator ==(std::string &s) { return (s==(std::string)(*this)); }
  bool operator !=(std::string &s) { return (s!=(std::string)(*this)); }
  operator std::string() { return toString(target); }

  bool hasMultipleValues() { return false; }

  AUTO_SIZE;
};

OK. That's the class for a dator which represents a single value (hasMultipleValues returns false). Look at the constructor and protected data member - we're working with references, which means that when you create a dator, you'll bind it to an existing variable - any assignments to the dator will result in assignments to the variable itself. That's why we'll hardly ever need to work with the dator when we know what type it is - we'll work with the variable it's bound to instead.

What's the std::stringstream stuff about, I hear you ask? That's the trick I mentioned, borrowed from boost::lexical_cast. You see, we can't just assign a std::string to an arbitrary type - there's no built-in conversion available. In C, we had to use the atoi()/atof()/atol() family of functions; we could, in theory, do that here, but that requires template specialisation, which is not much good (at least under MSVC) - it practically forces us to copy+paste code for each specialised type, which is exactly what the templates were there to avoid. So, what we do is take advantage of the fact that std::stringstream has overloaded input/output operators for most standard types; we write the string out to it using operator <<(std::string), and then read it back in again using operator >>(T &). The type-conversion is performed for us by the stringstream class. You can see how it works in the toVal() and toString() functions - it's reversible, too. If you try and set up a variable for a type that stringstream can't convert to, then you'll get a compile error, but it's possible to provide global overloads (for example, operator<<(std::string) isn't actually a member of the class, it's globally defined in the 'string' header).

template<class T>
class ListDator : public BaseDator
{
protected:
  std::list<T> &values;
  T toVal(std::string &s)
  {
    std::stringstream str;
    str.unsetf(std::ios::skipws);
    str<<input;
    T res;
    str>>res;
    return res;
  }
  std::string toString(T &val)
  {
    std::stringstream str;
    str.unsetf(std::ios::skipws);
    str<<val;
    std::string res;
    str>>res;
    return res;
  }
public:
  ListDator(std::list<T> &v) : values(v) { }
  BaseDator &operator =(std::string &s)
    { values.clear(); values.push_back(toVal(s)); return *this; }
  BaseDator &operator +=(std::string &s)
    { values.push_back(toVal(s)); return *this; }
  BaseDator &operator -=(std::string &s)
    { values.remove(toVal(s)); return *this; }
  bool operator ==(std::string &s)
    { return (std::find(values.begin(),values.end(),toVal(s))!=values.end()); }
  bool operator !=(std::string &s) { return !((*this)==s); }
  
  operator std::string() { return toString(values.back()); }
  operator std::list<T>&() { return values; }

  bool hasMultipleValues(){return true;}

  AUTO_SIZE;
};

And that's the class for a dator which can hold multiple values (hasMultipleValues returns true). It's pretty similar to the previous class - ideally, we'd use the previous class for this - but std::list doesn't provide +=, -=, or = operators so we can't (and my attempt to provide global overloads failed). Operator = will clear the list and add a single value; operators += and -= will add and remove values respectively. Operator == returns true if the list *contains* the given value - it could only be one of many though. The std::string type converter returns the last value added to the list (values.back()), and a function is there to get a reference to the list itself (though, like normal dators, you'll usually have direct access to the list without needing the dator).

How do you use these classes?

//we can have a variable of pretty much any type - let's pick int for simplicity
int someValue;
//we can then create a dator bound to it like this
CMMPointer< Dator<int> > dator=new Dator<int>(someValue);
//if we then assign to the dator...
(*dator)=std::string("5");
//the value of someValue should now be 5.

//using ListDators is pretty similar, as I said earlier
std::list<int> someValues;
CMMPointer< ListDator<int> > listDator=new ListDator(someValues);
(*listDator)=std::string("5");
(*listDator)+=std::string("6");
(*listDator)-=std::string("5");
//someValues should now have the single entry 6.

Dators will be useful later on for scripting, but right now, we're going to use them for our settings mechanism.

As you might expect, we need a Singleton-based Manager to handle all the settings for us.

class CSettingsManager : public Singleton<CSettingsManager>  
{
public:
  CSettingsManager();
  virtual ~CSettingsManager();

  void RegisterVariable(std::string &name, CMMPointer<BaseDator> &var);
  void SetVariable(std::string &name, std::string &value, int bias=0);

  void CreateStandardSettings();
  void DestroyStandardSettings();

  void ParseSetting(std::string str);
  void ParseFile(std::string filename);

protected:
  std::map<std::string, CMMPointer<BaseDator> > settingMap;
};

We've got the familiar Singleton syntax, a constructor and a destructor. RegisterVariable should be obvious - and that's where the dators come in. SetVariable has one parameter, 'bias,' that you might be wondering about, but we'll get to that in a minute. ParseSetting takes a single name=value expression, splits it up and passes it onto SetVariable; and ParseFile opens a given file and hands each line to ParseSetting (allowing you to build up 'settings files'). The only totally unexpected functions there are CreateStandardSettings and DestroyStandardSettings.

Now I don't like the StandardSettings mechanism. It feels messy, and like there should be a better way to do it. But as far as I can tell, there isn't. CreateStandardSettings is the function which creates all of the settings used by the engine itself - the renderer's screenX, screenY, and screenBPP, for example. I feel that creation of those should fall to the renderer (obviously), but we get a chicken-and-the-egg situation; we can't create the renderer until we've loaded in it's settings, but we can't load in it's settings till they've been registered. The one possible ray of hope is to use static object variables for the dators; but they couldn't be registered in the CSettingsManager because it needs to be created first, with a 'new CSettingsManager()' line. As Ned Flanders would say, it's quite a dilly of a pickle.

So the best we can do is provide this function, CreateStandardSettings, to be called when the CSettingsManager is created. Because it's called by the manager itself, there's no risk that the manager doesn't exist when it gets called. Also, we don't have to desert static variables completely - we can put static pointers and values into the renderer class, and have CSettingsManager store the dators there when they get created. We also, therefore, need to pair up CreateStandardSettings() with DestroyStandardSettings(), because those static pointers (which are smart pointers, of course) don't try and delete the dators they point to until the program is unloaded from memory (which is *after* the call to CollectRemainingObjects). DestroyStandardSettings will set all those static pointers to zero, so they don't try and call Release() on already-deleted objects.

We're about to look at some function code, but first I want to explain the 'bias' parameter passed to SetVariable. 'Bias,' in this situation, basically means 'Add/Remove.' When we're talking about list settings, we can't assign to them in the normal way; and flags need some kind of boolean expression for whether they should be set or unset. So, when dealing with list or flag settings, the parser requests that the name of the setting be prefixed with '+' or '-'; '+' for positive, 'enable' bias, and '-' for negative, 'disable' bias. They can still be specified for non-list, non-flag variables - they'll just be ignored - and if left off, a positive bias is assumed.

Here's the simple functions, from both CSettingsManager, and the couple of undefined CSetting functions:

CSettingsManager::CSettingsManager()
{
  settingMap.clear();
  CreateStandardSettings();
}

CSettingsManager::~CSettingsManager()
{
  DestroyStandardSettings();
}

void CSettingsManager::RegisterVariable(std::string &name,
                                        CMMPointer<BaseDator> &var)
{
  settingMap[name]=var;
}

void CSettingsManager::ParseFile(std::string filename)
{
  std::ifstream in(filename.c_str());
  if(!in.is_open())return; //couldn't open
  while(!in.eof())
  {
    char szBuf[1024];
    in.getline(szBuf,1024);
    ParseSetting(szBuf);
  }
}

//set up a couple of macros for the StandardSettings mechanism - just convenience
//jobs each macro takes the type of dator, the CMMPointer<> to store it in,
//the variable it's bound to, and the name the manager should use to refer to it.
#define SETTING(type, target, var, name) target=new Dator<type>(var); 
        RegisterVariable(std::string(name),CMMPointer<BaseDator>(target));
#define LIST(type, target, var, name) target=new ListDator<type>(var); 
        RegisterVariable(std::string(name),CMMPointer<BaseDator>(target));

void CSettingsManager::CreateStandardSettings()
{
  //empty for the time being
}

void CSettingsManager::DestroyStandardSettings()
{
  //also empty

}

OK, those are simple enough. The CSettingsManager constructor/destructor spends most of it's time setting up the StandardSettings; and RegisterVariable() just adds the pointer to the map. Let's move onto the two more complex functions, SetVariable and ParseSetting:

void CSettingsManager::SetVariable(std::string &name,
                          std::string &value, int bias)
{
  if(!settingMap[name])return; //setting doesn't exist
  if(settingMap[name]->hasMultipleValues())
  {
    std::list<std::string> valueList;
    valueList.clear();

    //check for semicolon-seperated values
    if(value.find(';')!=-1)
    {
      //split the string into semicolor-seperated chunks
      int first=0, last;
      while((last=value.find(';',first))!=-1)
      {
        valueList.push_back(value.substr(first,last-first));
        first=last+1;
      }
      valueList.push_back(value.substr(first));
    }else{
      valueList.push_back(value);
    }

    for(std::list<
        std::string>::iterator it=valueList.begin(); it!=valueList.end();
        it++)
    {
      if(bias>0)
      {
        (*settingMap[name])+=(*it);
      }else if(bias<0)
      {
        (*settingMap[name])-=(*it);
      }else{
        (*settingMap[name])=(*it);
      }
    }
  }else{
    //just assign the value
    (*settingMap[name])=value;
  }
}

void CSettingsManager::ParseSetting(std::string str)
{
  int bias=0; std::string name, value;
  //test for bias
  if((str[0]=='+')||(str[0]=='-'))
  {
    bias=((str[0]=='+')*2)-1; //+ maps to 1*2-1=1, - maps to 0*2-1=-1
    str=str.substr(1); //remove the first character from the string
  }
  //test for '='
  int eqPos=str.find('=');
  if(eqPos!=-1)
  {
    //there's an = sign in there
    //so split either side of it
    name=str.substr(0,eqPos);
    value=str.substr(eqPos+1);
  }else{
    //there's no equal sign
    //we use the bias to construct a boolean value
    //so that flags can be +flag (mapping to flag=1) or -flag (mapping to flag=0)
    name=str;
    char szBuf[5];
    sprintf(szBuf,"%i",(bias+1)/2);
    value=szBuf;
  }
  //set the variable
  SetVariable(name,value,bias);
}

Still fairly simple, just a little larger. The SetVariable function splits the value string down into its component parts (if they exist). Then, using the bias value, it adds or removes each part from the list. If, on the other hand, it's a simple non-list variable, it just sets the value. The SetVariable function is called by the ParseSetting function, which simply extracts the bias and splits the string using the '=' sign in the middle (if, again, it exists).

So what syntax should we use for our options, in the end? The syntax rules look something like this: Setting: [biasValue]valueName[=valueList] biasValue: +, - valueList: value[;valueList]

Where [] indicates 'optional,' and a comma indicates 'or.' If you want to test it, try creating a Dator of some basic type such as 'int', registering it with the CSettingsManager, passing a value to it through the command-line (MSVC users: Project->Settings->Debug->Program Arguments), and then logging that value back out. Play around; after all, this is a game engine! ;-)

The Kernel

That's right, it's that moment you've all been waiting for.. the heart of the engine, the Kernel, and its jaw-dropping task-management ensemble.

The Kernel, which the more old-school game developers amongst you might know better as the Game Loop, is the beating heart of the engine - almost literally. It 'pumps' the various things the engine needs to do at any given time, looping through them in a round-robin. Each thing the engine is doing - a 'task' - gets a single Update() call every frame, in which it does whatever it needs to do. The Kernel exits the loop when there are no more tasks. It's quite a lot like multithreading, if you're familiar with that - in fact, the term 'Kernel' is borrowed from OS terminology. (Combining the game kernel with multithreading is something you should probably avoid; however, the concept of multiple game kernels for multiprocessor systems, where each processor runs one kernel in its own thread, is something I quite like).

The first thing to do is to define a 'task.' A task can be any object which supports the Update() function, along with a couple of others - so the sensible approach is to use a base ITask class as an interface to be implemented. (However, because I'm totally insane, I'm going to use....a herring. Or maybe not.)

class ITask : public IMMObject
{
public:
  ITask(){canKill=false;priority=5000;}
  virtual bool Start()=0;
  virtual void OnSuspend(){};
  virtual void Update()=0;
  virtual void OnResume(){};
  virtual void Stop()=0;

  bool canKill;
  long priority;
};

There's a little more there than just an Update() function. The interface provides for all stages in a task's life - creation, pause, resume, and destruction. The creation function - Start() - is boolean, allowing the task to say, 'No, can't start right now,' so we don't get confused tasks being updated. OnSuspend() and OnResume() are used when pausing and resuming tasks (for example, you'd pause the AI task while the user is accessing the in-game menu), just to notify the task that it should release any high-demand resources and get itself ready for a little wait; and, conversely, that it should pick up its resources and carry straight on again. The Update() function we've already covered; which leaves the Stop() function, called when a task is being removed from the kernel's list. Note that the Start(), Update(), and Stop() functions are pure virtual - forcing derived classes to implement them - but the OnSuspend and OnResume classes are only regular virtual, meaning that you can override them if you want the notification, but you don't have to. Some tasks won't need to do anything to pause or resume - they just stop getting Update() messages for a while.

The last two parts of the class, canKill and priority, are used to manage thread lifetime and execution order, respectively. The task sets canKill to true when it's ready to be Stop()'d; and the kernel calls Update() on the tasks in order of their priority numbers, with the lowest numbers happening first. The order can be very important - your custom rendering task should have a higher priority than the 'flip buffers' task, but a lower priority than the 'clear back buffer' task, for example.

Now we preset the Kernel itself. It's a singleton, and only really provides task management functions:

class CKernel : public Singleton<CKernel>
{
public:
  CKernel();
  virtual ~CKernel();

  int Execute();

  bool AddTask(CMMPointer<ITask> &t);
  void SuspendTask(CMMPointer<ITask> &t);
  void ResumeTask(CMMPointer<ITask> &t);
  void RemoveTask(CMMPointer<ITask> &t);
  void KillAllTasks();

protected:
  std::list< CMMPointer<ITask> > taskList;
  std::list< CMMPointer<ITask> > pausedTaskList;
};

You've got your standard constructor/destructor, an Execute() function - the function which runs the task loop and exits when the game is shutdown, a load of task-management functions, and then two protected lists for ITask pointers - one for running tasks, and one for paused tasks.

Why have two seperate lists? The alternative is to have a flag bIsPaused in the ITask class, which you set to true when the task should pause, and so on. The problem with such a system is that it's very prone to abuse - anything could pause any task at any time. There's no guarantee that the OnSuspend or OnResume functions would be called. We would also incur a cost each loop, in that we'd have to check the flag; given that the actions of pausing/resuming tasks will be fairly rare, the cost of moving the pointer from one list to another is negligable.

CKernel::CKernel()
{
  SDL_Init(0);
  SDLNet_Init();
}

CKernel::~CKernel()
{
  SDLNet_Quit();
  SDL_Quit();
}

So far so simple. These functions bring up and shut down SDL, without initialisng any of its subsystems. Seemed like a good enough place to me, at least; you're welcome to move them if you can think of some place better.

int CKernel::Execute()
{

  while(taskList.size())
  {
    {
      PROFILE("Kernel task loop");

      std::list< CMMPointer<ITask> >::iterator it;
      for(it=taskList.begin();it!=taskList.end();)
      {
        ITask *t=(*it);
        it++;
        if(!t->canKill)t->Update();
      }
      //loop again to remove dead tasks
      for(it=taskList.begin();it!=taskList.end();)
      {
        ITask *t=(*it);
        it++;
        if(t->canKill)
        {
          t->Stop();
          taskList.remove(t);
          t=0;
        }
      }
      IMMObject::CollectGarbage();
    }
#ifdef DEBUG
    CProfileSample::Output();
#endif
  }

  return 0;
}

And there you have it; the game loop. You can see the task system, the Memory Manager, and the Profiler all coming into play - this is where garbage collection gets called and the profiler gets told to output its statistics (as the "Kernel task loop" is the top-level profiler sample). All tasks are updated, and then any dead tasks are removed from the system; this is repeated until all tasks are dead, one way or another. You can see some slightly weird constructions with the STL iterators - that's because there's a risk of the task being removed from the list (either to be deleted, or to be moved to the paused list) in the Update() function, which would mess up the iterator.

bool CKernel::AddTask(CMMPointer<ITask> &t)
{
  if(!t->Start())return false;

  //keep the order of priorities straight
  std::list< CMMPointer<ITask> >::iterator it;
  for(it=taskList.begin();it!=taskList.end();it++)
  {
    CMMPointer<ITask> &comp=(*it);
    if(comp->priority>t->priority)break;
  }
  taskList.insert(it,t);
  return true;
}

void CKernel::SuspendTask(CMMPointer<ITask> &t)
{
  //check that this task is in our list - we don't want to suspend
  //a task that isn't running
  if(std::find(taskList.begin(),taskList.end(),t)!=taskList.end())
  {
    t->OnSuspend();
    taskList.remove(t);
    pausedTaskList.push_back(t);
  }
}

void CKernel::ResumeTask(CMMPointer<ITask> &t)
{
  if(std::find(pausedTaskList.begin(),pausedTaskList.end(),t)
        !=pausedTaskList.end())
  {
    t->OnResume();
    pausedTaskList.remove(t);
    //keep the order of priorities straight
    std::list< CMMPointer<ITask> >::iterator it;
    for(it=taskList.begin();it!=taskList.end();it++)
    {
      CMMPointer<ITask> &comp=(*it);
      if(comp->priority>t->priority)break;
    }
    taskList.insert(it,t);
  }
}

void CKernel::RemoveTask(CMMPointer<ITask> &t)
{
  if(std::find(taskList.begin(),taskList.end(),t)!=taskList.end())
  {
    t->canKill=true;
  }
}

void CKernel::KillAllTasks()
{
  for(std::list<
      CMMPointer<ITask> >::iterator it=taskList.begin();
      it!=taskList.end();it++)
  {
    (*it)->canKill=true;
  }
}

That's the task-management API of the kernel. It covers all the basic things you can do to a task, including a KillAllTasks() function, which essentially causes the app to quit on the next task cycle. AddTask and ResumeTask keep the live tasks list sorted by priority, so that the highest-priority task (the one with the lowest number) is at the front and will therefore be executed first each cycle.

Th-th-th-that's all, folks

That's the whole of the foundation tier done. It's solid enough to support the rest of the engine, and if there are any problems it's centralised enough to make fixing things pretty simple. Next time we'll set up a few basic tasks (such as the video or input tasks), and look for the first time at how the engine integrates into a full program. Because what we've got so far is good, but doesn't do much without a main() function to start it all up...

Next time will also be the first time we do any significant work with SDL and FMOD, so make sure they're up to scratch as far as you're concerned. The addresses are http://www.libsdl.org/ and http://www.fmod.org/ for anyone who had forgotten.

Enginuity, Part IV
The Entry Point and Task Pool; or, Swim Your Way In
by Richard "superpig" Fine

Still reading these? I must be better than I thought. This article we'll take all the code we've produced so far - the Foundation Tier of the Enginuity engine - and actually make an executable program with it. Then we'll put together some of the 'system tasks' that any game will need.

But of course, if I'm going to take the code we've produced so far, you'll need to know about it. So go read the other articles, if you haven't already.

Entry Point

The Application Entry Point is the place in your program where it all begins. Traditional C/C++ programs have an entry point called 'main' - Win32 programs have 'WinMain,' and so on and so forth. If you were to represent your program as a tree, where nodes are functions that call other functions, the entry point would be the very root of the tree. Before now, Enginuity didn't have an entry point, so we couldn't build it into an executable.

We're not about to give Enginuity an entry point, either. As an engine, it shouldn't have one; as it is now, we can build it as a library, and have a proper program start the engine whenever it wants. We give extra control to whoever wants to use the engine - perhaps an anti-piracy system needs to be initialized before the engine starts, for example.

So what we'll be doing here is looking simply at a sample program that makes use of the engine. The engine could be in a library or DLL, or it could be simply build as part of the project; it doesn't matter. Personally, I'm building the whole thing in one project, and just splitting the source files into 'Engine' and 'Game' folders.

Given that we're aiming for a relatively cross-platform engine here, we have a problem. I already mentioned a discrepancy between entry point functions on Win32 and other systems - they have different names (and different parameters). Do we provide both main() and WinMain() functions? Do we use some kind of conditional-compilation trick?

Neither. SDL has already solved the problem for us. It contains the code to 'insulate' us from the underlying system - so that when it gets to us, we always use a main() function. SDL provides the 'translation' from WinMain() to main() under Win32, and so on for other platforms. All we have to do is make sure we link to sdlmain.lib, and that we're including sdl.h. Here's the main() function we're going to use:

int main(int argc, char *argv[])
{
  new CApplication();
  CApplication::GetSingleton().Run(argc,argv);
  delete CApplication::GetSingletonPtr();

  //clean up any remaining unreleased objects
  IMMObject::CollectRemainingObjects(true);

  return 0;
}

Before we get into the body of the function itself, I'll just say this: make absolutely sure that the main() function has a header like the one above. Same return type, same name, same argument types. If you get errors about 'sdl_main is undefined,' check here. (The truth is that sdl_main.h includes a macro to turn any function named main() into one named sdl_main(), so that it doesn't get confused with the main() function that SDL provides. As far as I can tell, an unfortunate side effect of this is that you shouldn't use the name 'main' for any functions or variables; but frankly, I consider it a small price to pay).

OK. You're probably wondering what this CApplication class is. You've probably gathered that it's a Singleton; it represents your program. It's often useful to encapsulate (wrap up in a class) the 'application' itself; you get the benefits of construction/destruction, as well as extra control over lifetimes (as we'll see in a moment). The CApplication class, then, is the 'meat' of the program.

So the first thing we do is to create a new CApplication object (because that's how the Singleton mechanism works - check back to part 2 if you don't remember). We then pass argc and argv straight into the CApplication's Run() function. When it's done, we delete the CApplication object. So that's the whole of the 'application itself' done.

Then we do a last call to IMMObject::CollectRemainingObjects. This is where one of the major advantages of having the CApplication object comes into play. When CollectRemainingObjects() is called, all IMMObject-derived objects will be deleted; but after that, if there are any CMMPointers still around, they'll try calling Release() on their pointers - which will cause an access violation. In the end, we see that we can't call CollectRemainingObjects while there are any IMMObjects alive (and assigned). This means that keeping global CMMPointers is unsafe - they don't get killed till after the main() function is done - so instead, we can keep them in the CApplication object, and they get destroyed when the CApplication object is destroyed. Thus, when we reach CollectRemainingObjects we can release all still-allocated objects to avoid memory leaks completely, without worrying that anything is still latched onto them. When the CApplication object has been shut down, nothing should still be running, no CMMPointers should still be alive.

The CApplication object only needs to provide a Run() function; a constructor and destructor are optional (because for the most part, we'll only be adding CMMPointers to the CApplication object, and they have their own constructors), so I'm not going to show you the class definition here. Just remember that it derives from Singleton<CApplication>. Instead, let's skip straight to the Run() function:

void CApplication::Run(int argc, char *argv[])
{
  //open logfiles
  if(!CLog::Get().Init())return;

  //create a couple of singletons
  new CSettingsManager();
  new CKernel();

  //parse the 'settings.eng' file
  CSettingsManager::GetSingleton().ParseFile("settings.eng");
  
  //parse command-line arguments
  //skip the first argument, which is always the program name
  if(argc>1)
    for(int i=1;i<argc;i++)
      CSettingsManager::GetSingleton().ParseSetting(std::string(argv[i]));
  
  //set up the profiler with an output handler
  CProfileLogHandler profileLogHandler;
  CProfileSample::outputHandler=&profileLogHandler;

  //main game loop
  CKernel::GetSingleton().Execute();
  
  //clean up singletons
  delete CKernel::GetSingletonPtr();
  delete CSettingsManager::GetSingletonPtr();
}

Fairly self-explanatory. This is where many of the systems we've built up over the past articles tie together.

First, the logfiles. We want to have these available to us throughout the startup process, so that if something goes wrong and the game can't start at all, the logfiles are around for the user to find out why.

As soon as possible, we create the singletons - creating the CSettingsManager first is probably a good idea because the kernel may have some settings that should be in place before it gets constructed.

Next, we parse the 'settings.eng' file. This is totally optional, and the name is arbitrary, but you're probably going to need to load in a configuration file at some point, and now is as good a time as any. It's particularly useful when testing - you can set the screen mode so that you don't have to wait for the mode to change each time (and if you're on a multiple-monitor system, mess up your window layout ;-) ).

Then, the command-line arguments. We do these after settings.eng so that the command-line can 'override' the stored settings.

We set the profiler up to output to the logs (using our already-setup ProfileLogHandler). It's far from being the best output mechanism - ideally, we should be able to see stats on-screen while the game is running - but that's something we'll do later.

Then we start the main game loop itself (with CKernel::Execute()). Because we've not registered any tasks, this will return almost immediately.

Lastly we clean up our singletons.

If you build the project now, you should find that there are no unresolved dependencies, so it builds ok - running it will have the program start up and then exit. If you want to see for certain that it's running ok, add a log message in there (before CKernel::Execute(), probably). Let your mouth fall open in wonder and amazement; this is the blank slate of an engine upon which we build...

The Task Pool

The 'task pool' is the term I use to refer to the group of tasks that the engine is running at any given time. There are certain tasks that run pretty much all of the time - 'system tasks' - such as the timer or input tasks. These system tasks are what we're going to look at now.

Timer

The global timer task will be responsible for working out how many seconds have passed since the last frame. We can use that number to scale things like physics code, so that things move at the same speed across different machines:

class CGlobalTimer : public ITask
{
public:
  AUTO_SIZE;
  
  static float dT;
  static unsigned long lastFrameIndex;
  static unsigned long thisFrameIndex;

  bool Start();
  void Update();
  void Stop();
};

bool CGlobalTimer::Start()
{
  thisFrameIndex=SDL_GetTicks();
  lastFrameIndex=thisFrameIndex;
  dT=0;
  return true;
}

void CGlobalTimer::Update()
{
  lastFrameIndex=thisFrameIndex;
  thisFrameIndex=SDL_GetTicks();
  dT=((float)(thisFrameIndex-lastFrameIndex))/1000.0f;
}

void CGlobalTimer::Stop()
{

}

SDL_GetTicks() returns the number of milliseconds since SDL_Init() was called, which we store in thisFrameIndex. To work out the elapsed time for this frame, we subtract the previous frame's value from that value, and divide by 1000 (to convert from milliseconds to seconds). The result is stored in a public static variable for easy access (so technically we should make the CGlobalTimer a Singleton, to prevent anyone creating more than one of it, but I didn't because multiple inheritance is something I wanted to avoid, if possible).

Sound

The sound task will initialize and shutdown the sound system, as well as pausing all active sounds when the task is paused. When pausing, we need to store which channels are actually active so we know which ones to unpause - the game itself might have paused some channels for it's own ends, and we don't want to accidentally unpause them.

class CSoundTask : public ITask
{
public:
  bool Start();
  void OnSuspend();
  void Update();
  void OnResume();
  void Stop();

  AUTO_SIZE;

protected:
  CMMPointer<CMMDynamicBlob<bool> > isPaused;
};

bool CSoundTask::Start()
{
  if(FALSE==FSOUND_Init(44100, 32, 0))return false;
  return true;
}

void CSoundTask::OnSuspend()
{
  //pause all channels, storing the pause state in the isPaused array
  //once the states are stored we can use FSOUND_ALL to pause all
  //channels the easy way
  int chCount=FSOUND_GetMaxChannels();
  isPaused=new CMMDynamicBlob<bool>(chCount);
  for(int i=0;i<chCount;i++)
  {
    if(FSOUND_IsPlaying(i))
    {  
      isPaused->buffer[i]=true;
    }else{
      isPaused->buffer[i]=false;
    }
  }
  FSOUND_SetPaused(FSOUND_ALL,TRUE);
}

void CSoundTask::Update()
{
  //we don't need to do anything, FMOD does it all for us :)
}

void CSoundTask::OnResume()
{
  //unpause all the flagged channels
  if(isPaused)
  {
    int chCount=FSOUND_GetMaxChannels();
    for(int i=0;i<chCount;i++)
    {
      if(isPaused->buffer[i])FSOUND_SetPaused(i,FALSE);
    }
    isPaused=0;
  }
}

void CSoundTask::Stop()
{
  FSOUND_Close();
}

Input

The input task has to get SDL to update it's internal input information, and then it has to read that information out. Again, we use public static variables for easy access (so again, I should make this a Singleton, but I haven't).Something to note is that SDL_GetKeyState returns a pointer to SDL's internal array - so we shouldn't free it ourselves.

class CInputTask : public ITask  
{
public:
  CInputTask();
  virtual ~CInputTask();

  bool Start();
  void Update();
  void Stop();

  static unsigned char *keys;
  static CMMPointer<CMMDynamicBlob<unsigned char> > oldKeys;
  static int keyCount;
  
  static int dX,dY;
  static unsigned int buttons;
  static unsigned int oldButtons;

  static bool inline curKey(int index) { return (keys[index]!=0); }
  static bool inline oldKey(int index) { return ((*oldKeys)[index]!=0); }

  //some helper functions to make certain things easier
  static bool inline keyDown(int index)
      { return ( curKey(index))&&(!oldKey(index)); }
  static bool inline keyStillDown(int index)
      { return ( curKey(index))&&( oldKey(index)); }
  static bool inline keyUp(int index)
      { return (!curKey(index))&&( oldKey(index)); }
  static bool inline keyStillUp(int index)
      { return (!curKey(index))&&(!oldKey(index)); }

  static bool inline curMouse(int button)
      { return (buttons&SDL_BUTTON(button))!=0; }
  static bool inline oldMouse(int button)
      { return (oldButtons&SDL_BUTTON(button))!=0; }

  static bool inline mouseDown(int button)
      { return ( curMouse(button))&&(!oldMouse(button)); }
  static bool inline mouseStillDown(int button)
      { return ( curMouse(button))&&( oldMouse(button)); }
  static bool inline mouseUp(int button)
      { return (!curMouse(button))&&( oldMouse(button)); }
  static bool inline mouseStillUp(int button)
      { return (!curMouse(button))&&(!oldMouse(button)); }

  AUTO_SIZE;
};

bool CInputTask::Start()
{
  keys=SDL_GetKeyState(&keyCount);
  oldKeys=new CMMDynamicBlob<unsigned char>(keyCount);
  dX=dY=0;
  SDL_PumpEvents(); SDL_PumpEvents();
  return true;
}

void CInputTask::Update()
{
  SDL_PumpEvents();

  oldButtons=buttons;
  buttons=SDL_GetRelativeMouseState(&dX,&dY);

  memcpy((unsigned char*)(*oldKeys),keys,sizeof(unsigned char)*keyCount);
  keys=SDL_GetKeyState(&keyCount);
}

void CInputTask::Stop()
{
  keys=0;
  oldKeys=0;
}

What's with the oldKeys and oldButtons members? At any given time, if you check a key in the keys array, all you'll know is if the key is down; not if it's just been pressed, or if it's being held down, or if it's just been released, and so on. By comparing it to it's previous state, oldKeys, we can quickly see if it's going down, going up, or staying put. Same goes for the mouse buttons. That's what all those inline functions are for you could write a separate 'input event' task which watches for those sorts of conditions and translates them into 'events' in a queue - a little more useful for things like text entry (because otherwise you just have to check every key, every frame).

Renderer

It's time we got something significant on screen. The VideoUpdate task will be responsible for starting up and shutting down the video system, along with swapping the screen buffers (because we're working with double buffers). It's also the first part of the engine to use the settings mechanism - we're going to have the screen mode (width, height, and BPP) registered as settings.

class CVideoUpdate : public ITask  
{
public:
  CVideoUpdate();
  virtual ~CVideoUpdate();
  AUTO_SIZE;

  static int scrWidth, scrHeight, scrBPP;
  static CMMPointer<Dator<int> > screenWidth, screenHeight, screenBPP;

  bool Start();
  void Update();
  void Stop();
};

bool CVideoUpdate::Start()
{
  assert(screenWidth && screenHeight && screenBPP);

  if(-1==SDL_InitSubSystem(SDL_INIT_VIDEO))
  {
    CLog::Get().Write(LOG_CLIENT,IDS_GENERIC_SUB_INIT_FAIL,
        "Video",SDL_GetError());
    return false;
  }
  SDL_GL_SetAttribute( SDL_GL_ALPHA_SIZE, 8 );
  SDL_GL_SetAttribute( SDL_GL_RED_SIZE, 8 );
  SDL_GL_SetAttribute( SDL_GL_GREEN_SIZE, 8 );
  SDL_GL_SetAttribute( SDL_GL_BLUE_SIZE, 8 );
  SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );
  SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );

  int flags = SDL_OPENGL | SDL_ANYFORMAT | SDL_FULLSCREEN;

  if(!SDL_SetVideoMode(scrWidth, scrHeight, scrBPP, flags))
  {
    CLog::Get().Write(LOG_CLIENT, IDS_BAD_DISPLAYMODE,
        scrWidth, scrHeight, scrBPP, SDL_GetError());
    return false;
  }

  //hide the mouse cursor
  SDL_ShowCursor(SDL_DISABLE);

  return true;
}

void CVideoUpdate::Update()
{
  SDL_GL_SwapBuffers();
}

void CVideoUpdate::Stop()
{
  SDL_QuitSubSystem(SDL_INIT_VIDEO);
}

There. We also need to head back to the CSettingsManager, and add the following to CreateStandardSettings:

SETTING(int, CVideoUpdate::screenWidth,  CVideoUpdate::scrWidth,  "screenX");
SETTING(int, CVideoUpdate::screenHeight, CVideoUpdate::scrHeight, "screenY");
SETTING(int, CVideoUpdate::screenBPP,    CVideoUpdate::scrBPP,    "screenBPP");

Also, we add to DestroyStandardSettings:

CVideoUpdate::screenWidth  = 0;
CVideoUpdate::screenHeight  = 0;
CVideoUpdate::screenBPP  = 0;

The parameters for the SETTING macro are, in case you'd forgotten, the type, dator, variable to bind the dator to, and name for the setting within the manager. Finally, it's worth noting the static definitions of scrWidth/scrHeight/scrBPP:

int CVideoUpdate::scrWidth=800;
int CVideoUpdate::scrHeight=600;
int CVideoUpdate::scrBPP=16;

If no setting is given for screenX/screenY/screenBPP in the settings file or on the command line, no assignments will be made to the relevant dators and so scrWidth/scrHeight/scrBPP will not be changed from their initial values. Thus, set them up with your default values.

Pulling it all together (again)

Now that we've got these tasks, let's head back to our game-specific CApplication object, and try them out. We'll need to decide on priorities for each one - the priorities determine the order in which the tasks are run - and we'll need a simple task of our own to add to the mix, otherwise the app won't really do anything at all (including exit).

Here's the order of execution - the 'pipeline:'

CGlobalTimer  (priority: 10)
CInputTask  (priority: 20)
CSoundTask  (priority: 50)
COurTestTask  (priority: 100)
CVideoUpdate  (priority: 10000)

You can see that the tasks are fairly well spaced out; an app could add at least 9 tasks between the system ones, and the gap between the sound task and the video update is large enough for anything. Before we set up the pipeline itself, here's the test task:

class COurTestTask : public ITask
{
public:
  bool Start()
    {return true;}
  void Update()
    {
      glClear(GL_COLOR_BUFFER_BIT);
      if(CInputTask::mouseDown(SDL_BUTTON_LEFT))
        CKernel::GetSingleton().KillAllTasks();
    }
  void Stop(){};
  AUTO_SIZE;
};

Very simple. It'll just cause all tasks to shutdown when you press the left mouse button, and clears the screen in the meantime. So, now we go back to CApplication::Run, and just before calling CKernel::Execute(), we create tasks and put them into the pipeline:

//it's probably a good idea to have all the system tasks together.
//The priority system means the tasks can officially be created in
//any order (though bear in mind that the CVideoUpdate task must be
//added to the kernel before any task using GL functions in its 
//Start() method, because SDL_VIDEO will not have been initialized).
//We'll create the system tasks first and then our game-specific ones
//afterwards. It also ensures that when we get to game-specific tasks,
//things like FSOUND_Init() have been called.

CMMPointer<CGlobalTimer> globalTimer = new CGlobalTimer();
globalTimer->priority=10;
//the CMMPointer<ITask> expression here is used to typecast
//the pointer from CGlobalTimer* to ITask*
CKernel::GetSingleton().AddTask(CMMPointer<ITask>(globalTimer));

CMMPointer<CInputTask> inputTask = new CInputTask();
inputTask->priority=20;
CKernel::GetSingleton().AddTask(CMMPointer<ITask>(inputTask));

CMMPointer<CSoundTask> soundTask = new CSoundTask();
soundTask->priority=50;
CKernel::GetSingleton().AddTask(CMMPointer<ITask>(soundTask));

videoTask = new CVideoUpdate();
videoTask->priority=10000;
CKernel::GetSingleton().AddTask(CMMPointer<ITask>(videoTask));

//game-specific tasks:

CMMPointer<COurTestTask> tt=new COurTestTask();
tt->priority=100;
CKernel::GetSingleton().AddTask(CMMPointer<ITask>(tt));

Build and test that - you should get a blank screen, which exits when you click the mouse. In the word of many millions of people, 'Yes!'

The Code

The code for this article contains a bit more than what we've seen here - I've written a very (and I mean very) basic implementation of Pong. Move your paddle using the mouse; click (or just lose the game :P ) to exit. See what you can do with it - if you need ideas, I'd suggest getting the ball to come off the paddle at different angles depending on where you hit it, or maybe adding sound. The relevant code is in CPongTask, in main.cpp; I recognize that you can't do much impressive stuff without texturing, which is coming soon. Still, consider it an exercise in pure gameplay - if you can make that Pong game fun, without using any fancy graphics and effects further than shaded polygons, then major kudos; I'll be truly impressed. Maybe it should be a lounge mini-contest.

There are also some updates to code from previous articles, based on feedback I've had from people (mostly minor bugfixes). The most important change is probably in the memory manager - previously, I'd overlooked stack objects, which could have lead to *serious* problems:

CSomeIMMObjectDerivedClass obj;
CMMPointer<CSomeIMMObjectDerivedClass> ptr=&obj;
ptr=0;
IMMObject::CollectGarbage();
//heap fault - obj has a reference count of zero, but we
//shouldn't call delete() because we didn't allocate it using new()!

The memory manager has now been updated to handle them. I believe I've commented the code; the best documentation, however, is the discussion that lead to the discovery (and later fixing) of the problem, in the discussion thread for Enginuity part 2. Indeed, all the discussion threads have been rich sources of information and ideas for me (and others too, they tell me :) ).

Conclusion

Well, that's a basic (and I mean basic) engine finished. You could stop reading now, and just work with what we've built up together; it's a pretty stable base for any project. Maybe you'd care to rewrite it with DirectX or change some other fundamental feature; I hope my articles have given you enough understanding of the way the engine works to allow you to do that.

However, as much as you can stop reading, doesn't mean I'm going to stop writing. After all, I haven't met my specification yet - there's still the networking system to be implemented, along with the beginnings of a 3D graphics system... but more importantly, there's no games built on this engine yet! It's no good if games can't actually *use* it.

I'd just like to take this opportunity to thank the people who've supported me so far - eldee, my loyal proofreader; Oluseyi, my seems-loyal-enough-but-I-reckon-has-a-hidden-agenda-yeah-buddy-I'm-onto-you proofreader; and all the many people who gave me their comments and feedback, through email, the forums, and IRC. I'll try not to let you down as I progress. :)

So, I'm far from finished. Next article I plan to cover textures and fonts, as well as the mysterious Interpolators and Triggers systems. In the meantime, I recommend you visit the 'Discuss this article' link to point out all my mistakes and pick apart my methods; or, of course, you can still email me (rfine at tbrf dot net).

 

Enginuity, Part V
Serialization, Triggers/Interpolators, and the Build Stamp or, I Can't Think Of A Witty Subtitle For This One
by Richard "superpig" Fine

Get the source code for this article here.

I'm back, after a bit of a break to build up the codebase and the example game a bit. And to catch up on Real Life . ;-)

Many thanks to all the people who've written in recently, urging me to continue with the series; I assured you all that I was not stopping, and this should be proof of that. From the list of topics I've got to cover, I estimate that our first demo game - CY - should arrive around article 8. So I've still got more to go, and I plan to continue after that, so...

This article I'm going to show off a few tricks I came up with for Enginuity which aren't really something that every engine *needs* - they come under the heading of 'nifty features,' but you can get along without them. However, nifty as they are, I thought I'd show them to you. Four things: Serialization, the Triggers and Interpolators systems, and the build stamp.

Serialization

You'll like this one, you really will. I know that when I thought of it up in Edinborough, I was still grinning about it when the train reached Birmingham. (Doesn't being easily amused just *rock* on long journeys? :-) )

'Serialization' is the general term for the processes of 'flattening' your data, for byte-stream uses such as storage in a file or transmission over a network, and then 'inflating' it again at the other end. Typical situations are messages for networked games, saved games, loading levels... hell, any custom resource that is loaded from or saved to a file needs a serialization mechanism (and the 'standard' resources, like bitmaps and sounds, need them too, but as far as Enginuity is concerned the libraries we use provide their own mechanisms).

There are a large number of problems. Firstly, what data do you need to save out or load in? Your entire heap? The positions and velocities of every single object and entity, down to individual particles in the particle systems, for everything that is loaded into memory? Probably not. Then, there's the problem of actually structuring that data - after all, saving pointers straight to file is no good when you load them back in again, so you can't just do a dump of your objects. You need to determine a 'flat' structure for them - something I call a 'serialization structure.' Dators are a bit slow, and only really need to be used when a variable is going to be set by name.

If you've ever worked with Quake BSP files, you'll have come across these 'serialization structures.' When a BSP file is actually in memory there's quite a bit more information than when on disk - a fair number of pointers between objects, for example - and that information is constructed when the level is loaded. The serialization structures - which, in Quake's case, are quite literally C structures - dictate how each piece of information in the BSP file is laid out - how a block of 32 bytes is divided into 4 longs, 6 ints, and 4 chars.

So, while the first major problem - what to serialize - will depend on the situation, the second problem - how to do it - is something we can address with a strong framework. See, creating an entire C structure for each piece of information you want to serialize is not just messy, it's also inflexible - it's fixed at compile-time. I'm going to present to you a mechanism that uses function calls, rather than C structures, to establish serialization structures. That way you can easily control which functions get called through something as basic as if() blocks.

There's also one of the original design requirements to be taken into account - the requirement that the engine be cross-platform. Well, while it's possible to write tools to load data files, swap the bytes around, and save them out again for different architectures, it's also a pain - and something which, in a time-critical situation, can really bite. It stinks of 'primary platform, plus ports' rather than 'cross-platform development;' it also requires the development of tools for each individual project, because a generalised program wouldn't know about the actual structure of the data and thus wouldn't know which bytes need swapping. The technique we look at today is completely architecture-independent; it actually uses SDL_Net's buffer read/write macros to serialize all data into network byte order (big-endian). If you don't like depending on SDL_Net to do that, it's very simple to replace the macros with your own equivalents.

Firstly, let's look at a typical scenario. Say we have a ball object, CBall, and we want serialization functions on it. All it needs, to begin with, is position information.

CBall::Flatten(ostream &out)
{
 out << position.x;
 out << position.y;
}

CBall::Inflate(istream &in)
{
 in >> position.x;
 in >> position.y;
}

Now, that works pretty well in simple situations, but it's potentially very problematic. Firstly, it's inflexible in that it depends on having STL streams to serialise to/from - that may well not be the case. Secondly, it's either going to be using a text-based format for storing the data - which is inefficient - or a binary format which will not necessarily be cross-platform. Thirdly, there's no real scope for error in there - things like buffer overflow aren't really tracked. Lastly, the existence of two seperate serialization functions means that you have to keep them both synchronized - some may argue that it's just one of the habits of a good programmer, like pairing calls to 'new' with calls to 'delete,' but I still maintain that everyone makes mistakes, and the smaller the chances of them happening, the better.

It's 'hard-coded.' I don't just mean that if you change it you need to recompile - soft code often needs that too - but changing it requires changes in more than one place, and, depending on the change, could potentially require changes in many places - adding support for a new type of source or target, for example. The solution we're going to look at is more 'soft-coded' - the serialization structure is defined in one place and one place only, the system is pretty extensible, and - best of all - you can accurately calculate other things about the serialization structure, like how much space it *actually* needs (rather than just hoping that a sizeof() is big enough).

What we have is simple - our objects support a 'serialize' method, which takes a single pointer to a 'target' object as its parameter. That 'serialize' function is all an object needs to provide to work with the system. That may sound a little familiar to those of you who have some MFC experience, but even MFC requires that you define the structure twice - once for loading, once for saving. The serialize function calls methods on the 'target' object, and those calls define the structure: the target object's methods are things like IOChar, IOFloat, IOLong, IOString, and so on. See where I'm going with this yet?

With each of those calls, a reference to the variable in question is passed. So, IOChar(char &value), IOFloat(float &value), etc. Then - and here comes the cruncher - we derive different objects from the base 'target' interface - CSerialFlattener, CSerialInflator, CSerialSizer, and so on. They can then write the values to a buffer, read the values in from a buffer, or simply add to a running total of bytes written. The object itself never touches the actual read/write buffer - assuming there is one - and any change to the structure is felt across all operations on the structure. You could write 'serializer objects' to do pretty much anything - count the number of different types of variable used, generate code for a C-structure based on the serialization structure, whatever. The first three have suited me just fine so far. By forcing buffer read/writes to happen through a sort of 'visitor' object, we can do things like ensure that strings are always written out in a consistant way (I opt for size followed by unterminated string, but you could just as easily make all strings null-terminated), or check for buffer overflow/underflow (because underflow can be just as bad a sign as overflow).

In fact, we can even take advantage of another nice feature of C++ - overloading. Instead of seperate IOChar/IOFloat type names for things, we just have a single IO() function overloaded for different types. Though, don't go too far - this might seem like one of the places where templates would work well, but remember that each type will probably need to be handled differently, making templates useless (because they're for applying the *same* operations to different types). Using overloading, though, is much nicer; it means that we don't have to check that the type of the variable matches the function, because the compiler will pick the correct function for us.

The end result is a system which is a little bit like C++ iostreams, but does away with the concept of 'input' or 'output.'

Let's pull out some code. Firstly, our base ISerializer interface:

class ISerializer
{
public:
 virtual void IO(unsigned char &value)=0;
 virtual void IO(unsigned long &value)=0;
 virtual void IO(std::string &str)=0;
};

If that looks a bit short, it's just because I've not needed any more types than unsigned char, unsigned long, and std::string just yet. It's pretty easy to add new types, as you'll understand soon. Let's start looking at the Serializers themselves with the simplest one, the CSerialSizer:

class CSerialSizer : public ISerializer
{
protected:
 unsigned long length;
public:
 CSerialSizer() { length=0; }

 void IO(unsigned char &value)
 { ++length; }

 void IO(unsigned long &value)
 { length+=4; }

 void IO(std::string &str)
 { IO(length); length+=str.length(); }

 unsigned long getLength() { return length; }
};

Pretty simple. A char adds 1 byte to the size; an unsigned long adds 4 bytes. Why do I use literals instead of sizeof() expressions? Because - while in this case, the sizes of char and unsigned long are pretty much guaranteed - we want to be writing out the size of the data when serialized, rather than the size of the data when in memory. If I were to add an 'unsigned int' overload, would the size of it be 16 bits or 32 bits? Because we're trying to keep this cross-platform, we can't really guarantee either; and given that we're trying to keep the data *itself* cross-platform too, we have to pick one and stick with it (I'd probably opt for 32 bits). Thus, the size of an 'unsigned int' when serialized - 4 bytes - might not correspond to the size of an 'unsigned int' when in memory - 2 bytes. For consistency I decided to write things the same way for the non-ambiguous types too; you're perfectly free to use sizeof() if you want, just bear in mind that sizeof() isn't always the right answer.

Incidentally, the 'length' variable is protected, rather than private, for a simple reason: you will quite probably introduce your own basic data structures in projects, which should be kept specific to that project. So, to minimize polluting the Enginuity codebase itself with overloads for your custom data types, you only need to overload in once place - ISerializer - and then you can derive your own CExtendedSerialSizer (or whatever) which implements those new overloads; the Enginuity serializer classes themselves will (aside from ISerializer itself) be unchanged. (If you wanted to be *really* neat and avoid polluting the Enginuity codebase all together, you could create another interface class - IExtendedSerializer - which has ISerializer as a virtual public base class. Then, you derive your CExtendedSerialSomething from both CSerialSomething *and* IExtendedSerializer; the end result should be an extended class which has overloads from both base classes in it, and you can still use IExtendedSerializer as an interface to all your extended serializer objects).

When you use CSerialSizer (or your own extension of it), it'll probably be to allocate a buffer for use with a CSerialSaver.

class CSerialSaver : public ISerializer
{
protected:
  unsigned char *buffer;
  bool bHasOverflowed;
  unsigned long length;
  unsigned long bytesUsed;
public:
  CSerialSaver(unsigned char *buf, unsigned long size)
  {
    buffer=buf; length=size; bytesUsed=0; bHasOverflowed=false;
  }

  void IO(unsigned char &value)
  {
    if(bHasOverflowed)return; //stop writing when overflowed
    if(bytesUsed+1>length){bHasOverflowed=true; return; }
    *buffer=value;
    ++buffer; ++bytesUsed;
  }
  void IO(unsigned long &value)
  {
    if(bHasOverflowed)return; //stop writing when overflowed
    if(bytesUsed+4>length){bHasOverflowed=true; return; }
    SDLNet_Write32(value,buffer);
    buffer+=4; bytesUsed+=4;
  }
  void IO(std::string &str)
  {
    unsigned long l=str.length();
    IO(l);
    if(bHasOverflowed)return;
    if(bytesUsed+l>length){bHasOverflowed=true; return; }
    memcpy(buffer,str.c_str(),l);
    buffer+=l; bytesUsed+=l;
  }

  bool hasOverflowed() { return bHasOverflowed; }

  //should be equal to 0 when we're done
  long getFlow() { return length-bytesUsed; }
};

There. The constructor takes a pointer to the buffer you want it to fill, along with the size of that buffer (so it can track when it's overflowing). Then, we have three overloads. The first two are very similar: they check that the overflow flag hasn't been set (and if it has, they bail out). Then, they check that the write wouldn't *cause* the buffer to overflow (and it if would, flag the overflow and bail out). Then they perform the write itself; the unsigned char overload simply copies through the byte, while the unsigned long overload uses an SDL_Net macro to make sure the value is written out in network byte order (it's a simple macro, so if you don't like depending on SDL_Net, it's easy to replace). Then, each increments the buffer pointer (the current write position) and the number of bytes used up.

The last overload - std::string - is pretty similar, but it actually calls one of the other overloads to write out the size of the string before the string itself. You can create such 'composite serial members' in this way; an overload for a vector class, for example, would probably just be implemented using three calls to IO(float). (If you're using my IExtendedSerializer suggestion, that's one of the beautiful bits - you can actually implement the overload in the base IExtendedSerializer class, and when you later derive from it with CSerialSaver/CSerialLoader the IO calls from the overload will be mapped to the correct virtual functions. That is, your extended overload calls IO(long), which successfully goes through to the CSerialSomething that you extended).

The last two functions, hasOverflowed() and getFlow(), are for error detection. The first of the two is pretty simple - it tells you whether the overflow flag has been set (there was an attempt to write more data than the buffer could hold). The second is for detecting underflow; this isn't such a serious error as overflow, but it still might be indicative of something not having worked correctly - especially if you're using a buffer with the size given by a CSerialSizer and the object you're serialising hasn't changed. The serialisation structure should be exactly the same in both cases, so if it hasn't filled the buffer perfectly, something's screwy. If you don't use a CSerialSizer, and just pass a buffer that you think is large enough, then you can use the flow to work out how much of the buffer was actually used (to save you writing out the extra padding at the end).

Now, the CSerialLoader:

class CSerialLoader : public ISerializer
{
protected:
  unsigned char *buffer;
  bool bHasOverflowed;
  unsigned long length;
  unsigned long bytesUsed;
public:

  CSerialLoader(unsigned char *buf, unsigned long size)
  {
    buffer=buf; length=size; bytesUsed=0; bHasOverflowed=false;
  }

  void IO(unsigned char &value)
  {
    if(bHasOverflowed)return; //stop writing when overflowed
    if(bytesUsed+1>length){bHasOverflowed=true; return; }
    value=*buffer;
    ++buffer; ++bytesUsed;
  }
  void IO(unsigned long &value)
  {
    if(bHasOverflowed)return; //stop writing when overflowed
    if(bytesUsed+4>length){bHasOverflowed=true; return; }
    value=SDLNet_Read32(buffer);
    buffer+=4; bytesUsed+=4;
  }
  void IO(std::string &str)
  {
    unsigned long l;
    IO(l);
    if(bHasOverflowed)return;
    if(bytesUsed+l>length){bHasOverflowed=true; return; }
    char *szBuf=new char[l+1];
    szBuf[l]=0;
    memcpy(szBuf,buffer,l);
    str=szBuf;
    delete[] szBuf;
    buffer+=l; bytesUsed+=l;
  }

  bool hasOverflowed() { return bHasOverflowed; }

  //should be equal to 0 when we're done
  long getFlow() { return length-bytesUsed; }

};

Pretty damn similar to the CSerialSaver, I think you'll agree. The constructor is exactly the same; the first two IO overloads simply flip the assignments over, so that the buffer is now copied to the value rather than the other way around. The third overload looks a little more complex, but it's actually still pretty simple - it reads back in the size as an unsigned long, and then allocates a temporary buffer to hold the string; reads the string, converts it to a std::string, and delete the temporary buffer. Once again, at the end, we have hasOverflowed() and getFlow(), doing exactly the same thing as before. Underflow is more of a problem here, as it means the whole buffer wasn't read in - if you thought you'd handed it a complete resource, evidently the serialization structure of the data is different to that of the object, so the data is either corrupt or you're trying to feed it into the wrong object.

Let's take a look at a sample serialization function on an object, then. This is taken from the high-scores table code in the upcoming demo game, CY. Here are the relevant parts of the class definition:

class CHighScoresTable : public Singleton<CHighScoresTable>  
{
public:
  CHighScoresTable();
  virtual ~CHighScoresTable();

  void Serialize(ISerializer *s);

  bool Load();
  bool Save();

  struct hs 
  { 
    std::string name; 
    unsigned long score; 
  }scores[10];

  inline int getScoreCount() const { return 10; }
};

While there are seperate Load/Save functions in this object, they don't actually touch the serialization structure - all they do is create the Serializer objects and work with the highscor.dat file, as you'll see.

The constructor initializes all the values in the table to the default highscores. If the highscor.dat file can't be opened, the scores will reset to defaults, and then get written out in a new file. So, to reset the high scores you can just delete the highscores file.

CHighScoresTable::CHighScoresTable()
{
  for(int i=0;i<10;i++)
  {
    scores[i].name="Nobody";
    scores[i].score=100-i*10;
  }
}

Here's the serialization function itself. For each entry in the table, it just gives the name (a std::string) and score (an unsigned long).

void CHighScoresTable::Serialize(ISerializer *s)
{
  for(int i=0;i<10;i++)
  {
    s->IO(scores[i].name);
    s->IO(scores[i].score);
  }
}

This is how loading the table is actually done. The function has no relation to the serialization structure; changes to the Serialize() function will not affect it. All it does is open the file, read in the contents, and hand it to the Serialize function (in a CSerialLoader) to be actually loaded.

bool CHighScoresTable::Load()
{
  unsigned long size=0;

  FILE *fp=fopen("highscor.dat","rb");
  if(!fp)return false;

  fseek(fp,0,SEEK_END);
  size=ftell(fp);
  fseek(fp,0,SEEK_SET);

  unsigned char *buffer=new unsigned char[size];
  fread(buffer,1,size,fp);
  fclose(fp);

  CSerialLoader sl(buffer, size);
  Serialize(&sl);
  assert(sl.getFlow()==0);

  delete[] buffer;

  return true;
}

And here's the complimetary save function. Again, it opens the file; it uses both a CSerialSizer *and* a CSerialSaver to get the size of the data to write out, though in fact this could be made more efficient by writing a CFileSaver which writes directly to the file rather than to a buffer. The same goes for the Load function.

bool CHighScoresTable::Save()
{
  FILE *fp=fopen("highscor.dat", "wb");
  if(!fp)return false;

  CSerialSizer ss;
  Serialize(&ss);
  unsigned long size=ss.getLength();

  unsigned char *buffer=new unsigned char[size];
  CSerialSaver sv(buffer,size);
  Serialize(&sv);
  assert(sv.getFlow()==0);

  fwrite(buffer,size,1,fp);
  fclose(fp);
  delete[] buffer;

  return true;
}

I think you'll agree that's pretty simple, especially when you're dealing with a large number of different objects - if you've got, say, a set of 100 objects of varying classes, all implementing some kind of ISerializable interface, then you can have a single save/load function pair to loop through all of them and call Serialize() functions on them.

Now, the method isn't without its caveats. For one, it requires that you plan your serialization structures with a bit more care; for example, if the number of entries in a serialization structure is going to be variable, you *have* to record that number at the beginning, rather than simply reading/writing till all the bytestream is used up. Such structures, though, are what I'd call 'deterministic;' you always have the information to read/write without needing any knowledge at all of the underlying byte-stream. After all, if you had serializers which sent data to and from sockets directly, you wouldn't necessarily *have* an end-of-file to test against.

Triggers/Interpolators

It's time to look at a couple more 'utility' objects - 'utility' in that they're internal engine objects that you don't really use on their own. However, that doesn't stop me from having found them to be some of the most useful objects in the engine. They're fairly similar in design and operation - they just behave a little differently - which is why I'm presenting them together.

Interpolators

Interpolators are particularly useful objects when it comes to polish and effects.

Quite simply, Interpolators take an input value - most often the clock - and use it to interpolate an output value. The output is set by reference, so the interpolator can directly change it with no problems. Want a fade-out effect? Simply set up an interpolator with your global alpha value as the output. It's also very simple to set up different types of interpolation - plain linear interpolation may do for many things, but smoother methods - quadratic and cubic - will be shown here as well.

class IInterpolator : public IMMObject
{
protected:
  float ⌖
  static std::list< CMMPointer<IInterpolator> > interpolators;
public:
  IInterpolator(float &t);
  virtual ~IInterpolator();

  bool bFreeze;

  virtual void Update(float dt)=0;
  void Kill();

  friend class CInterpolatorUpdater;
  AUTO_SIZE;
};

We're going to assume that all interpolators work with float values (I can't think of many situations where they wouldn't be - though if you *really* needed to, you could set it up with templates). So, we have a float reference to our 'target' value - our output. We also have a list of CMMPointers to IInterpolators.

This next one took me a while to get right. Interpolators are sort of self-referencing objects. When you create one, it will add itself to the 'interpolators' list using a CMMPointer - which means that even if you release all your pointers to the interpolator, it'll still be held in existence by that pointer in the list. Why is that useful? It means you can create an interpolator, and drop it out of scope, without it dying. It's going to need to be alive to function. When it comes down to it, you don't even need to keep a local copy of the interpolator - you can just do 'new CLinearInterpolator(...);' as a standalone statement, and this will handle the rest. Of course, if you do that you lose control of the interpolator - you can't pause it or kill it unless it pauses or kills itself. A possible extension to this system, then, would be a way to give an interpolator an ID - a string or unique number - which you give the interpolator when it is created, and can then be used to retrieve a pointer to the interpolator later on, so you can (for example) kill it.

Now we get to the public functions. There's the constructor and destructor - the constructor taking the initial value for 'target.' bFreeze is a boolean flag which you can set to 'freeze' the interpolator - it will not be updated while it is frozen.

Update() is the function derived classes must implement. It's that function which 'powers' the interpolator - does the calculation and assigns to the output value. It takes dT - 'delta time' - as a parameter, because 95% of our interpolators will be time-based so, unless you're going for micro-optimization and consider the time taken to pass the argument too much, there's no point having them all fetch the time themselves. If an interpolator doesn't need it, it ignores it.

Kill() is a simple function to remove the interpolator from it's own list. If you call Kill() on an interpolator, and then drop all references to it, it really *will* be destroyed. Technically, you can call Kill() on it and still keep references to it, but it won't be updated any more (unless you call IInterpolator::Update() on it yourself each frame).

Lastly, it marks CInterpolatorUpdater (we'll meet it in a minute) as a friend class, and then uses the expected AUTO_SIZE macro to fulfill abstract functions on IMMObject, from which it derives.

Here's the (brief) implementation of the non-abstract functions:

IInterpolator::IInterpolator(float &t) : target(t)
{
  interpolators.push_back(this);
  bFreeze=false;
}

IInterpolator::~IInterpolator()
{

}

void IInterpolator::Kill()
{
  std::list< CMMPointer<IInterpolator> >::iterator it=
      (std::find(interpolators.begin(),interpolators.end(),this));
  if(it!=interpolators.end())
    (*it)=0;
}

The constructor sets up the target reference, and adds itself to the list of pointers. It also has the interpolator start in a non-frozen state by default. The destructor does nothing (it's only there to make sure derived destructors works properly). Lastly, Kill() finds the interpolator in the list and (assuming it can find it) sets its pointer to zero, releasing it.

So... we've got all these interpolators knocking about with Update() functions on them, all in a list - sounds fairly easy to do. We'll use a task for it:

class CInterpolatorUpdater : public ITask
{
public:
  bool Start();
  void Update();
  void Stop();
  AUTO_SIZE;
};

That's about as minimial a task as you can get.

bool CInterpolatorUpdater::Start() { return true; }
void CInterpolatorUpdater::Stop() { IInterpolator::interpolators.clear(); }
void CInterpolatorUpdater::Update()
{
  PROFILE("Interpolator task");
  std::list< CMMPointer<IInterpolator> >::iterator it,
            ite=IInterpolator::interpolators.end(), itT;
  for(it=IInterpolator::interpolators.begin(); it!=ite; it++)
  {
    if((*it).isValid())
    {
      (*it)->Update(CGlobalTimer::dT);
    }else{
      //remove invalid entries from the list, just to keep things fast
      itT=it;
      --it;
      IInterpolator::interpolators.erase(itT);
    }
  }
}

Start() does nothing (it doesn't need to do anything). Stop() kills the list of pointers - thus releasing all interpolators when the task is shut down (otherwise they'd still be in scope when CollectRemaningObjects gets called, giving 'unreleased object' reports in the logs). Update() simply loops through the list of interpolators; for each interpolator, it tests that the pointer is actually valid, and if it is, calls Update() on it. If not, it removes that entry from the list - no point iterating over dead entries, and as more and more interpolators are created and destroyed, those dead entries would build up.

So, that's our basic interpolator system. Let's see some objects we'll actually use!

class ITimebasedInterpolator : public IInterpolator
{
protected:
  float elapsedTime, totalTime;
  virtual void Calculate()=0;
public:
  void Reset();
  void Update(float dt);  
  ITimebasedInterpolator(float &targ, float time);
  AUTO_SIZE;
};

This is the base class for interpolators which interpolate from start to finish across a fixed time period. Note that there are plenty of interpolators that *use* time but are not considered time-based - a sine-wave interpolator would be an example, an interpolator which oscillates its target value at a given phase, amplitude and frequency for an indefinite period of time. This base class implements Update() - which updates the elapsed time and checks to see if the total time has been exceeded (in which case the interpolator expires, Kill()ing itself). There's also a Reset() function, which sets elapsedTime back to zero (to 'restart' the interpolator). However, it adds an abstract function of its own - Calculate - which the classes below implement to work out the output value in their own specific ways:

class CLinearTimeInterpolator : public ITimebasedInterpolator
{
protected:
  float startVal, endVal;
  void Calculate();
public:
  CLinearTimeInterpolator(float &targ, float time, float sV, float eV);
  AUTO_SIZE;
};

class CQuadraticTimeInterpolator : public ITimebasedInterpolator
{
protected:
  float startVal, midVal, endVal;
  void Calculate();
public:
  CQuadraticTimeInterpolator(float &targ, float time,
                             float sV, float mV, float eV);
  AUTO_SIZE;
};

class CCubicTimeInterpolator : public ITimebasedInterpolator
{
protected:
  float startVal, midVal1, midVal2, endVal;
  void Calculate();
public:
  CCubicTimeInterpolator(float &targ, float time, float sV,
                         float mV1, float mV2, float eV);
  AUTO_SIZE;
};

How do these interpolators work? To answer that, we're going to need to do a little math.

Firstly, we can treat the time as a value between 0 and 1 - 0 means no time has elapsed, and 1 means all time (totalTime) has elapsed. Call that value 'b.' In a linear interpolator, we want a 'b' value of 0 to produce the start value, and a 'b' value of 1 to produce the end value. A 'b' value of 0.5 should produce a value half-way between the start and end.

We could say that the start value is equal to 'startValue * 1 + endValue * 0' and that the end value is equal to 'startValue * 0 + endValue * 1.' In fact, for any value through the interpolator, it'll be 'startValue * someNumber + endValue * someOtherNumber.' someNumber and someOtherNumber will always add up to 1 - that is, 'one whole value.' They're blending weights.

When 'b' is 0 someOtherNumber is 0, and when 'b' is 1 someOtherNumber is 1 - it doesn't take too much effort to suppose that someOtherNumber=b. Given that someOtherNumber + someNumber = 1, someNumber must = 1 - b. We'll call that 'a.'

So, in a linear interpolator, the output is 'a * startVal + b * endVal.' And if you look at the code:

void CLinearTimeInterpolator::Calculate()
{
  //calculate b, keeping it clamped to the range [0,1]
  float b=clamp(elapsedTime/totalTime,0,1);
  target = startVal*(1-b) + endVal*b;
}

Exactly what we said. How about the next interpolators, though? Are they quite as simple?

Nearly. We've established that '(a+b)=1'. That means that '(a+b)^2=1' (because 1^2=1). If you multiply out (a+b)^2, you get 'a^2 + 2ab + b^2' - three values. If we add to our startValue and endValue a 'middleValue,' we can do 'a^2 * startValue + 2ab * middleValue + b^2 * endValue.' The placement of the middleValue with respect to the start and end values will affect the 'steepness' of things at each end - for a sudden fade-in and then gradual fade-out, you could use a quadratic interpolator with the middleValue near the startValue. Fun fact: quadratics were how Quake 3 did its curvy surfaces ('bezier patches').

void CQuadraticTimeInterpolator::Calculate()
{
  float b=clamp(elapsedTime/totalTime,0,1), a=1-b;
  target = startVal*a*a + midVal*2*a*b + endVal*b*b;
}

The theory extends. If '(a+b)^2=1' produces an expression with 3 terms - 'coefficients' - then it's not a tremendous leap of the imagination to say that '(a+b)^3' would produce 4 terms. That's right - 'a^3 + 3ba^2 + 3ab^2 + b^3' - so we can plug four values into our interpolator. The expression (a+b)^3 is 'a plus b cubed,' thus this is a 'cubic' interpolator.

It's possible to have an interpolator which accepts any number of values. Given 'n' values, you just expand '(a+b)^(n-1)' to get your coefficients. It follows a nice pattern - for term 'r' out of a total of 'n' terms, the coefficient is something like 'nCr * a^r * b^(n-r).' Google for the 'binomal theorem' if you want to know more; more terms mean more calculation time, though, and cubic interpolation is usually good enough for me.

void CCubicTimeInterpolator::Calculate()
{
  float b=clamp(elapsedTime/totalTime,0,1), a=1-b;
  target = startVal*a*a*a + midVal1*3*a*a*b + midVal2*3*a*b*b + endVal*b*b*b;
}

The only thing that remains:

void ITimebasedInterpolator::Update(float dt)
{
  if(bFreeze)return;
  elapsedTime+=dt;
  Calculate();
  if(elapsedTime>totalTime)
  {
    Kill();
  }
}

Triggers

Triggers, like interpolators, are small objects that you can chuck around pretty liberally. They have a task updating them in the same way as the interpolators, but rather than working with changing an output, instead they monitor an input. Again, the input is set by reference; the idea is that you set a trigger up with a variable to 'watch' and a functor to call when a certain condition is met, and then let it get on with things; "don't call us, we'll call you."

class ITrigger : public IMMObject
{
public:
  ITrigger(Functor *h, bool fo);
  virtual ~ITrigger();

  void Kill();
protected:
  CMMPointer<Functor> handler;
  bool bFireOnce;

  virtual bool Test()=0;

  static std::list< CMMPointer<ITrigger> > triggerList;

  friend class CTriggerTask;

private:
  void Tick();
};

You should spot some similarities to the IInterpolator base class; there's the friend declaration, and the list of memory-managed ITrigger pointers. There's also that Kill() function, to remove a trigger before it expires (or if, indeed, it's set not to expire). Notice that the base class doesn't have a reference to an input variable - that's because unlike the Interpolators, we're going to allow Triggers to work with any type (not just float).

ITrigger::ITrigger(Functor *h, bool fo)
{
  handler=h;
  bFireOnce=fo;
  triggerList.push_back(this);
}

ITrigger::~ITrigger()
{

}

void ITrigger::Kill()
{
  std::list<CMMPointer<ITrigger> >::iterator it=
      std::find(triggerList.begin(), triggerList.end(), this);
  if(it!=triggerList.end())
    (*it)=0;
}

void ITrigger::Tick()
{
  if(Test())
  {
    (*handler)();
    if(bFireOnce)
    {
      Kill();
    }
  }
}

Again, all fairly familiar stuff. The constructor handles the self-referencing list stuff again, and the Kill() function has just changed interpolatorList to triggerList. The Tick() function is the equivalent of the Update() function in the interpolators, and as such is called every frame. The Test() function performs the actual test - in most derived classes it'll be a one-line function, as you'll see. If it returns true - that is, the test condition is satisfied - then the handler is called, and the trigger is destroyed (if it's been set to only fire once).

class CTriggerTask : public ITask
{
public:
  bool Start();
  void Update();
  void Stop();
  AUTO_SIZE;
};

bool CTriggerTask::Start() { return true; }
void CTriggerTask::Stop() { ITrigger::triggerList.clear(); }
void CTriggerTask::Update()
{
  PROFILE("Trigger task");
  std::list< CMMPointer<ITrigger> >::iterator it,
        ite=ITrigger::triggerList.end(), itT;
  for(it=ITrigger::triggerList.begin(); it!=ite; it++)
  {
    if((*it).isValid())
    {
      (*it)->Tick();
    }else{
      itT=it;
      --it;
      ITrigger::triggerList.erase(itT);
    }
  }
}

Identically minimalistic. (This one actually *was* a copy-and-paste job).

Now, onto some derived classes. I use the names 'subject' and 'object' for the input and the thing it's tested against ('subject-predicate-object', where predicate is the test itself):

template<class T>
class CEqualsTrigger : public ITrigger
{
protected:
  T &subject;
  T object;
public:
  CEqualsTrigger(T& s, T o, Functor *h, bool fo=true)
    : ITrigger(h,fo), subject(s)
  {
    object=o;
  }

  bool Test(){return (subject==object);}

  AUTO_SIZE;
};

You can now see why most of the Test() functions will be one-line jobs. Any type you want to use with the triggers system is going to need operators for whatever test you want to perform, of course - you won't be able to create a CEqualsTrigger<SomeClass> if SomeClass doesn't provide an == operator (you'll get a compiler error). You'll also need assignment operators - for the 'object' parameter, at the very least.

template<class T>
class CNotEqualsTrigger : public ITrigger
{
protected:
  T &subject;
  T object;
public:
  CNotEqualsTrigger(T& s, T o, Functor *h, bool fo=true)
    : ITrigger(h,fo), subject(s)
  {
    object=o;
  }

  bool Test(){return !(subject==object);}

  AUTO_SIZE;
};

template<class T>
class CLessTrigger : public ITrigger
{
protected:
  T &subject;
  T object;
public:
  CLessTrigger(T& s, T o, Functor *h, bool fo=true)
    : ITrigger(h,fo), subject(s)
  {
    object=o;
  }

  bool Test(){return (subject<object);}

  AUTO_SIZE;
};

template<class T>
class CGreaterTrigger : public ITrigger
{
protected:
  T &subject;
  T object;
public:
  CGreaterTrigger(T& s, T o, Functor *h, bool fo=true)
    : ITrigger(h,fo), subject(s)
  {
    object=o;
  }

  bool Test(){return (subject>object);}

  AUTO_SIZE;
};

You get the idea. It becomes drastically easy to write trigger classes - so easy, in fact, that I provided you a macro for doing it (commented out, in triggers.h). TRIGGER_CLASS(classname, test) will define a trigger class - there are a couple of examples there for you. Of course, for those of you who consider macros to be the devil, I invite you to exorcise it from the file, liberally redecorate with holy water, and write the classes out in full. Your choice. There are also a bunch of 'key' triggers, designed to work with the input system, which call functors when keys are pressed/released (making key binding incredibly simple).

The Buildstamp

This isn't so much part of the engine as it is a simple project trick that could be more suited to a Sweet Snippet or something like it, but I'm going to put it in anyway because (a) Enginuity uses it, and (b) it's nifty.

When you're working with a project over a fairly long period of time, having gone through several builds, with various betas and test releases having been distributed amongst team members and the odd friend looking to test their particular hardware configuration.. it can be difficult to keep track of them all, to find out which 'version' of an in-development project you're dealing with. It becomes particularly important when it comes to networked games - you need to ensure that all your clients have the same build of the game, otherwise messages could get interpreted differently across platforms, protocols could mismatch.. you'd generally get what appear to be a load of bugs which are actually just due to not having updated the build properly.

So, the most obvious way to do this is to track the date and time of the build. You *could* just request that everyone right-click their executables and check that the creation date is the same across all machines, but that's hardly efficient - quite aside from the fact that you're relying on the local file having the same creation date as the build, and with things like version-control systems knocking around there's no guaranteeing that'll be the case. No, the best option is to compile the date and time into the executable itself; you get the added advantage, there, of being able to access it in code. So, when your networked games connect to each other, they can compare 'buildstamps' - if they're not the same, the connection is not made; the two times could even be tested to see which is older, and the developer in question given a message telling them to update their build.

A global variable does the trick.

const std::string buildStamp = "ProjectName " __TIMESTAMP__;

__TIMESTAMP__ is, according to MSDN, a universally defined ANSI C macro, so it should be safe to use. If you can't get it to work, you may need to resort to the more advanced method I describe in a minute. I've got my projects set up with that line in a file all on its own - 'buildstamp.cpp.' An 'extern const std::string buildStamp' in engine.h makes the buildstamp value available throughout the engine.

The only problem we've not mentioned is, ironically, with the efficiency of the compiler. Buildstamp.cpp will get built once, but then with no changes it won't get built again - irritatingly, the compiler doesn't pick up that because the value of __TIMESTAMP__ has changed, the resulting object code would be different, but oh well. Add a custom build step in MSVC, or a custom makefile rule, to delete the buildstamp.obj file after the executable is built. That will force the compiler to regenerate the buildstamp.cpp file whenever you want to link and produce a new executable.

For the more elite amongst you, you may want to use a more advanced technique - it's not something I really thought I needed, but it gives you increased flexibility and could potentially be useful in a situation where multiple developers are working on a project. Basically, rather than writing the buildstamp.cpp file yourself, you write a short program to generate it - with the obvious advantage that such a program would have access to any information you care to give it access to, including the name of the user currently logged onto the computer ('built by "fine.richard" at...'), or even a file to keep track of the number of times the generator program has been run (a build number). As before, you hook this program in as a custom build step, and voila - each build will have a freshly-generated buildstamp.cpp file, containing any information you want. I'd recommend that you write such a program to use a config file specific to the project - you can store the project name and current build number in there, while reusing the generator program across projects.

Conclusion

We've covered a chunk more today; hopefully that'll keep you all going for a bit while I finish up with article 6. :-) The interpolator and triggers come in particularly handy for polished GUI sequences I've found - menus sliding smoothly in and out - and the buildstamp, while not essential just yet, will come in very handy when we write the networking system.

Incidentally, I just ported the demo game - 'CY' - across to Mac OS X. The total time taken was about 4.5 hours, and most of that was spent accounting for differences between the compilers (like the fact that GCC has better adherence to standards than MSVC6, and thus didn't let me get away with much of my sloppy coding). There were only about 3 actual bugs that were exposed by the port, and one of them was simply that I'd not implemented user-level logging on Mac at that time (I have now, thanks to John McDowall - major kudos, man). Four and a half hours. Not bad, hmm? :-) The OSX port is an entrant into the uDevGame competition over at www.idevgames.com - Mac owners, go and help them out by playing the games and voting for your favourites! Judging by some of the entries last year - like the spectacular 'Kiki the Nanobot' - you won't be disappointed with the originality and sheer style of some of the entries.

I'm off for lunch. If you've got questions or comments, the discussion thread is a good place to start, otherwise I can be reached at rfine AT tbrf no-spam-monkeys DOT net. Next time, I think we'll be looking at the texturing system, but until then: have fun!