| CRM64Pro GDK v0.17.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Log
Core modules

## Description

Log Manager and Log objects for application and GDK message output [v26.02.0].

### Overview

The Log module handles all logging output for both the client application and the GDK itself. The Log Manager handles the creation and destruction of Log objects and always owns a default log named "default" (although it is not initialized by default).
All CRM64Pro GDK modules use this default log for messages and information output. The client application can use the default log or create any number of additional Log objects.

### Key features

- Default log: Built-in "default" log used by all GDK modules
- Multiple logs: Create additional Log objects for application-specific output
- Pause control: Stop and resume log output without releasing the log
- Debug mode: Automatic error code logging when using GDK debug builds
- Color output: ANSI color coding for stdout output based on severity levels
- Indentation: Automatic indentation management for structured output
- Prefix characters: Customizable prefix characters for organized output blocks

### Default log

The Log Manager always owns a default log named "default" with special characteristics:

Initialization | Not initialized by default; call Log::init() to enable output
GDK usage | All CRM64Pro GDK modules output messages through this log
Release protection | Cannot be released; use Log::pause() to stop output

### Console Output Colors

When using LM_STDOUT, messages are automatically colored based on severity:

LL_CRITICAL | Bold Magenta - Fatal errors / Crashes
LL_ERROR | Red - Runtime errors
LL_WARNING | Yellow - Undesirable states
LL_INFO | Default - Standard messages
LL_DEBUG | Cyan - Diagnostic information
LL_TRACE | Dark Gray - Low-level execution details

### Debug mode logging

An automatic error code logging mode is available when both conditions are met:

GDK version | Link against a GDK debug version
Log level | Set eLogLevel to LL_DEBUG

When enabled, all return error codes are automatically logged to the default log.

### Structured Output

The log system supports automatic indentation management and prefix characters for organized output:

Indentation | Use pushIndent()/popIndent() to manage automatic spacing
Prefix characters | Use setPrefix()/clearPrefix() to add block markers like "|" or ">>"
Combined usage | Combine prefix and indentation for clear hierarchical output

### Manager type

This is a standard manager: objects are not shared and must be unique using its name as the key. You cannot create an object with the same name as another one already created.

### Best practices

- Initialize the default log using Log::init() right after Main::Instance() to capture all GDK initialization messages
- Use Log::pause() instead of releasing when you need to temporarily stop default log output
- Create separate Log objects for different application subsystems to organize output
- Use debug builds with LL_DEBUG log level during development for comprehensive error tracking
- Ensure each custom log has a unique name before creation
- Access the manager exclusively through Main::ILogMgr()
- Use pushIndent()/popIndent() pairs to create structured, readable log output
- Use setPrefix() to mark logical blocks or sections with characters like "|" or ">>"
- Always call clearPrefix() when done to avoid prefix leaking into subsequent messages

Note
  The Log Manager and default Log are singletons, automatically created once Main is instantiated. You can get a reference to this manager using Main::ILogMgr() method.
  The Log Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

## Classes
class | CRM64Pro::Log
| Log Object class. More...
class | CRM64Pro::LogMgr
| Log Manager class. More...

## Enumerations
enum | CRM64Pro::eLogMode : Uint32 { CRM64Pro::LM_NULL = 0 , CRM64Pro::LM_FILE = 2 , CRM64Pro::LM_FILEAPPEND = 4 , CRM64Pro::LM_STDOUT = 8 , CRM64Pro::LM_CONSOLE = 16 , CRM64Pro::LM_RESERVED = 64 }
enum | CRM64Pro::eLogLevel { CRM64Pro::LL_OFF = 0 , CRM64Pro::LL_CRITICAL = 1 , CRM64Pro::LL_ERROR = 2 , CRM64Pro::LL_WARNING = 3 , CRM64Pro::LL_INFO = 4 , CRM64Pro::LL_DEBUG = 5 , CRM64Pro::LL_TRACE = 6 }
| Log levels. More...

## Functions
bool | CRM64Pro::Log::info (Sint32 iMode=0) override
| Request Log object information.
const string & | CRM64Pro::Log::getName () const override
| Get the name.
Uint32 | CRM64Pro::Log::getID () const override
| Get the ID.
bool | CRM64Pro::Log::init (const string &sAppname, eLogLevel eLL, eLogMode eLM, const string &sFilename="", const string &sAuthor="", const string &sEmail="", const string &sWeb="")
| Initialize the log object.
bool | CRM64Pro::Log::pause ()
| Disable log output temporarily.
bool | CRM64Pro::Log::resume ()
| Enable log output.
eGeneralStatus | CRM64Pro::Log::status () const
| Get log status.
bool | CRM64Pro::Log::msg (eLogLevel eLL, const char *szFmt,...)
| Write a message to the log.
eLogLevel | CRM64Pro::Log::getLogLevel ()
| Get log detail level.
eLogMode | CRM64Pro::Log::getLogMode () const
| Get log mode.
Sint32 | CRM64Pro::Log::setLogMode (eLogMode eLM, const string &sFilename="")
| Set log mode.
const string & | CRM64Pro::Log::getFilename () const
| Get log filename.
bool | CRM64Pro::Log::setTimeStamp (bool bEnabled)
| Enable/disable timestamp in log messages.
bool | CRM64Pro::Log::getTimeStamp () const
| Get timestamp status.
bool | CRM64Pro::Log::pushIndent (Sint32 iSpaces=2)
| Push a new indentation level onto the stack.
bool | CRM64Pro::Log::popIndent ()
| Pop the most recent indentation level from the stack.
bool | CRM64Pro::Log::resetIndent ()
| Reset all indentation to zero.
Sint32 | CRM64Pro::Log::getIndent () const
| Get the current total indentation level.
bool | CRM64Pro::Log::setPrefix (const char *szPrefix)
| Set a prefix character to be printed before each message.
bool | CRM64Pro::Log::clearPrefix ()
| Clear the prefix character.
bool | CRM64Pro::LogMgr::info (Sint32 iMode=0) override
| Request Log Manager information.
Sint32 | CRM64Pro::LogMgr::create (const string &sName, Uint32 iUnused=0) override
| Create a new log object.
bool | CRM64Pro::LogMgr::close (Sint32 idLog) override
| Close and destroy a log object.
Sint32 | CRM64Pro::LogMgr::getCount () const override
| Get number of loaded objects.
Sint32 | CRM64Pro::LogMgr::setName (Sint32 idLog, const string &sName) override
| Change the object name.
Log * | CRM64Pro::LogMgr::get (Sint32 idLog=0)
| Get a pointer to the log object.

## Enumeration Type Documentation

## ◆ eLogMode

enum CRM64Pro::eLogMode : Uint32

Log output modes used in Log::init() and Log::setLogMode().

Enumerator
LM_NULL | Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Disable output entirely.
LM_FILE | Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to a file and overwrite existing content.
LM_FILEAPPEND | Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to a file, appending to existing content.
LM_STDOUT | Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to standard output (stdout).
LM_CONSOLE | Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to the integrated default console.
LM_RESERVED | Log output mode reserved for internal use; do not use it.

## ◆ eLogLevel

enum CRM64Pro::eLogLevel

Log levels.

Enumerator
LL_OFF | Disable all logging.
LL_CRITICAL | Fatal errors, application crash, or assertions.
LL_ERROR | Runtime errors that do not require immediate termination.
LL_WARNING | Undesirable states or use of deprecated APIs.
LL_INFO | Runtime events (startup/shutdown). No-timestamp msgs.
LL_DEBUG | Detailed information for flow control.
LL_TRACE | Very detailed information, potentially high-volume.

## Function Documentation

## ◆ info() [1/2]

bool CRM64Pro::Log::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Log object information.

Writes object information to the default log.

Parameters

  iMode | unused for the time being.

Returns
  true on success or false on failure.

## ◆ getName()

const string & CRM64Pro::Log::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Uint32 CRM64Pro::Log::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ init()

bool CRM64Pro::Log::init | ( | const string & | sAppname,
|  | eLogLevel | eLL,
|  | eLogMode | eLM,
|  | const string & | sFilename = "",
|  | const string & | sAuthor = "",
|  | const string & | sEmail = "",
|  | const string & | sWeb = "" )

Initialize the log object.

Parameters

  sAppname | Name of your application.
  eLL | Log verbosity threshold. Messages with a severity level numerically higher than this will be ignored. See ::eLogLevel.
  eLM | Log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.
  sFilename | Name of log file. Only used with ::LM_FILE or ::LM_FILEAPPEND. Directory separators '\' and '/' are supported.
  sAuthor | Author name.
  sEmail | Author email address.
  sWeb | Author web site.

Returns
  true on success or false on failure.

## ◆ pause()

bool CRM64Pro::Log::pause | ( |  | ) |

Disable log output temporarily.

Temporarily disables log output.

Returns
  true on success or false on failure.

## ◆ resume()

bool CRM64Pro::Log::resume | ( |  | ) |

Enable log output.

Re-enables log output.

Returns
  true on success or false on failure.

## ◆ status()

eGeneralStatus CRM64Pro::Log::status | ( |  | ) | const

Get log status.

Returns
  ::C64_STATUS_DISABLED if output is disabled, or ::C64_STATUS_ENABLED if output is enabled (actual output depends on log mode).

## ◆ msg()

bool CRM64Pro::Log::msg | ( | eLogLevel | eLL,
|  | const char * | szFmt,
|  |  | ... )

Write a message to the log.

Parameters

  eLL | Severity level of the message. The message is logged only if this value is less than or equal to the verbosity set in init(). See ::eLogLevel.
  szFmt | A printf() style message format string.
  ... | Variable arguments for format string.

Returns
  true on success or false on failure.

## ◆ getLogLevel()

eLogLevel CRM64Pro::Log::getLogLevel | ( |  | ) |

Get log detail level.

Returns
  Current log verbosity. See ::eLogLevel.

## ◆ getLogMode()

eLogMode CRM64Pro::Log::getLogMode | ( |  | ) | const

Get log mode.

Returns
  Current log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.

## ◆ setLogMode()

Sint32 CRM64Pro::Log::setLogMode | ( | eLogMode | eLM,
|  | const string & | sFilename = "" )

Set log mode.

Parameters

  eLM | log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.
  sFilename | name of log file (only relevant with ::LM_FILE or ::LM_FILEAPPEND). Directory separators '\' and '/' are supported.

Returns
  0 on success, or a negative error code on failure.

## ◆ getFilename()

const string & CRM64Pro::Log::getFilename | ( |  | ) | const

Get log filename.

Returns
  The current log filename.

## ◆ setTimeStamp()

bool CRM64Pro::Log::setTimeStamp | ( | bool | bEnabled | ) |

Enable/disable timestamp in log messages.

Disabled by default. Only works with ::LM_FILE or ::LM_FILEAPPEND modes. Does not display timestamps in console output.

Parameters

  bEnabled | true to enable or false to disable.

Returns
  true on success or false on failure.

## ◆ getTimeStamp()

bool CRM64Pro::Log::getTimeStamp | ( |  | ) | const

Get timestamp status.

Returns
  true if enabled or false if disabled.

## ◆ pushIndent()

bool CRM64Pro::Log::pushIndent | ( | Sint32 | iSpaces = 2 | ) |

Push a new indentation level onto the stack.

Increases the current indentation by the specified number of spaces. Each call to pushIndent() should be paired with a corresponding popIndent(). Indentation is cumulative: multiple pushIndent() calls will add their spaces together.

Parameters

  iSpaces | Number of spaces to add to the current indentation level (default: 2).

Returns
  true on success or false on failure.

## ◆ popIndent()

bool CRM64Pro::Log::popIndent | ( |  | ) |

Pop the most recent indentation level from the stack.

Decreases the current indentation by removing the last pushed indent level. Should be called to match each pushIndent() call.

Returns
  true on success or false on failure.

## ◆ resetIndent()

bool CRM64Pro::Log::resetIndent | ( |  | ) |

Reset all indentation to zero.

Clears the entire indentation stack and resets current indentation to 0. Useful for recovering from mismatched push/pop calls or resetting state.

Returns
  true on success or false on failure.

## ◆ getIndent()

Sint32 CRM64Pro::Log::getIndent | ( |  | ) | const

Get the current total indentation level.

Returns the sum of all active indentation levels (total spaces).

Returns
  Current indentation level in spaces.

## ◆ setPrefix()

bool CRM64Pro::Log::setPrefix | ( | const char * | szPrefix | ) |

Set a prefix character to be printed before each message.

Parameters

  szPrefix | String to print at the beginning of each message (e.g., "|", ">>", etc.). The prefix appears before indentation.

Returns
  true on success or false on failure.

Note
  The prefix remains active until clearPrefix() is called.

## ◆ clearPrefix()

bool CRM64Pro::Log::clearPrefix | ( |  | ) |

Clear the prefix character.

Returns
  true on success or false on failure.

## ◆ info() [2/2]

bool CRM64Pro::LogMgr::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Log Manager information.

Writes manager information to the default log.

Parameters

  iMode | -1 to display only manager information. 0 (default) to display manager and all objects. Specific object ID to display manager and only that object.

Returns
  true on success or false on failure.

## ◆ create()

Sint32 CRM64Pro::LogMgr::create | ( | const string & | sName,
|  | Uint32 | iUnused = 0 )
| override

Create a new log object.

Parameters

  sName | name for the log object (e.g. 'myLog'). Must be unique; longer names are truncated to 64 characters.
  iUnused | unused for the time being.

Returns
  0 or greater on success (the log id) or a negative error code on failure.

## ◆ close()

bool CRM64Pro::LogMgr::close | ( | Sint32 | idLog | ) |
| override

Close and destroy a log object.

Parameters

  idLog | 0 to close all logs, or a specific log id. The default log cannot be removed with this method.

Returns
  true if at least one log was closed, or false if none were closed.

Note
  The default log (id=0) is ignored and will not be closed.

## ◆ getCount()

Sint32 CRM64Pro::LogMgr::getCount | ( |  | ) | const
| override

Get number of loaded objects.

Returns
  Number of log objects.

## ◆ setName()

Sint32 CRM64Pro::LogMgr::setName | ( | Sint32 | idLog,
|  | const string & | sName )
| override

Change the object name.

Parameters

  idLog | Log id.
  sName | new name (e.g. 'myLog'). Must be unique; longer names are truncated to 64 characters.

Returns
  0 on success, or a negative error code on failure.

## ◆ get()

Log * CRM64Pro::LogMgr::get | ( | Sint32 | idLog = 0 | ) |

Get a pointer to the log object.

Parameters

  idLog | Log id. 0 (default) returns the default log.

Returns
  nullptr if the log was not found, otherwise a pointer to the Log object.