mental ray shader language extensions

Naming guidelines

Attribute names and short names must be unique per node. For example, children of different compounds must not have the same name or short name.
Node type names and IDs must be unique.

Syntax extensions for Maya specials

You can provide additional parameters for each attribute on a node, and the node itself. Because there are no counterparts for these parameters in mental ray's scene description language, the Factory parser has been extended beyond the standard mental ray syntax to recognize certain keywords that can be given on a per attribute or per shader or phenomenon basis.

Add additional attributes with keywords

You can provide additional parameters for each attribute on a node, and the node itself by including keywords in the .mi declaration file.

These keywords must be prefixed with #: so that the declaration files are still accepted by the standard mental ray parser; these keywords are ignored by the standard mental ray parser (but not the Node Factory parser) because they are recognized as comments. Special comments in wrong places or syntactically wrong #: comments cause parse errors, which are written to the Script Editor.

Where to put keywords and what to write

Such #: comments can appear in two places: after a shader parameter or phenomenon parameter or in the requirement section of a declaration.

After a parameter, the following syntax is valid:
default scalar [scalar [scalar]] max scalar [scalar [scalar]] min scalar [scalar [scalar]] shortname "string" softmax scalar softmin scalar hidden boolean
In a declaration's requirement section, the following is syntactically correct:
nodeid integer

If none of these additional keywords are provided, the default is zero; the min/max and softmin/softmax are undefined; and the short name is uniquely assigned by counting attributes on nodes. Likewise unique node IDs are determined by counting nodes.

For attributes, not every keyword makes sense for every attribute type. The following is supported by Maya and thus by the Node Factory:

mental ray type	Maya type	default	min/max	soft min/max
boolean	boolean	0/1
color	float3	3 scalars
integer	long	1 integer	1 integer	1 integer
scalar	float	1 scalar	1 scalar	1 scalar
vector	float3	3 scalars	3 scalars

Short names

Short names can be given to every attribute. The Factory appends R,G,B to color children names/short names and X,Y,Z to vector children names/short names.

Example 1 (of 2):

declare shader
	vector					#: shortname "ov"
	"multiplyDivide" (
		integer		"operation",		#: default 1 min 0 max 2
		vector		"input1",		#: default 1. 1. 1.
		vector		"input2"		#: default 1. 1. 1.
		)
	#:
	#: nodeid 6894 # This is the node ID for binary Maya files.
	#:
	version 1
end declare

Example 2 (of 2):

declare shader
	struct {
		color		"outColor",		#: shortname "oc"
		scalar		"outAlpha"		#: shortname "oa"
	} "ramp" (
		array struct		"colorEntryList" {
			scalar		"position",
				#: default 1.
			color		"color"
				#: default 0.8 0.8 0.8
			},
			#: shortname "cel"			# compound's short name
		scalar		"uWave",
			#: shortname "uw"
			#: default 0.5
			#: softmin 1E-5 softmax 1
			#: min 1.0E-05 max 1
		scalar		"vWave",
		scalar		"noise",
		scalar		"noiseFreq",
		scalar		"hueNoise",
		scalar		"satNoise",
		scalar		"valNoise",
		scalar		"hueNoiseFreq",
		scalar		"satNoiseFreq",
		scalar		"valNoiseFreq",
		# Inherited from Texture2d
		vector		"uvCoord",
			#: shortname "uv"
		vector		"uvFilterSize",
		scalar		"filter",
		scalar		"filterOffset",
		boolean		"invert",
			#: default 0
		boolean		"alphaIsLuminance",
			#: default 1
		color		"colorGain",
			#: default 1.0 0.8 0.8
			#: min 0.1 0.1 0.1 max 0.5 0.5 0.5
		color		"colorOffset",
		scalar		"alphaGain",
			#: shortname "ag"
		scalar		"alphaOffset",
			#: shortname "ao"
		color		"defaultColor"
		)
	#:
	#: nodeid 6895 # Node ID for binary Maya files
	#:
	apply texture
	version	2
end declare

The Factory parser syntax vs. the mental ray parser syntax

Details about what the Factory parser does not accept, but mental ray's parser does:

Missing zeros before the dot in a scalar value are not supported. Instead of .5 you should write 0.5. Missing zeros after the decimal are supported, so 5. is acceptable.
There must be no comma after the last parameter in the input parameter list of a shader declaration. mental ray accepts

 declare shader
 			vector
 			"reverse" (
			vector "input",
			)
 end declare

The Factory parser reports a syntax error at the comma.

Hooks

The Factory creates Maya nodes from mental ray shader declarations. Once created, each such node represents a custom mental ray shader (a shader definition, to be precise). It can conveniently be used with various Maya scene entities.

Message attribute: The following mental ray shader parameter types are registered as message attribute by node factory: light, geometry, color texture, scalar texture, vector texture, lightprofile, shader.

Though it is possible to connect any node to these attributes (if you drag a node to the message attr in the Attribute editor, the message attribute of the source node is connected to the attribute. For example node1.message -> mrShaderNode.shader), you should make a proper connection. Otherwise, it may lead to crash or rendering abort.

The following are expected to be connected to each mental ray shader parameter type.

light : light transform node. For example, pointLight1.message -> dgs_material1.lights[0]
geometry : geometry shader. For example, mib_geo_sphere1.message -> mib_geo_instance1.object
shader : mental ray shader. For example, mib_illum_phong1.message -> mib_geo_instance.material
color texture, scalar texture, vector texture: mentalrayTexture node. For example, mentalrayTexture1.message -> mib_texture_lookup1.tex The button next to a color/scalar/vector texture attribute in the shader's attribute editor will create a new mentalrayTexture node, and connect it to the attribute.
lightprofile : mentalrayLightProfile node. For example, mentalrayLightProfile1.message -> mib_light_photometric.profile The button next to a lightprofile attribute in the shader's attribute editor will create a new mentalrayLightProfile node, and connect it to the attribute.
Materials

Custom materials may be specified in the shading group node. In the Attribute Editor, go to the mental ray section of the shading engine created along with this shader. Turn on Suppress all Maya shaders and connect the desired custom shaders to the corresponding attributes. The shading engine is now going to be exported as a mental ray material. You may still assign it to Maya objects in the usual ways.

Lights

You may specify a custom light shader in the mental ray section of any Maya point, spot or directional light. Turn on Suppress all Maya shaders and connect your light shader. On export, this overrides the default Maya shader while other properties of the light (orientation, spot cone angle, and so on) are preserved.

Cameras

Provide your own output, volume, lens, and environment shaders in the Attribute Editor’s mental ray section of any camera shape node. Currently you cannot specify more than one output shader.

Transforms

It is possible to override a shape node attached to a transform with a custom geometry shader. Just turn on Enable geometry shader in the mental ray section of Maya's transform nodes. Ideally, the transform node should have a single shape child.

Textures

The mental ray texture node should be used. mental ray Texture can be created from the Attribute Editor of a shader with “color texture, scalar texture, vector texture” parameter, and will be connected to the shader.