Errors and Messages

Errors are grouped by severity. There are six levels, each with its own printing routine. The parameters are the same as for printf. The message is printed in the form

module host.thread level: message

with the module name module, the host number host if available, the thread number thread with a leading dot if available, the message type level (fatal, error, warning etc), and the message given in the function call. Host and thread numbers are not available before and during initialization of the PAR and MSG modules. Host 0 is the master host, thread 0 is the master thread. Network threads are printed as .net.

Some of the following routines may be implemented as macros.

mi_set_verbosity

void mi_set_verbosity(
    const int       level)

Set the verbosity level bitmap. This bitmap controls which of the message-printing functions listed below will print messages and which will be ignored. The following level flags are available:

`miERR_NONE`	Print no messages at all (null bitmap).
`miERR_DEFAULT`	Print fatal, error, and warning messages.
`miERR_FATAL`	If set, print fatal messages.
`miERR_ERROR`	If set, print error messages.
`miERR_WARNING`	If set, print warnings.
`miERR_INFO`	If set, print infos.
`miERR_PROGRESS`	If set, print progress reports.
`miERR_DEBUG`	If set, print debug messages.
`miERR_VDEBUG`	If set, print verbose debug messages.

Note that this bitmap is not what users use in the mi scene file or on the mental ray command line, where a number between 0 and 7 is expected. To convert from a number n to a bitmap, use (1<<n)-1.

mi_get_verbosity

int mi_get_verbosity(void)

Return the current verbosity bitmap, as set by default or with mi_set_verbosity.

mi_set_subverbosity

void mi_set_subverbosity(
    const miModule  mod,
    const miUint    bitmap)

Set the message bitmap for the given module, or all modules if mod is miM_NULL. The bitmap is unrelated to the bitmap used by mi_set_verbosity. It can be retrieved by modules with mi_get_subverbosity to decide which classes of messages to print. The lower 24 bits of bitmap are predefined and valid for all modules; the upper 8 bits are reserved for module-specific classes. The following classes are predefined:

`miMSG_NONE`	No messages.
`miMSG_DEF`	Default messages. The LIB modules initializes all bitmaps with this value on startup.
`miMSG_ALL`	All classes, including the reserved classes.
`miMSG_PHASE`	Phase messages, such as ``begin tessellation.''
`miMSG_PROGRESS`	Progress messages, such as number of lines parsed or percentage of the job finished.
`miMSG_VPROGRESS`	Verbose progress messages, such as per-task percentages of the job finished.
`miMSG_RUNTIME`	Wallclock and CPU user time reports.
`miMSG_SCENE`	Scene statistics, such as the number of triangles or BSP tree statistics.
`miMSG_MEMORY`	Memory usage statistics.
`miMSG_RENDER`	Standard rendering statistics, such as the number of rays cast.
`miMSG_VRENDER`	Verbose rendering statistics, such as shader call counts or cache statistics.
`miMSG_RESOURCES`	Internal resource usage, such as number of task queues and tasks used, message passing statistics, or DB access statistics.
`miMSG_NETWORK`	Low-level networking statistics.
`miMSG_FILES`	File read/write statistics, reports all files being accessed and any path substitutions performed.
`miMSG_DEBUG`	Generic debugging messages. This class and the following can be used for modules that only support one or two types of debug messages. This avoids the need to define module-specific classes.

mi_get_subverbosity

void mi_get_subverbosity(
    const miModule  mod)

Retrieve the message bitmap for the given module. This is used by modules to find out which messages to print.

mi_errorhandler

void mi_errorhandler(
    void    (*const handler)(const int         errmask,
                             const char *const fullmsg,
                             const char *const rawmsg,
                             const int         code))

If a message of any class (fatal, error, warning, info, progress, debug, or vdebug) is printed, call the named function with four parameters: the error level bitmap with exactly one of the miERR_* bits set; the full message with module, host, thread, and level information; the raw message without this information, and a code number that identifies the error or warning. No newline is appended to either message. This handler routine is called only for levels allowed by mi_set_verbosity (default is fatals, errors, and warnings). The default printing routine prints the full message to stderr, followed by a newline.

The code number consists of six decimal digits: two for the module number (one of miM_*), one for the severity level (0 for fatal, 1 for error, 2 for warning), and three that are either 0 or uniquely identify the error or warning message. The last three digits are 0 for messages that have not yet been assigned an unique error code, such as messages printed by shaders. The last three digits are shared by fatal and error messages (no two have the same), but a warning may use the same trailing three-digit code as either an error or a fatal. The code number is the number that is printed to stderr. Once assigned, mental ray will keep these code numbers, but if a message is dropped from raylib its number will be recycled for future new messages.

This function can be used to print messages into an application error log, or pop up dialog boxes etc.

mi_fatal_handler

void mi_fatal_handler(
    void    (*const handler)(const int code))

If an unrecoverable error occurs in ray, exit() is normally called, after printing a diagnostic message. This handler allows the application to intercept the exit() call, and do some error recovery of its own. Control may not be returned to ray when this handler is called.

mi_fatal

void mi_fatal(
    const char *const message, ...)

An unrecoverable error has occurred. Unlike all others, this call will not return. The messages printed by this and the following six functions may be suppressed with appropriate mi_set_verbosity calls.

mi_error

void mi_error(const char *const message, ...)

An unrecoverable error has occurred. This call returns; the caller should abort the current operation gracefully and return.

mi_warning

void mi_warning(
    const char *const message, ...)

A recoverable error occurred. The current operation proceeds.

mi_info

void mi_info(
    const char *const message, ...)

Prints information about the current operation, such as the number of triangles and timing information. Infos should be used sparingly; don't print information for every object or surface tessellated.

mi_progress

void mi_progress(
    const char *const message, ...)

Prints progress reports, such as rendering percentages.

mi_debug

void mi_debug(
    const char *const message, ...)

Prints debugging information. This level might be unavailable in production versions.

mi_vdebug

void mi_vdebug(
    const char *const message, ...)

Prints more debugging information useful only for implementors. Messages that are likely to be useful only in rare circumstances, or that generate a very large number of lines should be printed with mi_vdebug.

mi_set_colormessage

void mi_set_colormessage(
    const miBoolean)

If the color message mode is set to miTRUE, then messages are prefixed and postfixed with ISO color escape sequences on Unix platforms. For Windows platforms, if message output is to the console then the console color is changed programmatically. The following messages are affected: fatal, error, warning, debug and vdebug. The color assignment is fixed and cannot be changed. The color messages are disabled by default. The message string passed to the message callback does not contain color escape sequences.