Macros | Typedefs | Functions
Message Logging API

Log management and operation. More...

Macros

#define __AI_FILE__   __FILE__
 
#define __AI_LINE__   __LINE__
 
#define __AI_FUNCTION__   __FUNCTION__
 

Typedefs

typedef void(* AtMsgCallBack) (int logmask, int severity, const char *msg_string, int tabs)
 Custom message callback, as passed to AiMsgSetCallback()
 
typedef void(* AtMsgExtendedCallBack) (int logmask, int severity, const char *msg_string, AtParamValueMap *metadata, void *user_ptr)
 

Functions

AI_API void AiMsgSetLogFileName (const char *filename)
 Enable writing messages to the specified log file. More...
 
AI_API void AiMsgSetLogFileFlags (int flags)
 Describe the type of messages that will be written to the log file. More...
 
AI_API void AiMsgSetConsoleFlags (int flags)
 Describe the type of messages that will be sent to stdout. More...
 
AI_API int AiMsgGetLogFileFlags ()
 Get the type of messages that will be written to the log file. More...
 
AI_API int AiMsgGetConsoleFlags ()
 Get the type of messages that will be written to the stdout. More...
 
AI_API void AiMsgSetMaxWarnings (int max_warnings)
 Set the maximum number of reported warnings. More...
 
AI_API void AiMsgSetCallback (AtMsgCallBack func)
 Change the logging callback function. More...
 
AI_API void AiMsgAddCallback (AtMsgCallBack func)
 Add an additional logging callback function. More...
 
AI_API void AiMsgResetCallback ()
 Reset the logging callback function to its default value. More...
 
AI_API unsigned int AiMsgRegisterCallback (AtMsgExtendedCallBack func, int mask, void *user_ptr)
 Add an additional logging callback function. More...
 
AI_API void AiMsgDeregisterCallback (unsigned int callback_id)
 Remove a previously registered logging callback function. More...
 
AI_API void AiMsgSetCallbackMask (unsigned int callback_id, int mask)
 Sets the mask of a previously registered logging callback function. More...
 
AI_API int AiMsgGetCallbackMask (unsigned int callback_id)
 Returns the mask of a previously registered logging callback function. More...
 
AI_API void AiMsgInfo (const char *format,...)
 Send an information message to the log. More...
 
AI_API void AiMsgDebug (const char *format,...)
 Send a debug message to the log. More...
 
AI_API void AiMsgWarning (const char *format,...)
 Send a warning message to the log. More...
 
AI_API void AiMsgError (const char *format,...)
 Send an error message to the log. More...
 
AI_API void AiMsgFatal (const char *format,...)
 Send a fatal error message to the log. More...
 
AI_API void AiMsgTab (int tabinc)
 Change the indentation of subsequent log messages. More...
 
AI_API size_t AiMsgUtilGetUsedMemory ()
 Memory used by this process in bytes. More...
 
AI_API uint32_t AiMsgUtilGetElapsedTime ()
 Elapsed time since AiBegin() More...
 

Severity Codes

#define AI_SEVERITY_INFO   0x00
 regular information message
 
#define AI_SEVERITY_WARNING   0x01
 warning message
 
#define AI_SEVERITY_ERROR   0x02
 error message
 
#define AI_SEVERITY_FATAL   0x03
 fatal error message
 

Logging Flags

#define AI_LOG_NONE   0x0000
 don't show any messages
 
#define AI_LOG_INFO   0x0001
 show all regular information messages
 
#define AI_LOG_WARNINGS   0x0002
 show warning messages
 
#define AI_LOG_ERRORS   0x0004
 show error messages
 
#define AI_LOG_DEBUG   0x0008
 show debug messages
 
#define AI_LOG_STATS   0x0010
 show detailed render statistics
 
#define AI_LOG_ASS_PARSE   0x0020
 show .ass-file parsing details
 
#define AI_LOG_PLUGINS   0x0040
 show details about plugins loaded
 
#define AI_LOG_PROGRESS   0x0080
 show progress messages at 5% increments while rendering
 
#define AI_LOG_NAN   0x0100
 show warnings for pixels with NaN's
 
#define AI_LOG_TIMESTAMP   0x0200
 prefix messages with a timestamp (elapsed time)
 
#define AI_LOG_BACKTRACE   0x0400
 show stack contents after abnormal program termination (SIGSEGV, etc)
 
#define AI_LOG_MEMORY   0x0800
 prefix messages with current memory usage
 
#define AI_LOG_COLOR   0x1000
 add colors to log messages based on severity
 
#define AI_LOG_ALL
 set all flags at once More...
 

Detailed Description

Log management and operation.

Macro Definition Documentation

#define AI_LOG_ALL
Value:
#define AI_LOG_STATS
show detailed render statistics
Definition: ai_msg.h:53
#define AI_LOG_DEBUG
show debug messages
Definition: ai_msg.h:52
#define AI_LOG_PROGRESS
show progress messages at 5% increments while rendering
Definition: ai_msg.h:56
#define AI_LOG_NAN
show warnings for pixels with NaN's
Definition: ai_msg.h:57
#define AI_LOG_ASS_PARSE
show .ass-file parsing details
Definition: ai_msg.h:54
#define AI_LOG_INFO
show all regular information messages
Definition: ai_msg.h:49
#define AI_LOG_TIMESTAMP
prefix messages with a timestamp (elapsed time)
Definition: ai_msg.h:58
#define AI_LOG_COLOR
add colors to log messages based on severity
Definition: ai_msg.h:61
#define AI_LOG_ERRORS
show error messages
Definition: ai_msg.h:51
#define AI_LOG_PLUGINS
show details about plugins loaded
Definition: ai_msg.h:55
#define AI_LOG_MEMORY
prefix messages with current memory usage
Definition: ai_msg.h:60
#define AI_LOG_WARNINGS
show warning messages
Definition: ai_msg.h:50
#define AI_LOG_BACKTRACE
show stack contents after abnormal program termination (SIGSEGV, etc)
Definition: ai_msg.h:59

set all flags at once

Function Documentation

AI_API void AiMsgSetLogFileName ( const char *  filename)

Enable writing messages to the specified log file.

The log file will record messages for the entire duration of the arnold session, i.e. until the arnold library is unloaded, or until AiMsgSetLogFileName is called again, which would close the previous log file before opening the new log file.

Parameters
filenameif a non-empty string, e.g. "arnold.log", a log file will be generated with this filename
AI_API void AiMsgSetLogFileFlags ( int  flags)

Describe the type of messages that will be written to the log file.

If this function is not called, the logging flags are set to AI_LOG_ALL by default.

Note that you can simultaneously send messages to the stdout console and to a log file, and that the messages can be filtered differently depending on where they are sent to.

Parameters
flagsa bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc
See also
AiMsgSetConsoleFlags
AI_API void AiMsgSetConsoleFlags ( int  flags)

Describe the type of messages that will be sent to stdout.

The default setting for console logging is AI_LOG_INFO | AI_LOG_WARNINGS | AI_LOG_ERRORS | AI_LOG_TIMESTAMP | AI_LOG_BACKTRACE | AI_LOG_MEMORY | AI_LOG_COLOR.

Parameters
flagsa bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc
AI_API int AiMsgGetLogFileFlags ( )

Get the type of messages that will be written to the log file.

Returns
a bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc
See also
AiMsgSetConsoleFlags
AI_API int AiMsgGetConsoleFlags ( )

Get the type of messages that will be written to the stdout.

Returns
a bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc
See also
AiMsgSetConsoleFlags
AI_API void AiMsgSetMaxWarnings ( int  max_warnings)

Set the maximum number of reported warnings.

This value applies to all forms of message processing: logfile, console and arbitrary callback. If this function is not called, the default value for the maximum number of warnings is 5.

Parameters
max_warningsmaximum number of warnings that will be reported
AI_API void AiMsgSetCallback ( AtMsgCallBack  func)

Change the logging callback function.

With this function, the user can bypass the default processing of log messages and replace it with a custom callback function. For example, a user may want to add a prefix to all messages, broadcast them over the network, or perform any other arbitrary action.

Parameters
funccallback function that will process log messages, or NULL to completely disable the processing of messages
AI_API void AiMsgAddCallback ( AtMsgCallBack  func)

Add an additional logging callback function.

With this function, the user can do their own processing of log messages while also keeping the default processing active.

Parameters
funccallback function that will process log messages
AI_API void AiMsgResetCallback ( )

Reset the logging callback function to its default value.

This function restores the default message callback that Arnold starts up with.

AI_API unsigned int AiMsgRegisterCallback ( AtMsgExtendedCallBack  func,
int  mask,
void *  user_ptr 
)

Add an additional logging callback function.

With this function, the user can do their own processing of log messages while also keeping the default processing active.

Parameters
funccallback function that will process log messages
funcdefines what log messages will be passed to the callback
user_ptra void pointer to pass to the register callback
Returns
the id of the registered callback, the user should not assume ids are sequential
AI_API void AiMsgDeregisterCallback ( unsigned int  callback_id)

Remove a previously registered logging callback function.

Parameters
callback_idthe id of the callback to be removed as returned by AiMsgRegisterCallback
AI_API void AiMsgSetCallbackMask ( unsigned int  callback_id,
int  mask 
)

Sets the mask of a previously registered logging callback function.

Parameters
callback_idthe id of the callback to modify as returned by AiMsgRegisterCallback
maskdefines what log messages will be passed to the callback
AI_API int AiMsgGetCallbackMask ( unsigned int  callback_id)

Returns the mask of a previously registered logging callback function.

Parameters
callback_idthe id of the callback as returned by AiMsgRegisterCallback
Returns
the log mask of the registered callback
AI_API void AiMsgInfo ( const char *  format,
  ... 
)

Send an information message to the log.

This is a variadic function. Use it just like you would use printf(). The formatted string will be appended to the log output (including a new line at the end). The message is tagged as AI_LOG_INFO.

Parameters
formatprintf-like format string
...printf-like variable argument list
AI_API void AiMsgDebug ( const char *  format,
  ... 
)

Send a debug message to the log.

This is similar to AiMsgInfo() but tags the message as AI_LOG_DEBUG. Debug messages will be ignored unless the AI_LOG_DEBUG flag is set.

Parameters
formatprintf-like format string
...printf-like variable argument list
AI_API void AiMsgWarning ( const char *  format,
  ... 
)

Send a warning message to the log.

This is similar to AiMsgInfo() but tags the message as AI_LOG_WARNINGS. The log system has a user-specified limit on the number of warnings that will be logged.

Parameters
formatprintf-like format string
...printf-like variable argument list
See also
MsgSetLogOptions
AI_API void AiMsgError ( const char *  format,
  ... 
)

Send an error message to the log.

This is similar to AiMsgInfo() but tags the message as AI_LOG_ERRORS. Error messages will signal the renderer to gracefully abort at the next scheduled checkpoint, e.g. when the current bucket is finished. This behaviour can be overridden with the global option abort_on_error.

Parameters
formatprintf-like format string
...printf-like variable argument list
AI_API void AiMsgFatal ( const char *  format,
  ... 
)

Send a fatal error message to the log.

This is similar to AiMsgError(), but the renderer will abort immediately and abruptly after logging the message.

Parameters
formatprintf-like format string
...printf-like variable argument list
AI_API void AiMsgTab ( int  tab_inc)

Change the indentation of subsequent log messages.

The indentation will be incremented or decremented by the specified number of tabs. The size of each tab is hardcoded to 1 space.

Parameters
tab_inctab increment, e.g. +1 or -1
AI_API size_t AiMsgUtilGetUsedMemory ( )

Memory used by this process in bytes.

Returns
the total number of memory bytes used by this process
AI_API uint32_t AiMsgUtilGetElapsedTime ( )

Elapsed time since AiBegin()

Returns
the elapsed time (in milliseconds) since the last call to AiBegin()

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com