Parameter Types

The declaration gives the type and name of the shader to declare, which is the name of the C function and the name used when the shader is called, followed by a list of parameters with types. Names are normally quoted to disambiguate them from keywords reserved by mental ray. Commas separate parameter declarations. The following types are supported:

boolean

A boolean is either true or false. Possible values are true and false, or their synonyms on and off,

integer

Integers are numbers without decimal point in the range −2³¹…2³¹−1.

scalar

Scalars are floating-point numbers, defined as an optional minus sign, a sequence of digits containing an optional decimal point at any place, followed by an optional decimal exponent. A decimal exponent is the letter e or E followed by a positive or negative integer. Examples are 1.0, .5, 2., 1.e4, or −2.3e−6.

vector

A vector is a sequence of three scalars as defined above, describing the x, y, and z components of the vector.

transform

A transformation is a sequence of 16 scalars describing a 4×4 matrix, with the translation in the last row. The data structure consists of an array of 16 miScalars in row-major order. Many shaders check the last scalar and ignore the matrix if it is 0. In most cases the last scalar of a valid matrix is 1, and always nonzero.

color

A color is a sequence of three or four scalars as defined above, describing the red, blue, green, and alpha components of the color, in this order. If alpha is omitted, it defaults to 0.0.

spectrum

A spectrum describes electromagnetic radiation within a wavelength range associated with visible light. The contents of a spectrum data type are not directly accessible.

shader

Shader names defined with the shader statement (not to be confused with the shader declaration statement) can be passed to other shaders that have parameters of this type. The shader receives a tag that it can call using mi_call_shader and similar shader interface functions.

color texture

Color textures name a texture as defined by a color texture statement in the .mi file. The color texture statement names either a texture file, or a texture shader followed by a user parameter list. Note that a color texture does not name the texture shader directly. When a color texture is evaluated, it returns an RGBA color.

scalar texture

Scalar textures are equivalent to color textures, except that they name a scalar texture statement in the .mi file. When a scalar texture is evaluated, it returns a scalar (a single floating-point number). This is most often used to apply a texture map to a scalar material parameter such as transparency.

vector texture

Vector textures are another variation. They name a vector texture statement in the .mi file, which returns a vector when evaluated. Bump map bases on materials are typical applications for vector textures. Vector textures are rarely used.

light

Lights specify a light instance as defined by an instance statement in the .mi file, which in turn names a light. Despite the name, shader parameters of type light do not name the light directly because only the light's instance provides the necessary position and orientation information. Like textures, light parameters do not name light shaders directly.

string

Strings are quoted character strings of arbitrary length. The data type is a tag that can be converted by the shader to a character pointer using the mi_db_access and mi_db_unpin shader interface functions.

map

Map parameters reference a map data, which carries arbitrary data with positional information. Shaders access it much like user data. See section map data for details.

data

Data parameters reference a user data block, holding arbitrary structured or unstructured data of any kind. User data is useful for large amounts of shared scene data. Shaders access it much like strings. See section userdata for details.

lightprofile

Light profiles such as IES and Eulumdat are physical lamp description files supplied by lamp vendors. They can be used by shaders to determine the accurate amount of light emitted in a given direction. See section lightprofile for details.

geometry

Geometry references objects, groups, or instances. They are allowed for all types of shaders but are primarily useful for geometry shaders, which can introduce geometric scene entities. Geometry shaders have a different shader API than other shaders. They are described in chapter geoshaderapi. Shaders and phenomena whose return type is geometry can be used in instance definition statements (see page instance).

material

primarily useful in phenomenon definitions, which may contain materials in addition to shaders. Shaders and phenomena whose return type is material can be used in material definition statements (see page material).

struct { … }

Structures define sub-lists of parameters. This is normally used to build arrays of structures, for example to declare an array of textures, each of which comes with a blending factor and other sub-parameters. The ellipsis ... stands for another (non-empty) comma-separated sequence of type/parameter_name pairs.

array type

Arrays are different from all other types in that they are not named. The array keyword is a prefix to any of the above types that turns a single value into a one-dimensional array of values. For example, array scalar "terms" declares a parameter named terms that is an array of scalars. The number of elements in the array size is dynamic and unlimited. Arrays of arrays are not supported.

When choosing names, avoid periods and double colons, which have a special meaning when accessing interface parameters in phenomenon subshaders.

The return type of the shader must either be a simple type (any type except struct or array), or an unnamed struct containing only simple types. Unnamed means that there is no name between the struct keyword and the opening brace. This allows a shader to return multiple result values.

Note, it is important that all shaders are correctly defined with all return parameters, especially in case of a return structure. mental ray will use the size of the declared return parameters to reserve enough space internally when calling such a shader. This is critical for contour store shaders.