Debug and Output Functions

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:

The message can be formatted with:

// This example prints two debug messages using different flags.
DebugOutput(flags, "@", "Debug test"_s);
DebugOutput(flags, "@", "Critical Error"_s);
PyCompilerFlags * flags
Definition: ast.h:14
OUTPUT
Output flags for OutputWithFlags and DebugOutput.
Definition: debugdiagnostics.h:47
#define DebugOutput(flags, formatString,...)
Definition: debugdiagnostics.h:162
@ DIAGNOSTIC
Diagnostic output, shows up if this group of output is activated. This is also the default.
@ HEADER
If set, header with line number and file name is added.
@ CRITICAL
Critical output, shows up if this group of output is activated.

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

// 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" };
Py_ssize_t i
Definition: abstract.h:645
PyObject * value
Definition: abstract.h:715
Definition: string.h:1237
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
#define DiagnosticVarOutput(...)
Definition: debugdiagnostics.h:176
const char const char * msg
Definition: object.h:438
// This example checks if the sub-functions succeeded.
// If not, debug messages are printed.
// perform task
maxon::Result<void> res = PerformSimpleTask();
// check for success
WarningOutput("Task could not be performed.");
// perform task
res = PeformCriticalTask();
// check for success
CriticalOutput("Critical Task could not be performed.");
Py_UCS4 * res
Definition: unicodeobject.h:1113
#define CriticalOutput(formatString,...)
Definition: debugdiagnostics.h:197
#define WarningOutput(formatString,...)
Definition: debugdiagnostics.h:186
static const ERROR_FAILED FAILED
Definition: resultbase.h:68

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
DebugStop("Task could not be performed.");
// perform task
res = PeformCriticalTask();
// check for success
CriticalStop("Critical Task could not be performed.");
#define DebugStop(...)
Definition: debugdiagnostics.h:225
#define CriticalStop(...)
Definition: debugdiagnostics.h:231

Asserts

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

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);
PyObject * error
Definition: codecs.h:206
maxon::Int32 Int32
Definition: ge_sys_math.h:56
#define CriticalAssert(condition,...)
Definition: debugdiagnostics.h:247
#define DebugAssert(condition,...)
Definition: debugdiagnostics.h:242

Further Reading