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:
Copyright © 1986-2009 by mental images GmbH