Macros | Typedefs | Functions
Message Logging API

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()
 

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 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 AiMsgResetCallback ()
 Reset the logging callback function to its default value. 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 AtUInt64 AiMsgUtilGetUsedMemory ()
 Memory used by this process in bytes. More...
 
AI_API AtUInt32 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_SSS   0x2000
 show messages about sub-surface scattering pointclouds
 
#define AI_LOG_ALL
 set all flags at once More...
 

Detailed Description

Macro Definition Documentation

#define AI_LOG_ALL
Value:
AI_LOG_DEBUG | AI_LOG_STATS | AI_LOG_PLUGINS | \
AI_LOG_PROGRESS | AI_LOG_NAN | AI_LOG_ASS_PARSE | \
AI_LOG_TIMESTAMP | AI_LOG_BACKTRACE | AI_LOG_MEMORY | \
AI_LOG_COLOR | AI_LOG_SSS)

set all flags at once

Function Documentation

AI_API void AiMsgSetLogFileName ( const char *  filename)

Enable writing messages to the specified log file.

To generate a log file, call this function once immediately after AiBegin(). Successive attempts to call this function will be ignored. The log file will record messages for the entire duration of the render session, i.e. until AiEnd().

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_NONE.

Parameters
flagsa bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc
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 100.

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 AiMsgResetCallback ( )

Reset the logging callback function to its default value.

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

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
AiMsgSetLogOptions
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 AtUInt64 AiMsgUtilGetUsedMemory ( )

Memory used by this process in bytes.

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

Elapsed time since AiBegin()

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

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com