.mi Translator (MI)

mi_mi_parse
mi_mi_parse_rayrc

.mi Translator (MI)

The .mi translator translates a file containing a scene in .mi format to an in-core scene representation. After every complete frame read, the control is passed so that the scene can be rendered. For information on the .mi file, see book1 of this series, Rendering with mental ray [Driemeyer 05].

mi_mi_parse

void mi_mi_parse(
    char * const    mifilename,
    miBoolean       resume,
    char * const    incl_path,
    char * const    file_name,
    char * const    file_type,
    int             (*getc_callback)(FILE *),
    miBoolean       verbose,
    miBoolean       (*frame_callback)(miTag root_group,
                                      miTag camera_inst,
                                      miTag camera,
                                      miTag options,
                                      miInh_func inheritance_func))

This function is the mainline of the MI module. It reads and parses an mi scene file, and either calls a given frame callback for every completed frame it finds, or returns to the caller after every completed frame.

mifilename: The path of the .mi file to parse. If it is a null pointer, stdin is parsed instead and no file is opened. The resulting file pointer of type FILE *, either for the open file or stdin, is passed to the getc callback for every character to read (see below).
resume: If set to miTRUE a previous run of the parser is resumed after mi_mi_parse had returned to the caller. The value of mifilename is ignored in that case.
incl_path: Specifies an optional directory path where include files loaded with the $include statement can be found. The include path is prepended to the given include file name if it is enclosed in angle brackets. It is not used if the name is enclosed in double quotes.
file_name: A path that overrides the output file path given in the first file output statement. This is used to implement the -o command-line option of the mental ray executable.
file_type: An extension name that overrides the output file type given in the first file output statement. This is used to implement the -type command-line option of the mental ray executable. Examples for types are rgb or jpg.
getc_callback: The function specified by this parameter is called for every character to be read from the file specified by the mifilename argument or stdin. It is not used for header files included with $include statements; for these getc is used. The callback should return a single character, or EOF (as defined in stdio.h) for end-of-file.
verbose: If this flag is set, verbose statements in the .mi file are ignored. The mental ray executable uses this to disable verbose statements in the mi file if the -verbose command-line option is used.
frame_callback: This argument controls what happens when the mi parser finds a render statement at the end of a frame definition. If set to 0, mi_mi_parse returns. If the return value is miTRUE, the caller is then expected to call mi_api_render_params and mi_rc_run to render the frame, and then to call mi_mi_parse with a render argument set to miTRUE to proceed with the next frame. This is the recommended procedure. It is also possible to pass the address of a render callback, which is then called by mi_mi_parse when it finds a render statement. The arguments are similar to what mi_api_render_params provides. The callback should then render the scene, and return miTRUE on success or miFALSE on error. If miFALSE is returned, mi_mi_parse aborts parsing and also returns miFALSE.

mi_mi_parse_rayrc

void mi_mi_parse_rayrc(
    char * const    incl_path,
    miBoolean       verbose)

This function finds and loads the rayrc startup initialization file (ray3rc before rayrc). It is typically called once before creating a scene in the scene database with mi_mi_parse or explicit mi_api_* calls.

incl_path: An optional directory path where the rayrc file itself, and include files loaded with $include statements in the mi file (if mi_mi_parse is used) can be found.
verbose: If this flag is set, verbose statements in the .mi file are ignored. It should be set if there was a -verbose option on the command line, which should override verbose statements in the .mi file.