Purpose

Inserts a keypoint into the log

Protoype

void CError::InsertKeypoint (string str_keypoint, int i_indent = 0)

Parameters

Description

Keypoints can have two uses in a log file. The first use is that they notify you when certain major events happen, so you can better seperate the log into parts. The second use is that they can be used to profile routines or sections of code, since they log elapsed time. To make use of this, keypoints should be insterted in pairs - one at the start of a section, another marking the end.

Each keypoint can have it's own text, like "BEGIN MAIN LOOP" and "END STARTUP" to identify the keypoint in the log. The keypoints don't have to be in caps as demonstrated here, but it does make them stand out better. You pass in the string with the keypoint text for str_keypoint.

In addition, you can indent keypoints. This is not a literal indentation and they do not appear indented in the log file, but indenting keypoints is what lets you track the elapsed time of a section of code within he elapsed time of another section of code. (Elapsed time displayed in mins:secs:ms). This can be a confusing concept at first so the Use section below describes the process in detail. When creating a top-level keypoint (the first in a string of indents) you only have to pass in the keypoint name. To create an indent you pass in the keypoint name along with INDENT for i_indent. To close an indent (and calculate the elapsed time for that indent, just pass in the keypoint name, ignoring the second parameter. Again, the example below demonstrates this in detail.

Use

CError error;

// set keypoint for main game loop
error.InsertKeypoint("ENTERING MAIN GAME LOOP");

while (true)
{
    // do some game handling stuff

    // set keypoint for screen rendering
    error.InsertKeypoint("BEGIN RENDERING", INDENT);

    // render some game objects

    // we want to profile the text rendering function as well
    error.InsertKeypoint("BEGIN TEXT RENDERING", INDENT);

    // render text

    // start closing the keypoint indents
    error.InsertKeypoint(END TEXT RENDERING");

    // render rest of game objects

    // close render keypoint
    error.InsertKeypoint("END RENDERING");

} // keep looping

// close first indent last
error.InsertKeypoint("LEAVING MAIN GAME LOOP");

Use Results
(for game loop with only one iteration)

*****ENTERING MAIN GAME LOOP*****
Report Time: 23:8:6:981

*****BEGIN RENDERING*****
Report Time: 23:8:6:991

*****BEGIN TEXT RENDERING*****
Report Time: 23:8:6:991

*****END TEXT RENDERING*****
Report Time: 23:8:7:1
Elapsed time: 0:0:10

*****END RENDERING*****
Report Time: 23:8:7:11
Elapsed time: 0:0:20

*****LEAVING MAIN GAME LOOP*****
Report Time: 23:8:7:44
Elapsed time: 0:0:63