Scopes disambiguate name spaces. The current scope is defined by a string that is prepended to all toplevel element names (objects, materials, lights, functions, declarations, etc) passed to API. Non-toplevel entities such as surfaces, curves, and shader parameters whose lifetime are limited to the enclosing toplevel element are not scoped. The scope string is initially empty. Scopes can be nested. Scopes in the scope string are separated by double colons; the scope string "a::b::" is the result of first beginning scope "a" and then scope "b". If applied to a name "x", the resulting name is "a::b::x". Since symbol tables contain scoped names, this can be used to distinguish different "x".

For example, mi_api_phen_begin automatically begins a new scope with the phenomenon name. This causes the phenomenon name and a double colon to be prepended to all shaders defined inside the phenomenon, which allows different phenomena to have subshaders with the same name. If phenomena " phen1" and "phen2" both have a subshader "shader", no conflict arises because their internal names are "phen1::shader" and " phen2::shader". The scoping functions are available to other modules, for example to allow the shader editor to read a declaration file without causing conflicts with the loaded scene. The name of the declared phenomenon itself, like the name of any other declaration, is global and does not get a scope prepended.

Every context has its own scope string (see LIB module about contexts).

miBoolean mi_api_scope_begin(
    char             *name)    /* new scope name */

Enter a scope. The given name and two colons (in this order) are appended to the scope string.

miBoolean mi_api_scope_end(void)

Exit a scope. The last name and double colon is stripped off the scope string.

char *mi_api_scope_apply(
    char             *name)   /* name to put in scope */

Prepend the scope string to name, if any. If name contains double colons, check the scope part of name against the scope, and return a null pointer if the check fails. For example, it is an error for name to contain double colons if there is no scope; assuming that the scope is "a::b::", the names "x", "b::x", and "a::b::x" are all ok and return the same string "a::b::x" but " a::x" is an error. As usual, name must have been allocated using MEM functions. The returned string is allocated with MEM and may be identical to name.

The following functions accept char* arguments that are passed through mi_api_scope_apply automatically by API:

mi_api_delete mi_api_delete_tree mi_api_options_begin
mi_api_camera_begin mi_api_render mi_api_light_begin
mi_api_light_lookup mi_api_material_begin mi_api_material_lookup
mi_api_texture_begin mi_api_texture_lookup mi_api_instance_begin
mi_api_instance_end mi_api_instgroup_begin mi_api_instgroup_additem
mi_api_object_begin mi_api_poly_begin mi_api_surface_begin (material name only)
mi_api_function_assign mi_api_function_call mi_api_parameter_shader
mi_api_shader_add mi_api_shader_call

Copyright © 1986-2011 by mental images GmbH