The API module identifies all entities by name. Different name spaces are provided for different purposes. In particular, the API module supports the current .mi language and, to some extent, its predecessor, which have a different name space concept. The current .mi module uses a shared global name space for all element types, while the old .mi format uses separate name spaces for each element type.
Note that shader parameter names do not use a persistent name space and have no assigned symbol table. Shader parameters are stored in declarations and are not accessible in any symbol table. There are also other short-lived sub-entities such as curves or surfaces that are not stored in symbol tables.
In general, symbol tables are used by the API module internally only. There is normally no need for another module to access specific symbol tables. However, API provides lookup functions for symbol tables that return the tag for individual named entities. This can be used for accessing the tessellated renderable representation of a geometric object, or for applying low-level scene access functions to entities created with API functions.
For example, the API module can be used to set up a small scene consisting of a single free-form surface object, which is then "rendered" using a render function that does not call any renderer, but uses the symbol table to find the object's tag, accesses the tessellated geometry, and displays a wireframe of the tessellation in a GUI window. This is a useful application of API because it visualizes the effects of user-defined approximation modes.
The following table lists the symbol tables. All symbol tables except the first three in the table below are used for old .mi syntax entities (bracketed by frame and end frame statements) only; all .mi entities except declarations are put into the global table instead. Current mental ray puts all scene entities into a single name space. For example, a material and an instance cannot both have the same name. Only declarations have a separate namespace because they are named after C/C++ shader names, which are not scene entities. This makes it possible to have shader parameters of type geometry that can be arbitrarily assigned any geometric scene entity, or instances that accept objects, lights, cameras, or groups without ambiguity.
| table | purpose |
|---|---|
| S_GLOBAL | all .mi2 entities |
| S_FUNCDECL | Function declarations ( declare statements) |
| S_VARIABLE | For internal use only |
| S_OPTIONS | Options ( options statements) |
| S_CAMERA | Cameras ( camera statements) |
| S_LIGHT | Lights ( light statements) |
| S_OBJECT | Geometric objects ( object statements) |
| S_INSTANCE | Instances ( instance statements) |
| S_INSTGROUP | Instance groups ( group statements) |
| S_MATERIAL | Materials ( material statements) |
| S_CTEXTURE | Color textures ( color texture statements) |
| S_STEXTURE | Scalar textures ( scalar texture statements) |
| S_VTEXTURE | Vector textures ( vector texture statements) |
API defines a number of specialized functions that perform lookups required during parsing:
miTag mi_api_name_lookup(
char * name)
Look up the element name in the scene element and function declaration symbol tables ( S_GLOBAL and S_FUNCDECL, and return the tag if found. Otherwise, return a null tag. Other symbol tables are not searched.
miTag mi_api_decl_lookup(
char * name)
Same thing but just for shader declarations. This is a separate function because if an object and a declaration have the same name (this is legal because they are in different name spaces), mi_api_name_lookup will never see the declaration and always return the other object.
miBoolean mi_api_variable_set(
char *name, /* variable name */
char *value) /* value or 0 to unset */
Set a variable name to a value value. If value is a null pointer, delete the variable. Variables can be redefined. The main purpose is to store meta-data in .mi scene files using the set command for variables such as author, translator, creation date, etc, whose values can be picked up by the client application or even a shader.
const char *mi_api_variable_lookup(
char *name) /* variable name */
Return the value of the variable name, as set with a preceding mi_api_variable_set. If the variable is not defined, a null pointer is returned. The returned string should not be modified or released.
const char *mi_api_tag_lookup(
miTag tag)
This is a reverse lookup function. Given a tag, it scans all symbol tables for an element with this tag and returns its name. This function is intended for printing more helpful error messages if only a tag is known, and to allow database dumps containing names. If the tag cannot be found, a null pointer is returned. A non-null pointer should not be modified or released, it points directly into the symbol table.
miTag mi_api_light_lookup(
char *name) /* instance to look up */
Deprecated Look up a light by name and return its tag. If no light by this name is found, return a null tag. This function is obsolete and supported only to access very old .mi scenes; use mi_api_name_lookup instead.
miTag mi_api_material_lookup(
char *name) /* material to look up */
Deprecated Look up a material by name and return its tag. If no material by this name is found, return a null tag. This function is obsolete and supported only to access very old .mi scenes; use mi_api_name_lookup instead.
miTag mi_api_texture_lookup(
char *name, /* texture to find */
int type) /* 0=col, 1=scal, 2=vec */
Deprecated Look up a texture by name and return its tag. If no texture by this name is found, return a null tag. type is the desired texture type: 0 for color textures, 1 for scalar textures, and 2 for vector textures. This function is obsolete and supported only to access very old .mi scenes; use mi_api_name_lookup instead.
miBoolean mi_api_surface_lookup(
char *name, /* name of face */
miTag *instance, /* instance with face */
miGeoIndex *idx) /* index of face */
Look up a surface by name and return its tag. If no surface by this name is found, return miFALSE, otherwise return miTRUE. This function can be used only while defining a geometric object group, between mi_object_group_begin and mi_object_group_end. Its purpose is finding surfaces to be connected for connection statements. The surface instance tag (not currently used) and the surface index (a sequential number beginning with 0 in every object that enumerates the surfaces in the object) are also returned.
void *mi_api_curve_lookup(
char *name, /* existing curve */
enum miCurve_type type, /* type of curve */
miBoolean newloop, /* is this a new loop */
miGeoRange *range, /* range of the curve */
int *no_scalars)
Look up a curve by name and type and return an identifying pointer. If no curve by this name is found, return a null pointer. The curve type is one of miCURVE_TRIM, miCURVE_HOLE, and miCURVE_SPECIAL, as defined by the SCENE module. This function is used when a surface references a curve as a trim, hole, or special curve with the given range. This function not only looks up the curve, but also creates a new curve reference entry containing the curve identifier, the type, whether this curve begins a new loop or continues an old one ( newloop), and the parameter range of the curve to use. The number of parameters of the curve is returned in * no_scalars. This function may only be used during the definition of a surface. Because of the side effects, this is not a true lookup function.
miTag mi_api_camera_end(void)
Complete the definition of the camera, after all parameters have been adjusted. If an error occurs, a null tag is returned; otherwise the tag of the new camera element is returned. The type of the returned element is miSCENE_CAMERA.
miBoolean mi_api_framebuffer_add(
miTag buffertag,
char *datatype,
char *filetype,
float *fileparams,
char *filename)
Define a standard frame buffer with optional file output, or
enable file output for a previously defined user frame buffer. The
buffertag argument should be the buffer tag of the
current camera. The datatype specifies the type of the
framebuffer (like "rgba_fb"). Optional
filetype is the file format of the output image file.
Optional fileparams give the list of parameters, an
array of 8 floats should be passed. The optional
filename provides the name of the file to which the
frame buffer image should be written to.
Note, that this function replaces the functions mi_api_output_file_parameter and mi_api_output_file_def functions used to attach file output to a frame buffer. It is provided for use with the C-style API in order to support compatibility with existing output and framebuffer handling in mental ray. It is not utilizing nor replacing the new Framebuffer API, which is recommended for new applications.
miBoolean mi_api_output_colorprofile(
char *cprof_name)
Deprecated Establish the named color profile for later use. The color profile is used to convert the color frame buffer to the requested color space while writing it to a file. The routine has to be called before mi_api_output_file_def is invoked. The transformation will only be performed if a color profile for the rendering color space has also been provided. The memory associated with the function parameter is released by the routine.
New applications are recommended to use the improved frame buffers and API for color profile support.
miTag mi_api_output_file_def(
miUint typemap, /* data type bitmap */
miUint interpmap, /* interp req bitmap */
char *format, /* file type string */
char *fname) /* file name */
Deprecated Define an output file and return an output function describing the file to write. The returned function has a special type code that tells mi_api_output_shaders to write a file instead of calling an output shader, and has the given format and file name encoded in its parameter area. It is not a normal shading function but can be treated as one by the caller, and can be appended to the camera's output function list.
When the output list is evaluated after rendering, this definition will write a frame buffer to the named file fname, using the file format format. Valid formats are extension strings such as "rgb" or "rla"; refer to the user's manual for a complete list. The typemap is a bitmap. Valid bit numbers are defined by the miImg_type enum as defined by the IMG module. Each bit informs the renderer that this shader requires a frame buffer of this type; at rendering time all active bitmaps (those defined in the camera used for rendering) are OR-ed. Only one bit should be set.
The interpmap bitmap uses the same pattern as typemap. It has a bit set if the frame buffer described by the corresponding set bit in typemap should be interpolated.
The new function mi_api_framebuffer_add should be used instead.
miBoolean mi_api_output_file_parameter(
miTag function, /* output file function */
miInteger code, /* parameter value code */
void *value) /* parameter value pointer */
Deprecated Supply one parameter value identified by its code to an output file function. The function tag identifies the output file function returned by a call to mi_api_output_file_def. The output file function is able to store 8 float parameter values. The code determines which one of these values will be changed. The actual meaning of a parameter value is not predefined and depends on the file format used. Currently, the miIMG_FORMAT_JPEG format interprets the first parameter value as compression quality.
The new function mi_api_framebuffer_add should be used instead.
miTag mi_api_output_function_def(
miUint typemap, /* data type bitmap */
miUint interpmap, /* interp req bitmap */
miTag function) /* output shader */
Define an output shader. Like output files, output shaders require a typemap. Unlike output files, output shaders may have multiple bits set. The function tag identifies the shader to be called. Shader tags are obtained during shader definition, they are returned by mi_api_function_call_end. The returned function tag can be appended to the camera's output function list by the caller.
The interpmap bitmap uses the same pattern as typemap. It has a bit set if the frame buffer described by the corresponding set bit in typemap should be interpolated.
miBoolean mi_api_output_file_override(
char *format,
char *fname)
Specify a file type and a file name that overrides the corresponding arguments of the next mi_api_output_file_def call. This call is not normally used to define a scene; it is intended for command-line option parsers that accept overrides for the file type and name specified in the scene. The override function must be called before the call to mi_api_output_file_def whose arguments should be overridden.
miBoolean mi_api_output_type_identify(
miUint *typemap, /* type bitmap */
miUint *interpmap, /* interp bitmap */
char *typename) /* data type */
This function converts a type string to a type map as required by the output file and output shader definition functions above. A type string is a comma-separated list of types, such as "rgba,n,contour". The special type contour is accepted also; it is the only one that is handled by RC only and not by IMG. All other types are identified in the same way as done by mi_img_type_identify. The type bitmap is returned in * typemap; the bits correspond to 1 shifted left by the miIMG_TYPE_* code.
Types can be prefixed with `+' or `-' to turn interpolation on or off for the frame buffer, respectively. Interpolation means that unsampled pixels get a value interpolated from its neighbors, rather than becoming a copy of one of its neighbors. Interpolation is on by default for all kinds of color frame buffers and off for all others. The interpolation bitmap is returned in * interpmap; the bit layout is the same as for * typemap.
miBoolean mi_api_output_imfdisp_handle(
miTag camera_tag) /* camera tag */
Deprecated This function should be
called after all output files have been defined. For every output
file in the camera's output list of camera specified by
camera_tag, a 128-byte file is created, containing the image
resolution and the gamma factor from the camera, as well as
information about how to open a socket to mental ray and version
information. This information is understood by programs such as
imf_disp which can connect to mental ray during rendering
and show the rendered image as it is being created. Note that
mental ray, when connected to in this way, will always transfer the
RGBA picture regardless of the type of the file used to establish
the connection.
mental ray does not require calling this function any more.
miBoolean mi_api_output_list(
miTag cam_tag) /* camera tag */
miTag opt_tag) /* options tag */
This function calls mi_phen_output_list, which collects all the type maps from the output list in the given camera and places appropriate frame buffer records into the options structure specified by tag. This function is no longer used; RC calls mi_phen_output_list directly after output shaders introduced by phenomena have been added. mi_api_output_list may be removed in a future version of mental ray because it doesn't take phenomena into account, which means it generates incomplete frame buffer lists.
miBoolean mi_api_output_shaders(
miTag cam_inst_tag, /* camera inst */
miTag opt_tag, /* options tag */
miTag *images) /* frame bufs */
Deprecated This function is obsolete since output shaders are called from mi_rc_render. Therefore it prints a warning and always returns miTRUE. The output list remains unchanged in the process.
miBoolean mi_api_framebuffer(
miOptions *opt, /* set framebuffer here */
int n, /* frame buffer 0..7 to set */
char *type) /* frame buffer type: "+rgba" etc */
This function sets or clears the definition of a user-defined frame buffer. There are up to eight user frame buffers numbered 0 through 7. Each can have an arbitrary user-defined type. The same types as for output statements are available, such as +rgba, -z, m, etc. As for output statements, "+" indicates sample interpolation and " -" indicates padding. If the type is a null pointer, the frame buffer is deleted from the options. Shaders can access these frame buffers with the mi_fb_get and mi_fb_put functions. There is no inherit limitation on the number of frame buffers in mental ray.
miTag mi_api_pass_save_def(
miUint typemap, /* data type bitmap */
miUint interpmap, /* interpolation req bitmap */
int max_samples, /* opt. max samples to write, or 0 */
char *out_fn) /* output pass file name */
The pass list in a camera is largely analogous to the output list, and uses similar functions. However, each statement is not concerned with writing pass files and calling preprocess or merge functions. This statement implements the pass write statement. Like output statements (and mi_api_output_*_def calls), the order is significant; each *_def call appends another statement to the script that is executed in order after rendering. Assuming that cam is a pointer of type miCamera, pass statements can be created with code like this:
cam->pass = mi_api_function_append(cam->pass, mi_api_pass_*_def(...));
The typemap defines which frame buffers should go into the pass file. It is used only to enable these frame buffers but does not exclude other rendered frame buffers from being written to the file; all rendered frame buffers will be written. The color and depth frame buffers are always rendered and written if there are pass statements. The interpmap specifies which frame buffers in the typemap should be interpolated (have the + sign in the type list in the pass statement).
The max_samples value controls the number of samples per pixel to write to the pass file. It is equivalent to the max_samples setting in the options, but allows resampling of the rendered image to write pass files with fewer samples than rendered. Specifying a higher sampling for the pass file than in the options is not useful. A value of 0 will use the max_samples setting from the options. Negative values are not allowed. Note that for the rasterizer, the rapid_collect_rate setting from the options is used instead.
Finally, out_fn is the name of the pass file to write.
miTag mi_api_pass_prep_def(
miUint typemap, /* data type bitmap */
miUint interpmap, /* interpolation req bitmap */
int max_samples, /* opt. max samples to write, or ~0 */
char *in_fn, /* input pass file name */
char *out_fn, /* output pass file name */
miTag function) /* pass preprocessing function */
This function defines a pass preprocessing function in the camera. The typemap, interpmap, and max_samples arguments are similar to mi_api_pass_save_def arguments. This function also specifies the pass file name in_fn to read from, the function to execute, and the pass file name out_fn to write to. The function must be a tag of a miFunction that is created like any other shader, using mi_api_function_call and related calls. A pass preprocessing function is a shader that has read access to a single pass file and write access to another single pass file, and can access any sample in random order by sample raster coordinate.
miTag mi_api_pass_merge_def(
miUint typemap, /* data type bitmap */
miUint interpmap, /* interpolation req bitmap */
int max_samples, /* opt. max samples to write, or 0 */
miDlist *in_fn_list, /* input pass file name list */
char *out_fn, /* output pass file name, or 0 */
miTag function) /* pass preprocessing function */
This function defines a pass merge function in the camera. The arguments are analogous to mi_api_pass_prep_def, except that the input file name is replaced with an input file name list, which is a dynamic list containing strings. Dynamic lists can be created with the mi_api_dlist_create (miDLIST_POINTER) and mi_api_dlist_add with a mi_mem_strdup'ed string. It is not necessary to release the dynamic list. Pass merge functions are shaders that have access to any number of input pass files, one output pass file, and only one sample coordinate at a time.
miTag mi_api_pass_delete_def(
char *fn) /* pass file name to delete */
This function defines a delete instruction in the camera. It simply deletes the file fn. This is useful to clean up temporary pass files after they have been preprocessed or merged, to avoid leaving very large files behind after rendering and pass processing finishes. Note that any file can be deleted with this statement, but it is not recommended to have a pass script consisting of a single delete instruction in order to delete, say, an unnecessary image file - the existence of any pass statement, even if it just a delete, will put mental ray into pass mode, which will enable an obligatory depth frame buffer and disable certain optimizations such as blank window rectangle elimination.
Copyright © 1986-2010 by mental images GmbH