mental ray shader language extensions

 
 
 

Naming guidelines

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:

 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.