Log management and operation. More...

Macros
#define	__AI_FILE__ __FILE__

#define	__AI_LINE__ __LINE__

#define	__AI_FUNCTION__ __FUNCTION__

Logging Flags
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)
	Custom message callback, as passed to AiMsgRegisterCallback() More...

AI_API void	AiMsgSetLogFileName (const char *filename)
	Enable writing messages to the specified log file. More...

AI_API void	AiMsgSetLogFileFlags (const AtUniverse *universe, int flags)
	Set the mask for what types of messages from the specified universe can be written to the log file. More...

AI_API void	AiMsgSetConsoleFlags (const AtUniverse *universe, int flags)
	Set the mask for what types of messages from the specified universe can be written to `stdout`. More...

AI_API int	AiMsgGetLogFileFlags (const AtUniverse *universe)
	Get the type of messages that will be written to the log file for a given universe. More...

AI_API int	AiMsgGetConsoleFlags (const AtUniverse *universe)
	Get the type of messages that will be written to the `stdout` for a given universe. More...

AI_API void	AiMsgSetMaxWarnings (int max_warnings)
	Set the maximum number of reported warnings. More...

AI_API AI_DEPRECATED void	AiMsgSetCallback (AtMsgCallBack func)
	Change the logging callback function. More...

AI_API AI_DEPRECATED void	AiMsgAddCallback (AtMsgCallBack func)
	Add an additional logging callback function. More...

AI_API AI_DEPRECATED 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...

AI_API void	AiMsgSystemInfo (const AtUniverse *universe)
	Output system information to the log. More...

#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_STATUS 0x2000
	flag associated with messages reporting overall status

#define	AI_LOG_ALL
	set all flags at once (except AI_LOG_STATUS, since status messages use the logging callback mechanism but are not intended to appear in the log) 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

Detailed Description

Log management and operation.

Macro Definition Documentation

◆ AI_LOG_ALL

#define AI_LOG_ALL

Value:

 ( AI_LOG_INFO       | AI_LOG_WARNINGS   | AI_LOG_ERRORS    | \
   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      )

set all flags at once (except AI_LOG_STATUS, since status messages use the logging callback mechanism but are not intended to appear in the log)

Typedef Documentation

◆ AtMsgExtendedCallBack

typedef void(* AtMsgExtendedCallBack) (int logmask, int severity, const char *msg_string, AtParamValueMap *metadata, void *user_ptr)

Custom message callback, as passed to AiMsgRegisterCallback()

The following items will be passed to the callback through the metadata list:

Name	Type	Description
universe	Universe*	Universe this log message refers to

Function Documentation

◆ AiMsgSetLogFileName()

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

filename if a non-empty string, e.g. "arnold.log", a log file will be generated with this filename

◆ AiMsgSetLogFileFlags()

AI_API void AiMsgSetLogFileFlags	(	const AtUniverse *	universe,
		int	flags
	)

Set the mask for what types of messages from the specified universe can be written to the log file.

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

Note that generic log messages that are not intended for a specific universe will be sent to the default universe.

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

universe	universe to apply these flags (NULL for default universe)
flags	a bitmask of logging flags, i.e. a logical sum of `AI_LOG_INFO`, `AI_LOG_STATS`, etc

See also: AiMsgSetConsoleFlags

◆ AiMsgSetConsoleFlags()

AI_API void AiMsgSetConsoleFlags	(	const AtUniverse *	universe,
		int	flags
	)

Set the mask for what types of messages from the specified universe can be written to stdout.

The default setting for console logging is AI_LOG_ALL

Note that generic log messages that are not intended for a specific universe will be sent to the default universe.

Parameters

universe	universe to apply these flags (NULL for default universe)
flags	a bitmask of logging flags, i.e. a logical sum of

◆ AiMsgGetLogFileFlags()

AI_API int AiMsgGetLogFileFlags ( const AtUniverse * universe )

Get the type of messages that will be written to the log file for a given universe.

Parameters

universe universe to get these flags (NULL for default universe)

Returns: a bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc

See also: AiMsgSetConsoleFlags

◆ AiMsgGetConsoleFlags()

AI_API int AiMsgGetConsoleFlags ( const AtUniverse * universe )

Get the type of messages that will be written to the stdout for a given universe.

Parameters

universe universe to get these flags (NULL for default universe)

Returns: a bitmask of logging flags, i.e. a logical sum of AI_LOG_INFO, AI_LOG_STATS, etc

See also: AiMsgSetConsoleFlags

◆ AiMsgSetMaxWarnings()

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_warnings maximum number of warnings that will be reported

◆ AiMsgSetCallback()

AI_API AI_DEPRECATED void AiMsgSetCallback ( AtMsgCallBack func )

Change the logging callback function.

Deprecated : please use AiMsgRegisterCallback instead.

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

func	callback function that will process log messages, or NULL to completely disable the processing of messages

◆ AiMsgAddCallback()

AI_API AI_DEPRECATED void AiMsgAddCallback ( AtMsgCallBack func )

Add an additional logging callback function.

Deprecated : please use AiMsgRegisterCallback instead.

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

Parameters

func	callback function that will process log messages

◆ AiMsgResetCallback()

AI_API AI_DEPRECATED void AiMsgResetCallback ( )

Reset the logging callback function to its default value.

Deprecated : please use AiMsgDeregisterCallback instead.

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

◆ AiMsgRegisterCallback()

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

func	callback function that will process log messages
func	defines what log messages will be passed to the callback
user_ptr	a void pointer to pass to the register callback

Returns: the id of the registered callback, the user should not assume ids are sequential

◆ AiMsgDeregisterCallback()

AI_API void AiMsgDeregisterCallback ( unsigned int callback_id )

Remove a previously registered logging callback function.

Parameters

callback_id the id of the callback to be removed as returned by AiMsgRegisterCallback

◆ AiMsgSetCallbackMask()

AI_API void AiMsgSetCallbackMask	(	unsigned int	callback_id,
		int	mask
	)

Sets the mask of a previously registered logging callback function.

Parameters

callback_id	the id of the callback to modify as returned by AiMsgRegisterCallback
mask	defines what log messages will be passed to the callback

◆ AiMsgGetCallbackMask()

AI_API int AiMsgGetCallbackMask ( unsigned int callback_id )

Returns the mask of a previously registered logging callback function.

Parameters

callback_id the id of the callback as returned by AiMsgRegisterCallback

Returns: the log mask of the registered callback

◆ AiMsgInfo()

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

format	printf-like format string
...	printf-like variable argument list

◆ AiMsgDebug()

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

format	printf-like format string
...	printf-like variable argument list

◆ AiMsgWarning()

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

format	printf-like format string
...	printf-like variable argument list

See also: MsgSetLogOptions

◆ AiMsgError()

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

format	printf-like format string
...	printf-like variable argument list

◆ AiMsgFatal()

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

format	printf-like format string
...	printf-like variable argument list

◆ AiMsgTab()

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_inc tab increment, e.g. +1 or -1

◆ AiMsgUtilGetUsedMemory()

AI_API size_t AiMsgUtilGetUsedMemory ( )

Memory used by this process in bytes.

Returns: the total number of memory bytes used by this process

◆ AiMsgUtilGetElapsedTime()

AI_API uint32_t AiMsgUtilGetElapsedTime ( )

Elapsed time since AiBegin()

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

◆ AiMsgSystemInfo()

AI_API void AiMsgSystemInfo ( const AtUniverse * universe )

Output system information to the log.

This function outputs information such as version number, operating system, free memory etc. The message is tagged as AI_LOG_INFO.

Parameters

universe universe logging flags to be applied (NULL for default universe)

Macros

Logging Flags

Severity Codes

Detailed Description

Macro Definition Documentation

◆ AI_LOG_ALL

Typedef Documentation

◆ AtMsgExtendedCallBack

Function Documentation

◆ AiMsgSetLogFileName()

◆ AiMsgSetLogFileFlags()

◆ AiMsgSetConsoleFlags()

◆ AiMsgGetLogFileFlags()

◆ AiMsgGetConsoleFlags()

◆ AiMsgSetMaxWarnings()

◆ AiMsgSetCallback()

◆ AiMsgAddCallback()

◆ AiMsgResetCallback()

◆ AiMsgRegisterCallback()

◆ AiMsgDeregisterCallback()

◆ AiMsgSetCallbackMask()

◆ AiMsgGetCallbackMask()

◆ AiMsgInfo()

◆ AiMsgDebug()

◆ AiMsgWarning()

◆ AiMsgError()

◆ AiMsgFatal()

◆ AiMsgTab()

◆ AiMsgUtilGetUsedMemory()

◆ AiMsgUtilGetElapsedTime()

◆ AiMsgSystemInfo()