Let’s face it, when we write some code it must at some point go wrong – we can’t write perfect code first time, every time…  For this reason it is necessary to have some way of notifying users that something bad has happened and some way of recording what has gone wrong.

This short article series will talk about logs and exceptions in C++.  Part i focuses on logging errors to a txt file, while part ii will focus on exception handling.  Both of these systems that are presented are used in my project and the code provided at the end of the article has been compiled and can be used as is.

How it works

Possibly the most useful feature when debugging our applications is the faithful log file.  We all have our own ways of doing this and here I will share with you my way of doing it.  I really like C++ IO streams and have used the insertion operator (<<) for logging to a file.  I will break down the interface into the first draft and then add the features in gradually till you have the full thing.  The basic interface looks like this:

class CLog
{
public:
    CLog(void);

    ~CLog(void);

    template <typename T>
    std::ostream& operator << (const T& value);

    std::ostream& operator << (std::ostream& (*fn)(std::ostream& os));

    void Flush();

private:
    std::stringstream  buffer;
    std::ofstream      output;
};

This interface allows us to write code like the following:

CLog Log;
Log << "Add an error code to the log: " << errorCode;

thanks to the insertion operators passing back a reference to an ostream.  This is exactly how std::cout works   The above example uses the first operator overload which is a template to allow typesafe insertion, unlike with printf!  The second one may confuse you, but it is necessary as it lets us use the stream manipulators like std::endl and std::flush.  They are passed to the stream as a function pointer.  One final note about the contents of our current interface is the two streams we have as members.  The first is a stringstream and the second is an ofstream.  Why do we have a stringstream when we only need a filestream?  Simple, I wanted to remove some of the overhead of writing to a file continuously by piling all the info into a buffer first and then manually flushing the log into the file.  There is a still a fair bit of overhead associated with this method, but that is the downside to streams really…

Improvements

This is a really good start and it works like we want it to.  It’s identical to using a regular C++ stream.  However, the user of the log has to specify when to flush and when to add new lines.  Since I’m lazy and want a log to be formatted automagically for me, I was stuck.  I can’t append a new line at the end of a call to the insertion operator since that would wreck the chaining we worked so hard for.  The solution I’ve used is a fairly common one; it is a helper class.  The helper class will now be used to chain the insertion operators and format our buffer for us.  We take advantage of object lifetime and add the end of line formatting in the helper class’ destructor to complete the functionality of it.  Our class now looks like:

class CLog
{
private:
    class CLogHelper;

    friend class CLogHelper;

public:
    CLog(void);

    ~CLog(void);

    template <typename T>
    CLogHelper operator << (const T& value);

    CLogHelper& operator << (std::ostream& (*fn)(std::ostream& os));

    void Flush();

private:
    std::stringstream  buffer;
    std::ofstream      output;

private:
    class CLogHelper
    {
    public:
        CLogHelper(CLog * Out);
        ~CLogHelper();

        template <typename T>
        CLogHelper& operator << (const T& value);

        CLogHelper& operator << (std::ostream& (*fn)(std::ostream& os));

    private:
        CLog * Log;
    };
};

The major changes then:

• We have added a private helper class.  This class is brilliant in its simplicity:
  • When the user now puts text into log the Logs insertion operator makes a call to the helper class’ constructor when it returns to create a scoped helper object
  • The helper class calls its insertion operator to add any extra info into the buffer if needed
  • At the end of the last call to the insertion operator we climb back up the stack to clean up after ourselves and this consequently adds a single new line to the buffer and calls our flush function which outputs to the file
• We have created a prototype of the helper class and made it a friend so that it can access our private buffer
• Finally, we have changed the return type of the insertion operators to return instances of the helper class to allow for chaining

Seems like a long-winded way to get what I wanted, but it works and is in fact quite simple and transparent.  The end user will never care about the helper class as there is no need to make any special calls.  Just create and use.  Simple.  But I’m not done yet!

Taking it one step further

What we have at this point is a very nice logging system that, on the face of it, acts like a regular stream and is just as easy to use, with the added bonus that we don’t need to worry about adding new lines   So what more can we do I hear you ask?  Simple, we’re going to add some extra formatting to the start of our messages.  Surfing through a log can be very tedious work.  It can often be like looking for a needle in a haystack…  So wouldn’t it be nice have some tags for the output?  Something like [ERROR] for errors or [RECOVERED] for recovering from a [FATAL ERROR] for example.  We can also make it so that the log will automagically add a default tag if none is specified (I know, I’m lazy…).  This requires a little more work and of course some additions to the log class.  I’ll just post the important parts for this since the rest of the class remains unchanged.  What I intend is to have is something like the following:

Log << "Logging started on " << GetDate() << " at " << GetTime();
Log(CLog::ERROR) << "Something bad happened  ";

Which would provide the following output in the log:

[INFO ] Logging started on 05/05/11 at 16:38:59
[ERROR] Something bad happened  

Very handy don’t you think?  We can achieve this very simply with a lovely enum and a couple of functions:

// CLog class enum LogLevel
{
    FATAL_ERROR = 0,
    ERROR,
    RECOVERED,
    INFO,
    DEBUG,
    WARNING
};

CLogHelper operator ()(const LogLevel level);
void ChangeDefaultLevel(const LogLevel & newLevel);

// CLogHelper class
CLogHelper(CLog * Out, const LogLevel lev);

The enum is fairly self explanatory, they are simply our tag IDs.  The parenthesis operator takes an entry from this enum as a parameter and makes a call to the extra helper class constructor.  This constructor uses the enum parameter in a switch to insert the required tag into the buffer before returning.  The other constructor for this class is unchanged.

As for inserting the default tag, when the log is created we make the assumption that the default tag is [INFO].  This tag gets added in during the call to the FIRST insertion operator only.  We ensure that this is the case be using a flag that is true when can insert the flag and false otherwise.  We take care to set this flag in the new helper class constructor so that we don’t accidentally insert two tags.  This should never happen anyway, but lets be safe about it

Conclusion

These final changes, then, allow us to create an easy to read log, as well as an easy to use interface.  I have created a small sample program that uses the log which I will close this post with.  It shows how to use the various pieces of the interface to create very helpful debug info:

CLog Log;
Log << "Logging enabled for: " << programName << std::endl;

try
{
    Log << "Log can be used like a normal IO stream  ";
    Log << "The insertion operator (<<) can be chained " <<  "like a normal iostream.";
    Log << "There is no need for a std::endl.";
    Log << "Although you can use one to add a blank line between outputs" << std::endl;
    Log << "See what I mean?" << std::endl;
    Log(CLog::DEBUG) << "Using the parenthesis () operator with a log level allows you to customise the output a bit";

    // We can change the default tag with one function call
    Log.ChangeDefaultLevel(CLog::RECOVERED);
    Log << "Now the default tag has been changed!";

    bool throwup = true;
    if(throwup)
    {
        Log(CLog::WARNING) << "I'm warning you!";
        throw std::string("I did warn you...");
    }
}
catch(std::string& e)
{
    Log(CLog::FATAL_ERROR) << e;
}

The above creates the following output:

[INFO]        Log opened...
[INFO]        Logging enabled for: Logger.exe

[INFO]        Log can be used like a normal IO stream 
[INFO]        The insertion operator (<<) can be chained like a normal iostream.
[INFO]        There is no need for a std::endl.
[INFO]        Although you can use one to add a blank line between outputs

[INFO]        See what I mean?

[DEBUG]       Using the parenthesis () operator with a log level allows you to customise the output a bit
[RECOVERED]   Now the default tag has been changed!
[WARNING]     I'm warning you!
[FATAL ERROR] I did warn you...

I hope that you find this logger to be quite helpful.  A read through the code will help you to understand it a lot better.  You can find the source code here.  The next article will talk about exception handling in C++ and how it can save your life!

This engine is my own personal project that I have undertaken in order to further my understanding of critical game components.  So far the engine features a sound device that is capable of streaming ogg files and playing wavs.  The renderer is under construction (will support OpenGL2.1, OpenGL3.x and DirectX9.0c)

Feel free to look at the source here or alternatively, download the project here (note that you require OpenAL, OggVorbis libraries (I link statically) and the boost headers installed to compile)

Just a short post to get this out there.  If you want to add something to the engine then leave me a message and we’ll chat!

Dave

I will go through my factory style functions first.  It is a simple inline template function that is also overloaded to handle polymorphism:

template<class Object> inline boost::shared_ptr<Object> CreateNew()
{
     return boost::shared_ptr<Object>(new Object);
}

template<class Base, class Derived> inline boost::shared_ptr<Base> CreateNew()
{
      return boost::shared_ptr<Base>(new Derived);
}

The use of these functions is relatively intuitive, especially the first one, however I will demonstrate the function in action with a small example below:

FILE : shape.h #ifndef _SHAPE_H_
#define _SHAPE_H_

class CShape
{
public:
     CShape() {}
     virtual ~CShape() {}

     virtual float Area() = 0;

private:
     float l, b;
};

class CSquare
 : public CShape
{
public:
     CSquare() : CShape() {}
     virtual ~CSquare() {}

     virtual float Area () { return l*b; }
};

typedef boost::shared_ptr<CShape> CShapePtr;

#endif // _SHAPE_H_

FILE : main.cpp int main(void)
{
     ...
     CShapePtr Square = CreateNew<CShape, CSquare>();
     float area = Square->Area();
     ...
}

Notice that I have typedef’d away the boost syntax to CShapePtr.  This makes what we are creating more obvious to someone not familiar with boost, namely, a pointer to a CShape object of type CSquare.  The limitation with these functions is that only the default constructor can be invoked.  These functions can be inherited from a template factory class containing these functions as static members with multiple overloads, but I find that the way these functions are works just fine for me – only ever program what you need, not what you want or think you might need .

Now lets move on to the destruction functions.  They are very simple to use as well and they should be fairly intuitive to use as well:

template< typename T >
inline void Destroy(T t)
{
     if(t)
     {
          delete t;
          t = 0;
     }
}

template< typename T > inline void DestroyArray(T t)
{
     if(t)
     {
          delete[] t;
          t = 0;
     }
}

template< typename T > inline void Release(T t)
{
     if(t)
     {
          t->Release();
          t = 0;
     }
}

Like I said, simple.  Note that you could also write these as macros, but I would advise against that since macros are almost impossible to debug.  Besides, I am using C++ not C!  As you can see, there are no typedefs required for these functions.  To delete something, just call the appropriate functions, passing the datatype into the <>’s and the object in the ()’s like so:

Destroy<int*>(ptr);
DestroyArray<char*>(array);
Release<IUnkown*>(COMptr);

I know that there will be some OO junkies out there that may not like my classless approach to these functions, but to them I say that C++ is a multi-paradigm language that actually encourages you to mix paradigms now and again to make programming a lot easier.  Feel free to use this code in your projects everyone!  If you come up with better solutions then let me know about them just e-mail me: d.brown@bigdavedev.com

I created this project yesterday as an exercise in fast and effective programming.   I decided to go with a topic I knew really well that offered a great challenge, namely, post-processing.  I gave myself 12 hours to complete the project and I am very satisfied with the results.  I used only three  resources for coding this application:

1. OpenGL Registry
2. Nehe Lesson1 basecode
3. An article on GameDev.net about abstraction

What I’m left with is an application that has a strong, reusable, robust and readable object hierarchy incorporating shaders, framebuffer obects, renderbuffer objects and renderable textures.

The Application

On start up, the application reads from a configuration file.  This file only contains the relative address to the post-processing shader that is to be used.  Currently, the choices are:

1. Combined.frag – An unmodified rendering of the rendertarget’s contents,
2. BlackAndWhite.frag – A black and white filter for the rendertarget contents,
3. Invert.frag – Inverts the colours in the rendertarget.

The application then proceeds to acquire all the resources, such as shaders, framebuffers, textures, renderable objects, etc before the rendering takes place.  In the rendering function forward rendering takes place followed by processing the rendered scene in a second pass.  Below are some screenshots of the application:

Part of the challenge I set myself was effective programming.  I take effective to mean code that does the job it is meant to, is readable and reusable.  A goal that I feel I accomplished with great success.  After reading through this article I decided to follow the structure presented, which left me with a very plug-able system.  As an example, the framebuffer class makes good use of the hierarchy.  When we break it down into base components we see that it is an OpenGL object and uses the normal Gen, Bind and Destroy functions.  It is also part of a group of buffer objects that are now very useful in the OpenGL API – and mandatory in the core profile for version 3.x/4.x – so we can create a base class to handle all of those object types.  The resulting code looks like:

template<class CObjectType>
class CGLObject
{
public:
     CGLObject() : ID(CObjectType::GenerateID())
     {}

     virtual ~CGLObject()
     {
          CObjectType::Destroy(ID);
     }

     void Bind() const      {
          CObjectType::Bind(ID);
     }

     void UnBind() const      {
          CObjectType::UnBind();
     }

     unsigned int GetID() const      {
          return ID;
     }

protected:
     unsigned int ID;
};

which gives us a base class for handling any OpenGL object we may choose to create.  Note that this is also a RAII based class.  The programmer inheriting from this class need not worry about creating or destroying the OpenGL object as that is handled in the constructor and destructor respectively.  The next class is the base class for buffer object types like framebuffers, renderbuffers or vertexbuffers:

template< GLenum bufferType >
class CBufferObject
{
public:
     static GLuint GenerateID()
     {
         GLuint ID;
         switch(bufferType)
         {
         case GL_FRAMEBUFFER:
             glGenFramebuffers(1, &ID);
             break;
         case GL_RENDERBUFFER:
             glGenRenderbuffers(1, &ID);
             break;
         case GL_ARRAY_BUFFER:
             glGenBuffers(1, &ID);
             break;
         };
         return ID;
     }

     static void Bind(GLuint ID)
     {
         switch(bufferType)
         {
         case GL_FRAMEBUFFER:
             glBindFramebuffer(GL_FRAMEBUFFER, ID);
             break;
         case GL_RENDERBUFFER:
             glBindRenderbuffer(GL_RENDERBUFFER, ID);
             break;
         case GL_ARRAY_BUFFER:
             glBindBuffer(GL_ARRAY_BUFFER, ID);
             break;
         };
     }

     static void UnBind()
     {
         switch(bufferType)
         {
         case GL_FRAMEBUFFER:
             glBindFramebuffer(GL_FRAMEBUFFER, 0);
             break;
         case GL_RENDERBUFFER:
             glBindRenderbuffer(GL_RENDERBUFFER, 0);
             break;
         case GL_ARRAY_BUFFER:
             glBindBuffer(GL_ARRAY_BUFFER, 0);
             break;
         };
     }

     static void Destroy(GLuint ID)
     {
         switch(bufferType)
         {
         case GL_FRAMEBUFFER:
             glDeleteFramebuffers(1, &ID);
             break;
         case GL_RENDERBUFFER:
             glDeleteRenderbuffers(1, &ID);
             break;
         case GL_ARRAY_BUFFER:
             glDeleteBuffers(1, &ID);
             break;
         };
     }
};

Although a rather polluted looking template, it does allow us to have one base class to plug-in to the CGLObject class I posted first.  It also means that a programmer creating their own buffer class can plug this template into the CGLObject class and not have to worry about coding all the required template functions.  It’s all about re-usability in this hierarchy afterall.  Finally, we can now create the CFramebuffer class.  I will only post the class declaration as the rest of the code is not related to this topic – full source code can be downloaded at the bottom of this post though .  The declaration is as follows:

class CFramebuffer
 : public CGLObject< CBufferObject< GL_FRAMEBUFFER > >
{
    ...
};

If you read the article I linked to it should be fairly obvious by now what this does.  The CFramebuffer class inherits CGLObject for it’s OpenGL handle functionality.  We plug in CBufferObject to CGLObject as we are creating a buffer type object and, specifically, we are creating a GL_FRAMEBUFFER type of buffer object, so this gets plugged into CBufferObject and our inheritance is complete.  When we create an instance of CFramebuffer, the CGLObject constructor gets automatically called, which creates a handle to our framebuffer object.  We add any other buffers or textures to the framebuffer with similar classes and when it comes time to use the framebuffer the bind function inherited from CGLObject gets called and similarly, when it’s time to stop using it, we call UnBind(), which simply binds the window framebuffer for us.  At the end of the objects lifetime the OpenGL handle to the object gets destroyed in CGLObject’s destructor and we are clear of any resource leaking!

Limitations

There are, however, some limitations to this code.  The biggest limitation is that, although I have coded an AddTexture function for the CFramebuffer class that allows you to add any number of textures, the number of draw buffers is hardcoded to 3.   I did not think of a way to get round this problem, although perhaps some sort of dynamic array would be the answer, I just didn’t have the time to look into it – zero hour was just 3 hours away at that time and I still had shaders to write…

For all the talk I give about the importance of RAII, I completely forgot to use my favourite boost library to wrap pointers – the ever wonderful shared_ptr<> class .  This means that I have done all the memory management manually for this project.  Not such a big deal this time round for a relatively small project, however the lack of these boost::shared_ptr’s disturbs me if it were to be a bigger project with many shaders and sceneobjects floating around – after all, humans forget…

That said, these small things are the only limitations in software, which I am proud of.  The hardware limitations are a little less forgiving though, as the application relies on the availability of shaders and framebuffers.  However, according to Valve’s hardware review, most people have GPUs that are more than capable of running this application, so my hardware concern lies with a small percentage of people who don’t have a powerful enough GPU, or who run something that is not NVIDIA based…

Downloads

source code

executable

On a side note, my PS3 has suddenly started working again, of its own accord… This is very strange, but very delightful! All in all, it’s going to be a great week ahead in getting stuff done!