Output

Description

In Orxonox, we don't use std::cout or printf for output, instead we use orxout(). orxout() is a function which can be used almost like std::cout, but adds a level and an optional context to the output. Each output message is then sent to the console, the log-file and the in-game-shell.

The user can set the desired maximal output levels for every device (console, logfile, shell) in the config file in the "Output" section.

Possible arguments

• orxout(): Acts like std::cout, used for debug output.
• orxout(level): Defines a level for the output
• orxout(level, context): Defines a level and a context for the output

Levels

Levels are used to define the meaning and the importance of an output message.

See the doxygen page or util/OutputDefinitions.h for a list of all output levels.

Each level has a different meaning and a different priority. The user_* levels are used to provide the user with (sparse) information about the program's state. The internal_* levels are usually only visible in the log-file and are used by developers. The verbose_* levels are usually not visible (not even in the log-file) and are only activated in rare cases (debugging).

The *_error levels are used for (unrecoverable) errors, while *_warning levels are used for (solvable, but not breaking) problems. *_status levels are used to log the program's state and *_info provides some additional information about this state.

Contexts

Contexts give additional information about the part of the program that generated the output message. Contexts are basically just strings, which means they are identified by their name. It's possible to activate verbose output of only one context which allows debugging of specific parts of the program without being flooded with thousands of unrelated output messages.

Most contexts are defined in util/OutputDefinitions.h, but there might exist more in different locations.

Examples

#include "util/Output.h"

orxout(internal_info) << "Start executing the function..." << endl;

bool success = functionWithAMeaningfulReturnValue(params);

orxout(internal_info) << "...finished executing the function." << endl;


if (success)
    orxout(user_info) << "The execution of the function was successful." << endl;
else
    orxout(user_error) << "The execution of the function failed." << endl;

namespace
{
    REGISTER_OUTPUT_CONTEXT(test);
}

orxout(verbose, context::test) << "This is some verbose output with 'test' context" << endl;