fiftysixtysoftware.com/blog

If you’re doing more than the simplest of games, chances are you want to know which things take the most time so that you can focus your optimization efforts in where it makes the most impact. Of course, Instruments with Time Profiler gives you a detailed list of exactly what functions and methods are hogging those precious processor cycles, and I thoroughly recommend using Instruments. However, there are some cases when you would welcome a different toolset and that’s when CCProfiler and CCProfilingTimer come in handy. They are not as easy to use as Instruments, though, and there is surprisingly little instructions on how to use them. Perhaps that’s a testament of just how good Instruments is, or perhaps people are not aware of them. So, if you’re using Cocos2D for the iOS, read on to learn more.

The profiling tools in cocos2d are admittedly simple: you need an instance of CCProfilingTimer for each piece of code you want to time, and you create it via the singleton CCProfiler object. The CCProfiler then prints out the average times for each timer once per second, and that’s it. You won’t get any percentages of time used or any information about the call stack. You will, however, get information about how much actual time each timed piece of code takes, and if you’re targeting, say, 60 FPS, well, you know you can spend at most 16.67 milliseconds per frame. So the actual time used is a very useful metric for game developers.

Though they are simple, I have to admit I made a couple of minor changes to the stock CCProfiler and CCProfilingTimer to make them a bit easier to use. With the stock implementation, you’re supposed to keep track of the CCProfilingTimer instances you’re using and dispose of them once you’re done. This means you need to modify code at four or five different places: declare the ivars in the .h file, init the instances, start timing for an instance, end timing for an instance, and finally release the instance once you’re done with everything. I thought that made things overly complicated, especially since you’re bound to use a number of different CCProfilingTimers, one for each thing you want to time, and I wanted to simplify things as much as I could.

My aim was to make it possible to use profiling with code modifications in just two places: starting timing and ending timing. That also means that you need to create the timer instance when you start timing, and you’ll need a way to access the instance when you stop timing. The latter is usually not such a big problem since in most cases you will start and end the timing within the same function or method and you can use the same instance variable, but it is possible to access the timers using the name and instance you used when creating them.

The resulting solution I came up with was to use a dictionary to hold the CCProfilingTimer instances in the CCProfiler, and use the timer name as the dictionary key. That way, only the CCProfiler keeps track of the timer instances and disposes them when it’s done. The original CCProfiler used a mutable array and, while it would have been possible to continue using it, checking the array for containsKey would be a linear time operation and could turn out to be a problem with a large number of timers. I’ve tagged the lines I changed in the source files with my initials – MPT – just in case you’re interested to see what I did there.

So, how do you actually use the modified CCProfiler and CCProfilingTimer? Here are the things you need to do:

1. Grab the zip containing the modified CCProfiling.h and CCProfiling.m -files, unzip it and copy the files over the stock file in cocos2d/Support.

2. Head over to ccConfig.h, find CC_ENABLE_PROFILERS and change the value to 1.

3. Go to your code where you want to use profiling. Do something like this:

#if CC_ENABLE_PROFILERS
    CCProfilingTimer *timer = [CCProfiler timerWithName:@"YourTimerName" andInstance:self];
    CCProfilingBeginTimingBlock(timer);
#endif
    [self yourMethodYouWantToBeTimed];
    [self yourOtherMethodIncludedInTheTiming];
#if CC_ENABLE_PROFILERS
    CCProfilingEndTimingBlock(timer);
#endif

4. That’s it. When you run your app, CCProfiler will print average times to the console once per second.

It’s not strictly necessary to wrap the profiling code bits with the preprocessor #ifs, but it makes it easy to turn profiling on and off for the whole app. If you want to begin and end the timing in different methods, but still within the same instance, change the end timing to:

#if CC_ENABLE_PROFILERS
    CCProfilingEndTimingBlock([CCProfiler timerWithName:@"YourTimerName" andInstance:self]);
#endif

If you’re starting and ending the timing in different classes and/or instances, you’ll need to pass the timer name and the instance used to create the timer to where you end the timing, otherwise you won’t be able to reference the timer. In real world usage I suspect these scenarios will be exceedingly rare.