Custom vertex data

For polygon meshes, mental ray for Maya checks for additional custom attributes with the fixed prefix "miCustomTex".

All characters after this prefix are considered the custom data's name, for example MyData for the attribute name "miCustomTexMyData". These data attributes are recognized and translated to additional mental ray texture spaces if they meet the following requirements:

their type is one of (in MEL):
- Int32Array
- doubleArray
- vectorArray
- pointArray
respectively (in Maya API):
- MFnIntArrayData
- MFnDoubleArrayData
- MFnVectorArrayData
- MFnPointArrayData
the number of array data elements exactly matches the number of vertices in the mesh object

These array attributes can be created either by MEL or the Maya API. They should contain values when processing starts, otherwise they are ignored.

The data elements of the array attribute is attached to the mesh vertices in the presented order. According to the data type, they occupy one or more texture spaces in mental ray. This implies a data type conversion to floating point format in any case. It also ensures that the vertex data are automatically be interpolated for the current intersection point on a triangle.

Maya type	number of elements	mental ray texture access
int	1	tex_list[i].x
double	1	tex_list[i].x
vector	3	tex_list[i].x, tex_list[i].y, tex_list[i].z
point	4	tex_list[i].x, tex_list[i].y, tex_list[i].z, tex_list[i+1].x

The information about the texture space that is actually used for a certain custom array is still missing. In the current mental ray for Maya, exactly one texture space is reserved for texturing by default. But meshes can hold more than one UV space. Therefore, all custom vertex data start at an arbitrary texture space offset. If more than one custom array is attached to a mesh, the order of the attributes as listed on the node determines the texture space sequence in mental ray.

This actual layout of the data needs to be supplied to the shaders that want to make use of it. Two ways are currently implemented: user data and custom text replacement. The user data approach attaches a user data block to the mesh object in mental ray. This can be retrieved in shaders. The declaration of the data block maya_vertexdata is contained in the mayabase.mi declaration file.

If custom text is applied to the material of the mesh, a special placeholder syntax allows convenient parameter value assignment. The following placeholders are supported (examples assume custom data of type vector with name "MyData" found as first custom attribute):

placeholder	replaced by	example
$<name>	texture space index	$MyData -> 1
$<name>Offset	texture space index	$MyDataOffset -> 1
$<name>Size	number of used texture components	$MyDataSize -> 3
$<name>Type	custom data type, 1 - int, 2 - double, 3 - vector, 4 - point	$MyDataType -> 3

Note

The placeholders are case sensitive. The use of the special dollar sign ($) for other than the placeholder names should be avoided.

Example

This is a complete example of custom vertex data and a custom text shader connected to a mesh with the following custom attributes:

miCustomTexMyInt (Int32Array),
miCustomTexMyDouble (doubleArray),
miCustomTexMyVector (vectorArray),
miCustomTexMyPoint (pointArray).

The custom text connected to the material looks like this:

int "$MyInt"
int offset "$MyIntOffset"
int type "$MyIntType"
int size "$MyIntSize"
double "$MyDouble"
double offset "$MyDoubleOffset"
double type "$MyDoubleType"
double size "$MyDoubleSize"
vector "$MyVector"
vector offset "$MyVectorOffset"
vector type "$MyVectorType"
vector size "$MyVectorSize"
point "$MyPoint"
point offset "$MyPointOffset"
point type "$MyPointType"
point size "$MyPointSize"
"offsets" [$MyInt $MyDouble $MyVector $MyPoint]
"sizes" [$MyIntSize $MyDoubleSize $MyVectorSize $MyPointSize]
"types" [$MyIntType $MyDoubleType $MyVectorType $MyPointType]

In the exported .mi file the text has changed to:

int "1"
int offset "1"
int type "1"
int size "1"
double "2"
double offset "2"
double type "2"
double size "1"
vector "3"
vector offset "3"
vector type "3"
vector size "3"
point "4"
point offset "4"
point type "4"
point size "4"
"offsets" [1 2 3 4]
"sizes" [1 1 3 4]
"types" [1 2 3 4]

The exported user data block on the polygon mesh shows up as:

data "plane:vxdata"
	"maya_vertexdata" (
		"magic" 1298749048,
		"data" [{
				"name" "Int",
				"type" 1,
				"size" 1,
				"offset" 1
				},{
				"name" "Double",
				"type" 2,
				"size" 1,
				"offset" 2
				},{
				"name" "Vector",
				"type" 3,
				"size" 3,
				"offset" 3
				},{
				"name" "Point",
				"type" 4,
				"size" 4,
				"offset" 4
				}
			]
		)

Using either the placeholder syntax or the user data block, custom shaders can be written that can safely retrieve the custom data at the appropriate places.