Messages and Errors

Shaders may print messages and errors. They are printed in the same format as rendering (RC) messages. Options given to the translator determine which messages are printed and which are suppressed. All message routines have the same parameters as printf(3). All append a newline to the message. Messages are printed in the form

   RC host.thread level: message

with the module name, e.g. RC, 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. In a networked environment, the messages of slaves are usually transferred to the master rendering host and printed in the order they were received. Messages resulting from connection problems and those that were dropped to avoid a network overload may be found in a local file (/tmp/raylib.log). Newlines in the message are replaced with blanks.

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

An unrecoverable error has occurred. Unlike all others, this call will not return; it will attempt to recover mental ray and return to the top-level translator. Recovering may involve aborting all operations in progress and clearing the entire database. Fatal messages can be suppressed, but mental ray is always exited. This function should never be used in a shader because it may also exit any application that mental ray is embedded in, without giving the user a chance to save his work!

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

An unrecoverable error has occurred. The caller then aborts the current operation gracefully and returns.

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; do not print information for every intersection point or shader call except during debugging, especially on Windows NT 4.x with its slow and nonparallel I/O system.

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 useful only for shader development.

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

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

Note that all these functions incur some runtime overhead even if the verbosity level is set such that no message is printed. It is often a good idea to enclose shader debugging messages that occur frequently in ifdef DEBUG statements to make sure they are omitted in production versions of the shader.

Copyright © 1986-2010 by mental images GmbH