About

Even though it was eventually integrated into the KoreTech framework (and hence also ColorIt), this simple profiler I wrote can be seen as a project of its own. I rolled it around half a year earlier, when I felt the urge to have a look at how some of the stuff I played around with performed. It’s a simple scope-based profiler (meaning it puts a tiny object on the stack for the sole purpose of recording the time that has passed between its creation and its going out of scope)  for single-threaded use that lets users hook up their own custom functions for memory allocation and deallocation as well as getting timestamps and printing. Everything the profiler does is wrapped in preprocessor macros so profiling can instantly be disabled if so desired. It requires only two files, but it kind of depends on  KORE_ASSERT as I was too lazy to rip out all those handy assertions just for presentation or publishing purposes. Actually doing that, if need be, is left as an exercise to the user.

It comes (just for once…) with fairly thorough documentation by way of comments so don’t sweat reading all of the following, if you really want to use it and are more of a hands-on guy.

Usage

The module must be initialized by calling

PROFILE_INITIALIZE(ALLOCATE, GET_CYCLES_FUNCTION, CYCLES_TO_SECONDS_FUNCTION, PRINT_FUNCTION, PRINT_OSD_FUNCTION)

(or kore::profile::profile_initialize(…), if you hate macros) and passing function pointers for allocation and printing. The Alloc function pointer requires malloc-signature and the Print function pointer requires printf-signature. Users must also pass pointers to functions that return the current number of cycles passed since system start (or something like that, it’s only about time increments anyway) and that can convert that number into seconds. The rationale behind this is that I didn’t want to muck around with conversion from cycles to seconds for every value the profiler records but rather store all values as uints of sufficient size and only do the conversion when statistics are evaluated. Once everything is initialized, users can either use

PROFILE_SCOPE_ONCE(VARIABLE_NAME, MESSAGE)

providing a unique name for the scoped object and a message to be printed upon entering and leaving the scope or

PROFILE_SCOPE_STATISTICS(VARIABLE_NAME, PROFILE_IDENTIFIER_ENUM_VALUE)

providing again a unique name for the scoped object and a profiling identifier as added to the enumeration in profile.h. PROFILE_SCOPE_ONCE will instantly attempt to print the duration the created object was alive in both cycles and seconds, while PROFILE_SCOPE_STATISTICS just records the duration for the specified category this turn and that’s that. Every hundred frames or so, users can call

PROFILE_PRINT_STATISTICS()

to have a brief summary printed using the supplied print function. That summary contains for each profile identifier the minimum/maximum and average duration. Users can adjust the number of samples that should be taken for the running average by modifying NUM_SAMPLES_MODIFIER in profile.h. Note that the number of samples must always be a power of two, so that modifier actually results in

const uint32_t MAX_NUM_SAMPLES = (1 << NUM_SAMPLES_MODIFIER);

When all is said and done, just kill the damn thing by calling

PROFILE_SHUTDOWN(DEALLOCATE)

where DEALLOCATE is the pointer to a deallocation function with free-signature and be done with it.

Remarks

First of all, yes, it’s very simple and has almost no functionality. But sometimes you don’t need much and settle with the tool that will just about do the job. I’ll definitely make the (now global) profiler-state bundled into an object so we can instantiate profilers (the whole thing, not ProfileScopes) in thread-local memory in order to be able to profile multi-threaded stuff. This will have to wait until I get around to implement the job-system for KoreTech, though.

Even though not part of the profiler itself, it should be noted that the kore::timer-thingy in the source folder is just a wrapper around QueryPerformanceCounter/QueryPerformanceFrequency on Windows and thus suffers from the same limitations. Most notably that your process could be migrated between cores and thus readings could not be correct. IF (and I haven’t seen this yet on any of the few PCs I  have around) your mainboard vendor has not properly implemented this in their drivers. Most halfway decent vendors seem to use dedicated hardware for getting timestamps (that’s often not clocked as fast the actual CPU, at least on my Intel  P58) and that also does not seem to suffer from thread migration issues. But as always, you can’t count on that.

There’s some other stuff like the PrintScreenFunction pointer that can be provided upon PROFILE_INITIALIZE(…) that I use to print a less verbose version of the statistics stuff onto the screen in KoreTech or the possibility to feed it an Allocator object instead of an allocate function that I also use in KoreTech. Omitting that stuff upon init won’t do anything bad. The profiler will just print a message telling the user that it will use the fallback of printing statistics via PrintFunction rather than using the default PrintScreenFunction.

What I did Contribute

• Simple modular framework in which the game runs
• Component based object model – Entities are integer IDs, components are retrieved from stores where they are kept in cache-friendly pools
• Renderer, Shaders for Phong Shading and Normal Mapping, Material System supporting Selective Bloom Post Processing and selective specularity
• Simple, extensible key frame animation system for model position, orientation, scaling and also material properties such as bloom-intensity or specular exponent/intensity
• Scriptable in-game console that mediates between sub-systems
• Various debugging facilities such as a tracing heap allocator, static and run-time assertions (thanks Niklas Frykholm, Charles Nicholson and Tom Forsyth) as well as logging of various debug-streams to files
• Lightweight in-engine scope profiler
• LibRocket render interface
• Sane build configuration (checkout, build, copy the BuildOutput folder containing just the executable, two 3rd-party dlls and an asset archive containing everything from textures to models to compiled shaders)
• SIMD-optimized cellular automaton simulation and bitmap painting code
• Cache-efficient Flood Filling algorithm

What I did not contribute

• Most of the design and gameplay code (Thanks, Martin!)
• Our cool radial menu (again, Thanks Martin!)
• Any art assets (would you have guessed: Thanks, Martin! Also thanks Thomas G.!)
• The Audio Module (even though I regret it)
• Loading of compressed assets (thanks PhysFS!)
• Font Rasterization and UI Layout (thanks LibRocket!)
• Offline Model Converter (fbx > vertex buffer ready model format, thanks Georg!)

The Game

ColorIt is a real time tactics game for two to four players in splitscreen-mode. Players use a Microsoft XBox 360 Controller for Windows to control their cursor across the map. Pressing the A-button will mark the area below their cursor with each player’s respective color. Holding that same button, players can paint paths and figures onto the neutral map. Paths that are connected to their own base building will gradually be conquered by their color. Using this mechanic, players need to first mark and then conquer strategic points that are scattered across the map. As long as strategic points are held by a player, they will contiguously increase that player’s victory score by a fixed amount per time quantum. The player that first manages to completely fill their victory score wins the game.

Players can paint across opponent’s paths and by doing so, cut off their supply. Any territory that is not connected to a player’s base building by at least one path will gradually deteriorate and finally vanish unless it is connected again.

Players can utilize three additional abilities:

• Placing an outpost by pressing B – This will fortify their own color in the outpost’s vicinity so that opponents cannot simply paint over it
• Placing bridge heads by pressing X – The first bridge head must be located in their own territory, the second one can be placed anywhere. Once a certain amount of time, dependent on the distance between the bridge heads has passed, the bridge heads will be connected by a path of the building player’s color. Such paths can be interrupted  by placing outposts between bridge heads
• Placing a nuke by pressing Y – Nukes will detonate after a certain amount of time, neutralizing any territory in their vicinity, even the placing player’s. Nukes can be defused by cutting of their supply line to the base building.

Post-Mortem

Read my post-mortem analysis of the ColorIt project!

Downloads

Sadly, I can’t yet offer the complete game for download, as we ponder publishing it with added bells and whistles. That’s also the reason why I can’t offer the complete source code yet, even though I’d like to. I will, however, publish the source code for some interesting modules and link them in the details section of this page.

• ColorIt Trailer (mp4 | 180MB, also available on YouTube)

Media

•  Screenshots

Details

• The KoreTech Profiler (+source)
• The Building Blocks of KoreTech (+source) – Coming soon!
• The KoreTech Console (+source) – Coming soon!