Each of these poor men is being totally honest in their description, but the end result ends up being divorced from reality by the limits of their own perception. The moral of the story is for one to be aware of where their limited perception (or preconceptions) may hide information from them. In more colloquial terms, it’s about learning to see the whole picture.

This lesson also applies to programming, particularly when designing code. For almost any programming problem, there are several, potentially competing, factors that play into its solutions. It’s easy to get so locked into a single mindset that you overlook important factors that you would only have noticed from a different vantage point.

When I need to design a piece of code, I try to think about it from at least the following three perspectives. Of course, these thee perspectives don’t represent the full set of potential viewpoints from which to examine a problem. These are just the three that I’ve found to be the most useful tools for my day-to-day programming work.

Class View
At this stage, I think about how I would structure my code with traditional Object-Oriented Programming techniques. I think about the data and functions that would be a part of the core “objects” in the feature I am creating. If things get hairy, I bust out some UML to track dependencies and ownership relations. This views tends to make the code most easily digestible for many game programmers because most of them have been raised on OOP principles.

Data View
This is where I look at the problem I need to solve in terms of data that needs to be processed. As opposed to thinking in terms of classes which are collections of data and functions that operate on that data, I think about data processing as a pipeline. In many cases, this sort of thought process leads me to the core update loops that will form the core of the feature I’m implementing. This view is often about making the code easily usable for the target machine. In many cases it’s about taking data that has been gathered and normalized so it can be processed in a minimally-complex fashion.

User View
I wouldn’t be a very useful programmer if I ignored my end-users. If my feature needs someone to author data for it (and almost every feature does in some way or another), I’d better make sure they can create that data in a reliable and reasonably error-proof fashion. This is especially true if they have to produce a lot of data or need to iterate on that data repeatedly.

I don’t always use the above three views in that order, but I generally make sure to ask myself if I’ve considered my design from all three of these perspectives before I start working on any significantly large feature. Sometimes the best thing I can do when programming is to stop and ask myself: “Have I seen the whole elephant?”

#OneGameAMonth

One Game a Month. That’s twelve games in a year. Considering that I struggled to launch two games last year (Michelangelo and Robot Legions, $1 a piece if you’re interested), this seems like a pretty tall order. And you know what, it is. But, I’m going to try and see how far I get.

One Game A Month is a motivational promotion being run by @McFunkypants. As the name suggests, the goal is to make a game every month. There are over 2000 developers signed-up who are ready to encourage each other to make games. As a nice touch, the One Game A Month site has implemented a suite of typical gamification features: experience points for making games, leveling-up profiles, and achievements.

On one hand, it’s silly. On the other, it’s also hugely motivating. If you’re a game dev looking for a challenge, this may be the one for you. If you need some more convincing, how about listening to @McFunkypant’s One Game A Month keynote speech:

Yuck.

So, in the interest of helping other XNA devs out there, let me tell you about what I screwed up and how I fixed it.

So, let’s get to the meat. Let me show you how I screwed up my save data handling.

First, this is how I read my save data:

// Deserialization
XmlSerializer s = new XmlSerializer(typeof(T));
if (container.FileExists(filename))
{
    TextReader r = new StreamReader(container.OpenFile(filename, FileMode.Open));
    saveDataItem = (T)s.Deserialize(r);
    r.Close();
}
container.Dispose();

And this is how I wrote it:

// Serialization
XmlSerializer s = new XmlSerializer(saveDataItem.GetType());
TextWriter w = new StreamWriter(container.OpenFile(filename, FileMode.OpenOrCreate));
s.Serialize(w, saveDataItem);
w.Close();

See the bug? Yeah, well, neither did I. You see, there was this little problem with how I wrote my save data. The code above would work in most cases, but if I wrote data that was shorter than the previous file’s save data, the old save data would only be partially overwritten. Any bytes of the old save data not explicitly overwritten by the new save data would remain appended to the end of the new save data. Thus potentially turning data like this:

<RobotSaveData><Cash>12345</Cash></RobotSaveData>

Into data like this:

<RobotSaveData><Cash>123</Cash></RobotSaveData>a>

And totally confounding the XML deserializer. Voila! Broken save data and unhappy customers. To top it off, as far as I can tell, this behavior doesn’t replicate on Windows, only on the Xbox 360. You can imagine my consternation.

Enough about what went wrong. Here’s how I went about fixing it. I changed the way I opened a file for writing my save data:

// Serialization
XmlSerializer s = new XmlSerializer(saveDataItem.GetType());
TextWriter w = new StreamWriter(
    container.FileExists(filename) ?
    container.OpenFile(filename, FileMode.Truncate) :
    container.OpenFile(filename, FileMode.Create)
);
s.Serialize(w, saveDataItem);
w.Close();

This big difference here is that I use FileMode.Truncate when opening the file for writing save data. By doing this, I’m able to dispose of the old contents and completely overwrite them with my new save data.

EDIT: I was recently informed by one of the fine members of the XBLIG community that simply using FileMode.Create when I open a file is sufficient for my purposes since it’s behavior when a file exists is the same as FileMode.Truncate.

If you’ve attended elementary school in the States, you should be familiar with 5WH, the building blocks of questions: Who, What, When, Where, Why and How. These six words cover the gamut of questions you can ask and provide structure to information sharing. So, what happens when you apply these questions to comments in source code and use them to direct the information you need to share?

Who?
Who wrote this code? Or, more importantly, who is responsible for this code when it breaks something? Explicitly identifying the owner of particular bits of code is useful because subsequent readers of the code then know who to ask if they have questions. This goes beyond just code ownership. I actually write my name next to any code comments I make so people can ask me to clarify in case my comment didn’t make sense to them.

That being said, this question can also be easily answered by having decent source control. If I find comments disagreeing with what I see from source control histories, I trust what the source control says.

What?
Commenting about what source code does is absolutely useless. People who hate comments in code usually hate them because they are answering this question. Writing what code does is simply re-stating information presented by the source code itself only with less precision and a greater change of being incorrect. This is also the kind of commenting you’ll get if you instate a commenting policy without addressing what questions the comments are actually supposed to answer.

Do we really need more “documentation” like this:

	//Sets the position of this object
	void SetPosition(Vector2 position);

It’s silly. Don’t do it.

When?
Putting a time-stamp on comments is almost as useful as putting your name on comments. This is another bit of information that replicates information provided by source control but it can help someone reading your code if they can decide, at a glance, whether a given comment is old and out-of-date.

Where?
Where is the code? The code is where the code is. A more useful question to answer is: where should this code be used? If the answer is not obvious, it’s probably worth mentioning. Another useful bit of information is telling the reader where your code came from. If you pulled the code from the net, include a link in the comments to the original material. If you copy-pasted (shame on you) the code from someplace, mention the source in the comments.

Why?
This is the BIG ONE! How often have you found yourself reading someone else’s (or your own) code and thinking: “Why did they do that?” If you answer only one question with your comments, answer this one. While “what” is fully captured by the code itself and “when/who” are captured by source control, “why” is pretty much invisible unless explicitly explained. If you think something is a hack, elaborate on why that is. If there’s some code that you think might be dangerous, explain why. If you chose a particular implementation when another might have worked, talk about why you made that choice. The person reading your code will thank you.

How?
If your code needs some explanation in order to be used correctly or if there is some particular order in which certain functions need to be called in order to behave as expected, it’s a good idea to document that in your comments. This is another question, like “Why”, that is not easily answered by source-control or the source code itself.

Programmers tend to be busy and comments are not crucial in the strictest sense of the word, but they CAN be invaluable tools to people reading code. Comments aren’t intrinsically valuable, however. Their value is only realized when they answer a question held by someone reading the code. Good code comments must serve the needs of the code reader, be that another programmer or your future self.

The core functionality of my text pre-rendering solution is drawing a given string to a texture using a given font. I’m then able to use that text texture anywhere in my game as I would any normal texture. This allows me to avoid the overhead of calling DrawString() for text in my game that doesn’t have to change often.

SpriteFont demoFont = Game.Content.Load<SpriteFont>("TextRenderingDemo/DemoFont");
Texture2D textTexture = textWriter.CreateTextSpriteTexture(demoFont, "The quick, brown fox jumped over Richter Belmont");

In addition to the core functionality, I added the following features:

Button Guides
The XBLIG Creator’s site provides images of the Xbox Controller’s buttons compatible with XNA’s SpriteFont for providing on-screen control instructions. While it’s possible to combine the button images with another sprite font image and use them as one SpriteFont, I prefer to combine the button images with fonts I choose at runtime. To do this, I prepared a version of my string rendering function with extra parameters for rendering the button image and positioning it relative to the text of my choice.

SpriteFont demoFont = Game.Content.Load<SpriteFont>("TextRenderingDemo/DemoFont");
SpriteFont buttonFont = Game.Content.Load<SpriteFont>("Fonts/xboxControllerSpriteFont");
Texture2D textTexture = textWriter.CreateButtonGuideTextSpriteTexture(demoFont, buttonFont, ": Do Something", "'", 0.5f, new Vector2(0.0f, 0.0f));

Drop Shadows
In a lot of cases, just rendering SpriteFonts as is tends to feel a little flat. Drawing a darkened version of the same text offset by a couple pixels before drawing the text in question goes a long way to helping it stand out. It’s a trick I use so often that I decided to bake drop shadows into my text pre-renderer. With this functionality, a call like this:

SpriteFont demoFont = Game.Content.Load<SpriteFont>("TextRenderingDemo/DemoFont");
List<TextWriterDropShadow> dropShadows = new List<TextWriterDropShadow>();
dropShadows.Add(new TextWriterDropShadow(new Vector2(2.0f, 2.0f), Color.Black));

Texture2D textTexture = textWriter.CreateTextSpriteTexture(demoFont, "The quick, brown fox jumped over Richter Belmont", Color.White, dropShadows);

Can give me text that looks like this:

Text Borders
You’ll notice that I pass lists of drop shadows to my sprite pre-renderer. It may seem like overkill, but being able to define a multiple drop shadows allows me to create various effects when rendering text. For example, I can define a list of drop-shadows like this:

SpriteFont demoFont = Game.Content.Load<SpriteFont>("TextRenderingDemo/DemoFont");
List<TextWriterDropShadow> dropShadows = new List<TextWriterDropShadow>();
dropShadows.Add(new TextWriterDropShadow(new Vector2(-1.0f, -1.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(1.0f, -1.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(-1.0f, 1.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(1.0f, 1.0f), Color.Black));

dropShadows.Add(new TextWriterDropShadow(new Vector2(0.0f, -2.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(0.0f, 2.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(-2.0f, 0.0f), Color.Black));
dropShadows.Add(new TextWriterDropShadow(new Vector2(2.0f, 0.0f), Color.Black));

Texture2D textTexture = textWriter.CreateTextSpriteTexture(demoFont, "The quick, brown fox jumped over Richter Belmont", Color.White, dropShadows);

To give me fancy bordered text like this:

How’s that for pop?

Playing with the number of drop shadows, their offsets, and colors can allow you to produce a variety of decorations for your game’s text. Give it a try if you’re interested. You can find the code for my text pre-renderer below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;

namespace EstrellaLib.Sprite
{
    public class TextWriterDropShadow
    {
        public Vector2 Offset;
        public Color Color;

        public TextWriterDropShadow(Vector2 offset, Color color)
        {
            Offset = offset;
            Color = color;
        }
    }

    public class TextTextureWriter
    {
        GraphicsDevice _graphics;
        SpriteBatch _spriteBatch;

        public TextTextureWriter(GraphicsDevice graphics)
        {
            _graphics = graphics;
            _spriteBatch = new SpriteBatch(graphics);            
        }

        public Texture2D CreateTextSpriteTexture(SpriteFont spriteFont, string textString)
        {
            return CreateTextSpriteTexture(spriteFont, textString, Color.White, null);
        }

        public Texture2D CreateTextSpriteTexture(SpriteFont spriteFont, string textString, Color textColor, List<TextWriterDropShadow> dropShadows)
        {
            return RenderTextTexture(spriteFont, textString, textColor, null, "", 1.0f, Vector2.Zero, dropShadows);
        }

        public Texture2D CreateButtonGuideTextSpriteTexture(SpriteFont textSpriteFont, SpriteFont buttonGuideSpriteFont, string textString, string buttonGuideText, float buttonGuideScale, Vector2 buttonGuidePositionOffset)
        {
            return CreateButtonGuideTextSpriteTexture(textSpriteFont, buttonGuideSpriteFont, textString, buttonGuideText, buttonGuideScale, buttonGuidePositionOffset, Color.White, null);
        }

        public Texture2D CreateButtonGuideTextSpriteTexture(SpriteFont textSpriteFont, SpriteFont buttonGuideSpriteFont, string textString, string buttonGuideText, float buttonGuideScale, Vector2 buttonGuidePositionOffset, Color textColor, List<TextWriterDropShadow> dropShadows)
        {
            return RenderTextTexture(textSpriteFont, textString, textColor, buttonGuideSpriteFont, buttonGuideText, buttonGuideScale, buttonGuidePositionOffset, dropShadows);
        }

        private Texture2D RenderTextTexture(SpriteFont textSpriteFont, string textString, Color textColor, SpriteFont buttonGuideSpriteFont, string buttonGuideText, float buttonGuideScale, Vector2 buttonGuidePositionOffset, List<TextWriterDropShadow> dropShadows)
        {
            if (textSpriteFont != null)
            {
                Vector2 stringDimensions = textSpriteFont.MeasureString(textString);

                float buttonHorizontalShift = 0.0f;
                Vector2 buttonTextDimensions = Vector2.Zero;
                if (buttonGuideSpriteFont != null)
                {
                    buttonTextDimensions = buttonGuideSpriteFont.MeasureString(buttonGuideText);
                    buttonTextDimensions.X *= buttonGuideScale;

                    buttonTextDimensions.X += Math.Abs(buttonGuidePositionOffset.X);
                    if (buttonGuidePositionOffset.X < 0.0f)
                    {
                        buttonHorizontalShift = -buttonGuidePositionOffset.X;
                    }

                    //Eliminate potential non-integral values that could result in lost pixels on texture render
                    buttonTextDimensions.X = (float)Math.Ceiling(buttonTextDimensions.X);
                }

                Vector2 dropShadowPositionAdjust = Vector2.Zero;
                Vector2 dropShadowSizeAdjust = Vector2.Zero;
                if (dropShadows != null)
                {
                    Vector2 lowestVals = Vector2.Zero;
                    Vector2 hightestVals = Vector2.Zero;
                    foreach (TextWriterDropShadow dropShadow in dropShadows)
                    {
                        if( dropShadow.Offset.X < 0.0f )
                            lowestVals.X = Math.Min(lowestVals.X, dropShadow.Offset.X);

                        if (dropShadow.Offset.Y < 0.0f)
                            lowestVals.Y = Math.Min(lowestVals.Y, dropShadow.Offset.Y);

                        if (dropShadow.Offset.X > 0.0f)
                            hightestVals.X = Math.Max(hightestVals.X, dropShadow.Offset.X);

                        if (dropShadow.Offset.Y > 0.0f)
                            hightestVals.Y = Math.Max(hightestVals.Y, dropShadow.Offset.Y);
                    }

                    dropShadowPositionAdjust.X = Math.Abs(lowestVals.X);
                    dropShadowPositionAdjust.Y = Math.Abs(lowestVals.Y);

                    dropShadowSizeAdjust.X = Math.Abs(lowestVals.X) + Math.Abs(hightestVals.X);
                    dropShadowSizeAdjust.Y = Math.Abs(lowestVals.Y) + Math.Abs(hightestVals.Y);
                }

                RenderTarget2D renderTarget = new RenderTarget2D(_graphics, (int)stringDimensions.X + (int)buttonTextDimensions.X + (int)dropShadowSizeAdjust.X, (int)stringDimensions.Y + (int)dropShadowSizeAdjust.Y);

                _graphics.SetRenderTarget(renderTarget);
                _graphics.Clear(Color.Transparent);
                _spriteBatch.Begin(SpriteSortMode.Immediate, BlendState.AlphaBlend, SamplerState.PointClamp, null, null);
                
                if (buttonGuideSpriteFont != null)
                {
                    _spriteBatch.DrawString(buttonGuideSpriteFont, buttonGuideText, dropShadowPositionAdjust + new Vector2(buttonHorizontalShift, buttonTextDimensions.Y * -0.25f * buttonGuideScale) + buttonGuidePositionOffset, Color.White, 0.0f, Vector2.Zero, buttonGuideScale, SpriteEffects.None, 1.0f);
                }

                Vector2 textPosition = dropShadowPositionAdjust + new Vector2(buttonHorizontalShift + buttonTextDimensions.X, 0.0f);
                if (dropShadows != null)
                {
                    foreach (TextWriterDropShadow dropShadow in dropShadows)
                    {
                        _spriteBatch.DrawString(textSpriteFont, textString, textPosition + dropShadow.Offset, dropShadow.Color);
                    }
                }

                _spriteBatch.DrawString(textSpriteFont, textString, textPosition, textColor);
                
                _spriteBatch.End();
                _graphics.SetRenderTarget(null);

                return renderTarget;
            }
            return null;
        }
    }
}

/* Button Guide Mapping
Character	Image
Space       Left Thumbstick
!	        Directional Pad
"	        Right Thumbstick
#	        BACK
$	        Guide
%	        START
&	        X
'	        A
(	        Y
)	        B
*	        Right Shoulder
+	        Right Trigger
,	        Left Trigger
-	        Left Shoulder
*/

Fixing Problem #1: Structs as Dictionary Keys
So, according to the CLRProfiler, I’m creating ActorStates via Generic.ObjectEqualityComparer::Equals() during my ChooseTargetNode() function. Looking at that code, it simple looks like I’m checking against a Dictionary that uses ActorState as a key. A quick Google search turns up this tidbit on XNA Wikia. The article talks about how Enums cause memory allocations when used as keys in Dictionaries. It’s fair to assume that structs would have similar behavior and cause garbage to be created when used by the Dictionary’s internal comparison functions. Luckily, the fix for this is easy. If a struct implements IEquatable, Dictionary won’t allocate instances of that struct during comparisons. Since my ActorState struct already implemented comparison functions, I just needed to add IEquatable as a part of its declaration.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace EstrellaLib.Actor
{
    public struct ActorState : IEquatable<ActorState>
    {
        string _stateName;

        public ActorState(string stateName)
        {
            _stateName = stateName.ToUpperInvariant();
        }

        public string StateName
        {
            get
            {
                return _stateName;
            }
            set
            {
                _stateName = value.ToUpperInvariant();
            }
        }

        public override bool Equals(object obj)
        {
            if (obj is ActorState)
            {
                return this.Equals((ActorState)obj);
            }
            return false;
        }

        public bool Equals(ActorState p)
        {
            return _stateName == p._stateName;
        }

        public override int GetHashCode()
        {
            return _stateName.GetHashCode();
        }

        public static bool operator ==(ActorState lhs, ActorState rhs)
        {
            return lhs.Equals(rhs);
        }

        public static bool operator !=(ActorState lhs, ActorState rhs)
        {
            return !(lhs.Equals(rhs));
        }

        public static ActorState None = new ActorState("NONE");
    }
}

Once I did that, ActorState disappeared from my allocation list on a second CLRProfiler run.

Fixing Problem #2: Value Type Boxing with PropertyInfos
While the boxing problem caused by my code is relatively straight-forward:

        public override void ApplyToActor(Actor targetActor)
        {
            if (_targetProperty == null)
            {
                _targetProperty = targetActor.GetType().GetProperty(_targetName);
                _targetActor = targetActor;
            }
            System.Diagnostics.Debug.Assert(_targetActor == targetActor);

            //PropertyInfo.SetValue(object obj, object value, object[] index)'s second parameter
            // causes any value types I pass to it to be boxed in a temporary System.Object
            _targetProperty.SetValue(targetActor, _targetValue, null);
        }

Fixing it, is not quite as easy as simply implementing a particular interface. I need to find a way to avoid calling SetValue(). Thankfully, PropertyInfo provides a way for me to get a delegate for setting the properties value that is typed to the value I’m trying to set. This means that, if I go through the setter delegate, I can avoid implicitly casting my value type to a System.Object and creating garbage. With a bit of work, I modify my code and end up with something like this:

        public override void ApplyToActor(Actor targetActor)
        {
            if (_targetActor == null)
            {
                PropertyInfo targetProperty = targetActor.GetType().GetProperty(_targetName);
                _targetActor = targetActor;

                MethodInfo setter = targetProperty.GetSetMethod();
                System.Diagnostics.Debug.Assert(setter != null);
                _propertySetter = (Action<T>)Delegate.CreateDelegate(typeof(Action<T>), targetActor, setter);
            }
            System.Diagnostics.Debug.Assert(_targetActor == targetActor);
            System.Diagnostics.Debug.Assert(_propertySetter != null);
            _propertySetter(_targetValue);
        }

It’s not as easy to read as the version using SetValue, but it doesn’t produce any garbage. For a function that will be called multiple times a frame, it’s totally worth it.

Enjoying the Fruits of my Labor
With my code changes in place, I fire up CLRProfiler again to make sure I get the expected effect. The GC Timeline ends up looking something like this.

There we go! A few GCs occurring when the game starts up, but once we get to the Title screen: nothing. Just a flat plane of constant memory use. My garbage collection problems are solved! At least in this part of the game.

As cutesy as it may be, I’m growing rather fond of my garbage collection count display. I’m especially fond of it because it helped me find garbage collections occuring in places I never expected them to happen. Such as my title screen for example:

Ack! Look at all those garbage cans, I mean recycling bins (reduce, reuse, recycle, folks!)

That’s a lot of garbage collections for a “static” title screen. Now, how to find out what’s causing all that garbage to be created… That’s where Microsoft’s CLRProfiler comes into play.

Running CLRProfiler
CLRProfiler is a great tool for profiling your XNA game’s memory usage. It can produce graphs and tables that tell you exactly when your game is allocating what classes. It’s also a bit rough around the edges and hard to use. Even installing it eschews the oh-so-common installer for a zip file (a rarity in Windows tools nowadays.)

So, once I get my hands on the tool, the first thing I have to do is get my game running with CLRProfiler. Pressing the Start Application button seems like a good place to start, but first I need to set my working directory or else my game won’t be able to find its data while it’s being run. To do that, I click on File->Set Parameters then set the working directory to the directory where my game’s executable lives.

Next, to make sure I get all the information I need, I enable both Allocations and Calls in the Profile section. With those settings done, I’m ready to hit the Start Application button and select my game’s executable for profiling.

Diagnosing the Problem
At this point, I let my game run to the title screen so I can gather data on memory applications. After a few seconds, I shut down my game and let CLRProfiler chew on the data and present it to me.

Since I’m worried about garbage collection, I’ll take a look at the GC Timeline. Clicking the “Time Line” button gives me a graph of memory at various GC generations like this one:

See that sawtooth pattern on the bottom timeline there? Those are garbage collections. Memory builds up until it hits a threshold then garbage collection kicks in and drops the total memory usage. After that memory begins to build up again until it hits the threshold and triggers another collection and so on. Now that I know how I’m allocating memory, it’s time to find out what I’m allocating. Box-selecting one of the sawtooths, I produce a report of what is in memory at that point.

The list on the right shows me all objects instantiated during the period I box-selected. Lots of System.Objects and lots of ActorStates. The ActorState structs are definitely being produced by my code and the System.Objects are probably being produced by the way I’m using .NET. Right-clicking on the list of allocated objects, I produce a graph of which function calls allocated which objects.

All the way on the right are my System.Object and ActorState allocations. Tracking back to the left, I can follow the function calls to find out where these allocations are happening.

Aha, looks like ActorStates are being allocated when they are being compared. As for the System.Objects, it looks like my calls into the .NET’s Reflection code are responsible. Considering that RuntimePropertyInfo.SetValue() takes a System.Object as a parameter and my code is generally passing in value types, this looks like a textbook case of boxing.

Now, thanks to CLRProfiler, I know where my garbage collection problems are coming from. Next week, I’ll go into what I can do to fix them.

Okay, so enough being coy, what did I actually do? Basically, I replaced my frametime and memory displays with icons. I retain the original text-based display as an option when I need more detail, but most of the time, I can use the icon-based display to keep me aware of my basic performance profile. You can see the new frametime display in action in this screenshot from work-in-progress Robot Legions (upper-left corner):

There are 2 major elements to this new, memory-allocation-free frametime display. One is the stopwatch whose neighboring smiley face changes color and expression depending on how high the frametime is. If my frametime grows to a level where I would start dropping frames, the face icon becomes an angry red. The other element is the row of garbage cans (actually recycling bins because we’re eco-friendly around here) that show the number of recent garbage collections. It’s not a lot of information but it’s just enough to let me know when I should start using my heavier-duty profiling tools to dig into a problem.

In case you want to use this sort of display in your own project, you can grab the icon spritesheet here.

The icons are originally from the public domain Tango Icon Library. You can go there to find icons suitable for a variety of purposes.

The latest code for my frametime display code is below:

#if DEBUG
using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;
using System.Text;
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Audio;
using Microsoft.Xna.Framework.Content;
using Microsoft.Xna.Framework.GamerServices;
using Microsoft.Xna.Framework.Graphics;
using Microsoft.Xna.Framework.Input;
using Microsoft.Xna.Framework.Media;


namespace EstrellaLib.Debug
{
    /// <summary>
    /// This is a game component that implements IUpdateable.
    /// </summary>
    public class FrametimeCounterComponent : Microsoft.Xna.Framework.DrawableGameComponent
    {
        enum PerfIconType
        {
            Stopwatch,
            GarbageBin,
            HappyFace,
            NeutralFace,
            SadFace
        }

        Stopwatch FrametimeStopwatch;

        const int PERF_ICON_WIDTH = 32;
        Texture2D PerfIconSheet;
        SpriteFont FrametimeDisplayFont;
        SpriteBatch FrametimeDisplayBatch;

        bool ShowFrametimeText;

        public Vector2 FrametimeDisplayPosition;
        public Color FrametimeDisplayColor;

        const double FRAMETIME_DANGER_THRESHOLD = 1000.0f / 60.0f;      //If averaged frametime goes over this threshold...
        const float DANGER_COLOR_DISPLAY_SECONDS = 2.0f;                //... the frametime display will change color for this many seconds.
        
        float DangerTimer;
        public Color FrametimeDangerDisplayColor;
        float AveragedFrameTime;

        public bool ShowAveragedFrametime;

        WeakReference GcDetectionReference;
        long TotalMemoryKB;

        float RecentGarbageCollections;

        public FrametimeCounterComponent(Game game, bool showFrametimeText)
            : base(game)
        {
            ShowAveragedFrametime = true;
            FrametimeDisplayPosition = Vector2.One * 10.0f;
            FrametimeDisplayColor = Color.Green;
            FrametimeDangerDisplayColor = Color.Magenta;
            GcDetectionReference = new WeakReference(null);
            RecentGarbageCollections = 0;
            ShowFrametimeText = showFrametimeText;
        }

        /// <summary>
        /// Allows the game component to perform any initialization it needs to before starting
        /// to run.  This is where it can query for any required services and load content.
        /// </summary>
        public override void Initialize()
        {
            FrametimeStopwatch = new Stopwatch();
            FrametimeStopwatch.Start();
            base.Initialize();
        }

        protected override void LoadContent()
        {
            FrametimeDisplayBatch = new SpriteBatch(Game.GraphicsDevice);
            PerfIconSheet = Game.Content.Load<Texture2D>("Textures/PerfIconSheet");
            FrametimeDisplayFont = Game.Content.Load<SpriteFont>("Debug/Fonts/Default");
            base.LoadContent();
        }

        /// <summary>
        /// Allows the game component to update itself.
        /// </summary>
        /// <param name="gameTime">Provides a snapshot of timing values.</param>
        public override void Update(GameTime gameTime)
        {
            base.Update(gameTime);
        }

        public override void Draw(GameTime gameTime)
        {
            float deltaSeconds = (float)gameTime.ElapsedGameTime.TotalSeconds;
            TimeSpan frameTime = FrametimeStopwatch.Elapsed;
            FrametimeStopwatch.Reset();
            FrametimeStopwatch.Start();

            RecentGarbageCollections = MathHelper.Max(0.0f, RecentGarbageCollections - deltaSeconds * 0.1f);        //Subtract 1 RecentGC every 10 seconds
            if (!GcDetectionReference.IsAlive)
            {
                GcDetectionReference = new WeakReference(new Object());
                TotalMemoryKB = GC.GetTotalMemory(false) / 1024;
                RecentGarbageCollections+=1.0f;
            }
           

            AveragedFrameTime = AveragedFrameTime * 0.9f + (float)frameTime.TotalMilliseconds * 0.1f;
            DangerTimer = MathHelper.Clamp(DangerTimer - deltaSeconds, 0.0f, DANGER_COLOR_DISPLAY_SECONDS);
            if (AveragedFrameTime > FRAMETIME_DANGER_THRESHOLD)
            {
                DangerTimer = DANGER_COLOR_DISPLAY_SECONDS;
            }

            int displayItemCount = 0;
            FrametimeDisplayBatch.Begin();
           
            if (ShowFrametimeText)
            {
                FrametimeDisplayBatch.DrawString(FrametimeDisplayFont, "Frame Time: " + (ShowAveragedFrametime ? AveragedFrameTime : frameTime.TotalMilliseconds) + "ms", FrametimeDisplayPosition + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount++), DangerTimer > 0.0f ? FrametimeDangerDisplayColor : FrametimeDisplayColor);
                FrametimeDisplayBatch.DrawString(FrametimeDisplayFont, "Total Memory: " + TotalMemoryKB + "KB", FrametimeDisplayPosition + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount++), FrametimeDisplayColor);
                FrametimeDisplayBatch.DrawString(FrametimeDisplayFont, "Recent GCs: " + (int)RecentGarbageCollections, FrametimeDisplayPosition + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount++), FrametimeDisplayColor);
            }

            DrawIcon(PerfIconType.Stopwatch, FrametimeDisplayPosition + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount));
            DrawIcon(FrametimeToPerfIcon(ShowAveragedFrametime ? AveragedFrameTime : (float)frameTime.TotalMilliseconds), FrametimeDisplayPosition + Vector2.UnitX * PERF_ICON_WIDTH + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount));
            displayItemCount++;

            int garbageX = 0;
            int garbageY = 0;
            for (int i = 0; i < (int)RecentGarbageCollections; ++i)
            {
                DrawIcon(PerfIconType.GarbageBin, FrametimeDisplayPosition + Vector2.UnitX * PERF_ICON_WIDTH * garbageX + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * displayItemCount) + Vector2.UnitY * (FrametimeDisplayFont.LineSpacing * garbageY));
                garbageX++;
                if (garbageX > 10)
                {
                    garbageY++;
                    garbageX = 0;
                }
            }
            displayItemCount++;

            FrametimeDisplayBatch.End();

            base.Draw(gameTime);
        }

        private void DrawIcon(PerfIconType iconType, Vector2 position)
        {
            FrametimeDisplayBatch.Draw(PerfIconSheet, position, new Rectangle((int)iconType * PERF_ICON_WIDTH, 0, PERF_ICON_WIDTH, PERF_ICON_WIDTH), Color.White);
        }

        private PerfIconType FrametimeToPerfIcon(float frameTime)
        {
            if (frameTime < FRAMETIME_DANGER_THRESHOLD * 0.75f )
            {
                return PerfIconType.HappyFace;
            }
            else if (frameTime < FRAMETIME_DANGER_THRESHOLD * 1.5f)
            {
                return PerfIconType.NeutralFace;
            }

            return PerfIconType.SadFace;
        }
    }
}
#endif

The main issue with the memory output in my frametime debug display is that the constant memory allocations causes it to fluctuate between values several megabytes apart as temporary memory is allocated then periodically disposed by garbage collection. This means that the memory display ticks up constantly then drops down to a threshold value from which it starts ticking again. Naturally, this makes it hard to read the memory display and causes it to not accurately represent the memory being allocated by the game itself.

While I mentioned modifying the display logic to prevent memory allocations, I found an easier alternative I could implement without dramatically changing the existing code. Basically, I opted to only update the memory value being displayed just after a garbage collection. This means that the number displayed doesn’t change constantly as new memory is allocated, making it easier to read. Because it’s updated after a garbage collection run, the memory usage I log will exclude memory that was allocated but waiting to be released. Now, because I miss small allocations that don’t total up enough to trigger garbage collection and garbage collection itself is not guaranteed to necessarily clean up all potentially releasable memory, this approach to memory reporting is not entirely accurate. It’s pretty close however and the stability of the number gives me a much better reading of how much memory the various parts of my game are using relative to each other.

The code I use to only check memory usage after a garbage collection is below:

    //In class member declarations
    WeakReference GcDetectionReference;

...

    //In component Draw() function
    if (!GcDetectionReference.IsAlive)
    {
         GcDetectionReference = new WeakReference(new Object());
         TotalMemoryKB = GC.GetTotalMemory(false) / 1024;
    }

The trick here (which I picked up from this post) is to use a WeakReference around a dummy object as a canary for detecting garbage collections. WeakReferences aren’t considered to be holding memory for the purpose of garbage collections so they can have memory be deleted out from under them. In this scenario, the WeakReference GCDetectionReference is the only reference to the dummy object we allocate so it is very likely to for said object to be deleted during garbage collection. This allows us know when a garbage collection has just occurred and thus know when to update the memory usage report.

I hope this bit of code proves useful to my fellow XNA game devs. For convenience, the full code for the updated FrametimeCounterComponent follows:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Diagnostics;
using System.Text;
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Audio;
using Microsoft.Xna.Framework.Content;
using Microsoft.Xna.Framework.GamerServices;
using Microsoft.Xna.Framework.Graphics;
using Microsoft.Xna.Framework.Input;
using Microsoft.Xna.Framework.Media;


namespace EstrellaLib.Debug
{
    /// <summary>
    /// This is a game component that implements IUpdateable.
    /// </summary>
    public class FrametimeCounterComponent : Microsoft.Xna.Framework.DrawableGameComponent
    {
        Stopwatch FrametimeStopwatch;
        
        SpriteFont FrametimeDisplayFont;
        SpriteBatch FrametimeDisplayBatch;

        public Vector2 FrametimeDisplayPosition;
        public Color FrametimeDisplayColor;

        const double FRAMETIME_DANGER_THRESHOLD = 1000.0f / 60.0f;      //If averaged frametime goes over this threshold...
        const float DANGER_COLOR_DISPLAY_SECONDS = 2.0f;                //... the frametime display will change color for this many seconds.
        
        float DangerTimer;
        public Color FrametimeDangerDisplayColor;
        float AveragedFrameTime;

        public bool ShowAveragedFrametime;

        WeakReference GcDetectionReference;
        long TotalMemoryKB;

        public FrametimeCounterComponent(Game game)
            : base(game)
        {
            ShowAveragedFrametime = true;
            FrametimeDisplayPosition = Vector2.One * 10.0f;
            FrametimeDisplayColor = Color.Green;
            FrametimeDangerDisplayColor = Color.Magenta;
            GcDetectionReference = new WeakReference(null);
        }

        /// <summary>
        /// Allows the game component to perform any initialization it needs to before starting
        /// to run.  This is where it can query for any required services and load content.
        /// </summary>
        public override void Initialize()
        {
            FrametimeStopwatch = new Stopwatch();
            FrametimeStopwatch.Start();
            base.Initialize();
        }

        protected override void LoadContent()
        {
            FrametimeDisplayBatch = new SpriteBatch(Game.GraphicsDevice);
            FrametimeDisplayFont = Game.Content.Load<SpriteFont>("Debug/Fonts/Default");
            base.LoadContent();
        }

        /// <summary>
        /// Allows the game component to update itself.
        /// </summary>
        /// <param name="gameTime">Provides a snapshot of timing values.</param>
        public override void Update(GameTime gameTime)
        {
            base.Update(gameTime);
        }

        public override void Draw(GameTime gameTime)
        {
            TimeSpan frameTime = FrametimeStopwatch.Elapsed;
            FrametimeStopwatch.Reset();
            FrametimeStopwatch.Start();

            if (!GcDetectionReference.IsAlive)
            {
                GcDetectionReference = new WeakReference(new Object());
                TotalMemoryKB = GC.GetTotalMemory(false) / 1024;
            }

            AveragedFrameTime = AveragedFrameTime * 0.9f + (float)frameTime.TotalMilliseconds * 0.1f;
            DangerTimer = MathHelper.Clamp(DangerTimer - (float)gameTime.ElapsedGameTime.TotalSeconds, 0.0f, DANGER_COLOR_DISPLAY_SECONDS);
            if (AveragedFrameTime > FRAMETIME_DANGER_THRESHOLD)
            {
                DangerTimer = DANGER_COLOR_DISPLAY_SECONDS;
            }

            FrametimeDisplayBatch.Begin();
            FrametimeDisplayBatch.DrawString(FrametimeDisplayFont, "Frame Time: " + (ShowAveragedFrametime ? AveragedFrameTime : frameTime.TotalMilliseconds) + "ms", FrametimeDisplayPosition, DangerTimer > 0.0f ? FrametimeDangerDisplayColor : FrametimeDisplayColor);
            FrametimeDisplayBatch.DrawString(FrametimeDisplayFont, "Total Memory: " + TotalMemoryKB + "KB", FrametimeDisplayPosition + Vector2.UnitY * FrametimeDisplayFont.LineSpacing, FrametimeDisplayColor);
            FrametimeDisplayBatch.End();

            base.Draw(gameTime);
        }
    }
}

You see, there are times when designs that look “right” when viewed through an OOP lens turn out to be ill-suited to solving certain problems in game programming. One of the major causes of this is the tendency of OOP to encourage thinking of problems in terms of single data objects. Often this works because handling multiple instances of an object is a natural extension once you know how to handle a single instance. This isn’t always the case however and it’s common for OOP-oriented programmers (OOPOP?) to overlook cases in which it would be better to think of processing data as a gestalt as opposed to as lists of stand-alone objects.

To clarify this idea, I’ll share a recent experience with some code at work.

The story that follows is a familiar one. We, the programmers, had adopted a fully-featured game engine with a suitably large codebase. The engine’s 3D features were, as to be expected, top-notch. The engine’s 2D feature were not quite so developed. It mainly consisted of a set of functions to draw sprites onto a 2D HUD at particular positions, scales, rotations, etc. It had no useful UI features like buttons or other widgets nor could it handle hierarchies of sprites. This meant that any sort of menus beyond the simplest single-depth affairs would be impossibly clumsy to implement.

So, like any good programmer, one of our number set about extending the engine’s 2D HUD system with our own hierarchal sprite management system as well as some basic widgets. Throw in some runtime tools for tweaking UI layouts and we were golden. At least, we were until we started implementing some of the more complicated menus in the game.

You might not notice it at first, but most game menus actually have significant amounts of information being displayed at once. Unchecked, these menus can result in surprisingly large numbers of sprite renders. And that’s what we had in our project. Lot’s of sprites being rendered at once and our framerate tanking on our menus. Heavy menus? I thought the game itself was supposed to be the heavy part? What happened?

Well, having the hierarchal sprite system written in a scripting language didn’t help performance, but that’s a straight-forward transcription away from being solved. More to the root of the problem was the design of the hierarchal sprite system itself. You see, it was almost text-book OOP with “sprite” being the core object. Sprites were independent objects capable of rendering themselves The first thing the programmer probably did was write code to make sure a single sprite could render itself. Then, he made sure they could be connected hierarchically, deriving their absolute screen position based on their relative offset from their parent.

For the most part, that approach makes sense, until you look carefully at how sprites were actually being used. Almost every sprite we used was the child of another sprite in a multi-level child-parent hierarchy. We would render our root sprites and expect the render command to travel down to child sprites through the hierarchy. So far, so good. But, every sprite was designed to be able to calculate its own absolute screen position. To do this, each sprite would query its parent’s absolute position and add its own relative offset. These absolute position calculations therefore involved climbing back up the hierarchy to the root. This operation was performed by each child and would only become more expensive as we went deeper down the hierarchy with each depth requiring longer trips back to the root to calculate screen positions.

“Wow”, you may say. “That behavior is horrid.” And you would be right. If you’re already traveling down a hierarchy, it makes sense to calculate values like absolute screen position and propagate them downwards as you perform the traversal. But, it was surprisingly non-obvious from the OOP perspective. Had the programmer who implemented the sprite system thought in terms of how hierarchies of sprites should be rendered as opposed to how single sprites should render themselves, I imagine he would have written very different code.

Object-oriented programming has a powerful tendency to encourage thinking in terms of single objects and assuming that the handling of multiple instances of said objects is a trivial extension. For a lot of high-level game logic, this is probably a correct assumption. But, in cases where you need to process large amounts of data, this sort of single-instance thinking can be debilitating. While swearing off object-oriented programming would be akin to throwing the baby out with the bathwater, it’s good practice to occasionally question your own thought process and approach problems from a different angle.