Log

All output that OpenSG generates is channeled through the Log class, which is defined in OSGLog.h. OpenSG supplies a global Log object that is used by the library, but the application can create its own logs, if needed.

Every log message has one specific level. Available levels are FATAL, WARNING, NOTICE, INFO and DEBUG. They are also numbered from 0 to 5. The verbosity of the system can be controlled by ignoring messages of specific levels. This can be achieved by calling osgLog().setLogLevel( <enum> ); or by setting the environment variable OSG_LOG_LEVEL.

The system log has two different interfaces. One is based on C++ streams, one is based on C printf semantics.

The stream interface can be used by using SFATAL, SWARNING, SNOTICE or SINFO instead of cout or cerr. Note that there is no SDEBUG for efficiency reasons, as FDEBUG can be compiled out. These print the position in the code where the log is executed. For multi-line outputs you'll only want that on the first line, for the other lines use PFATAL, PWARNING, PNOTICE or PINFO.

To synchronize multiple outputs from various threads all S* commands lock the stream. You have to use 'osgendLog' (e.g. SFATAL << "Message" << endLog;) to unlock the stream output.

Example: SINFO << "Line 1 of message 1" << endl; PINFO << "line2 of message 1" << endLog; SINFO << "Message 2" << endLog;.

The C interface tries to mimic the printf semantics. The following functions can be used for that: FFATAL, FWARNING, FNOTICE, FINFO and FDEBUG. The only difference to printf is that they have to be called with double parentheses, i.e. FWARNING(("What do you mean by %s?", s));. The nice thing about the C style interface is that the whole output can be compiled out. Actually, the FDEBUG (( )) are only compiled in when OSG_DEBUG is set. The OSG_DEBUG define is automatically set while compiling the system in debug (default) mode.

The user can activate/deactivate various elements per log message at runtime by changing the LogHeaderElem mask. The following elements are supported right now:

LOG_BEGIN_NEWLINE_HEADER (creates an extra newline in front of every output), LOG_TYPE_HEADER (writes the Level (e.g. WARNING) as first element), LOG_TIMESTAMP_HEADER (writes a timestamp), LOG_MODULE_HEADER (writes the name of the current module), LOG_FILE_HEADER (writes the source file name), LOG_LINE_HEADER (writes the source line number) and LOG_END_NEWLINE_HEADER (creates an extra newline at the end)

When unchanged, the time stamp will be the time in seconds since the program started. The user can set/reset the time stamp at any time (e.g. osgLog().resetRefTime()).