Phenomenon Interface Parameters

Phenomena, like shaders, have parameters. In the phenomenon case they are called "interface parameters" because they form the gateway between the rest of the scene and the internal implementation of the phenomenon. Interface parameters are what makes the phenomenon look like a simple shader to the named and anonymous shader definitions. Phenomena are implemented in terms of subshader nodes, each with their own parameters. Subshader parameters can be assigned from the interface using an assignment of the following form:

"parameter_name" = interface "ifname"

This looks similar to the shader assignments described above, but when the shader calls mi_eval on a parameter assigned to the interface of the phenomenon it is defined in, no shader is called but the value is obtained from the phenomenon interface. For example:

declare shader 
   color "phong" (color "ambient",
                  color "diffuse",
                  color "specular")
   version 1
end declare

declare phenomenon
   color "phong_phen" (color "col")
   version 1

   shader "sub" "phong" (
       "ambient"   0.3 0.3 0.3,
       "diffuse"   = interface "col",
       "specular"  1.0 1.0 1.0)

   root = "sub"
end declare

shader "mtlsh" "phong_phen" (
   "col"   1.0 0.5 0.0)

For the shader definition, the phenomenon phong_phen looks like a shader with a single color parameter col. Internally, it contains the definition of a simple shader sub with three parameters, two of which have constant values and one which takes its value from the interface. When the shader definition mtlsh is called from a material or elsewhere in the scene, it calls the phenomenon phong_phen with the value 1.0 0.5 0.0 for the interface parameter col. This value is propagated to the diffuse parameter of the shader sub during evaluation of the phenomenon.

It is important to distinguish parameter values, such as 1.0 1.0 1.0 for specular, from shader assignments, which begin with an "=" sign. In particular, consider the shader parameter type shader: if a shader name is given as the value without "=" sign, the named shader will be returned but not called by mi_eval. With an "=" sign, mi_eval will call the shader and expect it to return another shader (so its return value must have type shader) which is then returned by mi_eval. The latter involves an indirection, and is not often used for parameters of type shader. This is a common mistake, and return type mismatches will result in mental ray warning messages.

When calling a phenomenon, all its parameters must pass through the interface. The shader sub and everything else defined inside the phenomenon block is visible only inside the phenomenon, and no names defined outside the phenomenon are visible to definitions inside the phenomenon. The interface is the only connection point between the inner and outer world. This encapsulation ensures the integrity and completeness of phenomena independently of the scene they are used in.

Phenomena may also contain material, light, and instance definitions in addition to shader definitions.

By convention, anonymous shader definitions should not be used in phenomenon declarations. There is no functional disadvantage in using anonymous shader definitions but it makes life difficult for graphical phenomenon editing tools like mental ray' Phenomenon Creator^™, which uses shader names to label the icons and boxes that represent subshaders in its graph and browser views.

The return type of a phenomenon may be any type that is a valid return type for a shader.