Debug and Output Functions

Table of Contents

• About
• Warning Levels
• Console Output
• Debug Stop
• Asserts
• Further Reading

About

The most simple way to debug and analyse code is to print data and events to a debug console. The MAXON API offers multiple functions that allow printing debug messages, checking for critical conditions and triggering debug stops.

Note

To print messages to Cinema 4D's "Console" window use ApplicationOutput(). See LoggerInterface Manual.

Warning Levels

Output messages can be assigned to one of these levels: diagnostic, warning or critical. By default messages of all three levels are printed to the debug console.

The output to the console can be filtered by setting the configuration variables g_diagnostic, g_warning and g_critical to true or false. See Configuration Variables.

Console Output

C++ code can be compiled to either a release or debug build. DebugOutput() prints the given message only in such a debug build; it does not cost any time in a release build.

The following flags can be used to define the type of message:

• maxon::OUTPUT::DIAGNOSTIC: Diagnostic output. This is also the default value.
• maxon::OUTPUT::WARNING: Warning output.
• maxon::OUTPUT::CRITICAL: Critical output.

The message can be formatted with:

• maxon::OUTPUT::NOLINEBREAK: No line break is added.
• maxon::OUTPUT::HEADER: A header with line number and file name is added.

  // This example prints two debug messages using different flags.
 
  maxon::OUTPUT flags = maxon::OUTPUT::DIAGNOSTIC | maxon::OUTPUT::HEADER;
  DebugOutput(flags, "@", "Debug test"_s);
 
  flags = maxon::OUTPUT::CRITICAL | maxon::OUTPUT::HEADER;
  DebugOutput(flags, "@", "Critical Error"_s);

The following functions print messages in both debug and release builds:

• DiagnosticOutput(): Prints a diagnostic message.
• DiagnosticVarOutput(): Prints the names and values of the given variables.
• WarningOutput(): Prints a warning.
• CriticalOutput(): Prints a critical message. Also triggers a debug stop.
• OutputWithFlags(): Prints a message with the given flags.

  // This example prints various debug messages.
 
  // simple message
  const maxon::Int value = 1;
  DiagnosticOutput("The value is: @", value);
 
  // debug variable values
 
  const maxon::Int    i = 123;
  const maxon::String msg { "This is a test" };
 
  DiagnosticVarOutput(i, msg);

  // This example checks if the sub-functions succeeded.
  // If not, debug messages are printed.
 
  // perform task
  maxon::Result<void> res = PerformSimpleTask();
  // check for success
  if (res == maxon::FAILED)
    WarningOutput("Task could not be performed.");
 
  // perform task
  res = PeformCriticalTask();
  // check for success
  if (res == maxon::FAILED)
    CriticalOutput("Critical Task could not be performed.");

Debug Stop

If Cinema 4D is run with a debugger the program flow will stop if a breakpoint is hit. Such a breakpoint can be triggered dynamically with these functions:

• DebugStop(): Stops the execution and prints the given message. Only works in a debug build.
• CriticalStop(): Stops the execution and prints the given message as a critical warning.

  // This example checks if the sub-functions succeeded.
  // If not, debug stops are triggered.
 
  // perform task
  maxon::Result<void> res = PerformSimpleTask();
  // check for success
  if (res == maxon::FAILED)
    DebugStop("Task could not be performed.");
 
  // perform task
  res = PeformCriticalTask();
  // check for success
  if (res == maxon::FAILED)
    CriticalStop("Critical Task could not be performed.");

Asserts

The following macros can be used to check critical conditions. If the condition is not fulfilled the program is stopped.

• DebugAssert(): If the condition is not fulfilled DebugStop() is triggered.
• CriticalAssert(): If the condition is not fulfilled CriticalStop() is triggered.
• SizeAssert(): Checks the size of a given type at compile-time.

Note

Asserts will only be executed in debug builds. In release code, the check won't be executed.

See also Error Utility.

  // This example checks the return values of the sub-functions.
  // Asserts are used to check these values.
 
  const Int32 elementCnt = GetElementCount();
  DebugAssert(elementCnt > 0, "Invalid Element Count"_s);
 
  const Int32 error = GetErrorCode();
  CriticalAssert(error == 0, "Error Code is not 0."_s);

Further Reading

• Debugging Techniques
• LoggerInterface Manual
• Error System