Page History

While annotations are optional, it is highly recommended to provide the shader annotation that specifies the type ID.

Annotations in the OSL source code

The annotations are defined between double square brackets. Multiple, comma-separated annotations,  can be used in one set of double square brackets.

Shader annotation

This annotation is provided between the shader name and its parameter list. For instance:

surface OSLVoronoi [[ string maya_type = "texture", string maya_typeID = "0x00" ]] ( ... )

The supported shader annotations are:

string maya_typeID

Specifies the type ID used for the node registration. This is a integer that Maya uses to identify the node type, most notably when saving a scene in the Maya Binary format. Each OSL shader that defines a given shading node type should be assigned a unique type ID. You can chose a value between 0x0000 and 0x007F, or between 0x7F01 and 0x7FFF for your shading node type.

The IDs from 0x0000 to 0x7FFF are reserved for node types that are used internally in a studio. 3Delight for Maya will generate a type ID between 0x0080 and 0x7F00 if no maya_typeID annotation is provided. You can also request your own reserved node ID range to Autodesk, for free. This is also the recommended solution if you intend to share your nodes with users outside your studio.

You may use any ID between 0x0000 and 0x7FFF if you always provide the maya_typeID annotation for every custom OSL shader you define. In this case 3Delight for Maya will never need to generate a type ID.

string maya_type

Specifies the Maya shading node classification. The classification affects where the node is presented in the Hypershade tree lister and menus. Some classification types will also change the node creation mechanism to automatically create and connect related nodes - for instance, creating a surface shader will also create and connect a shading group.

The currently supported types are:

texture

The shading node will be classified as a texture node. The node will be classified as a 2D texture node, for which Maya automatically create and connect a place2DTexture node, if:

• • it contains a float[2] parameter that has the string maya_name = "uv" annotation, and
  • it contains a float[2] parameter that has the string maya_name = "uvFilter" annotation.

lens

The shading node will be classified as a lens shader. Lens shaders can be connected to a camera's lens shader 3Delight extension attribute.

surface

The shading node will be classified as a surface shader. It will be connected to a shading group upon creation.

Parameter Annotations

Parameter annotations are provided between a parameter's default value and the comma that ends its declaration. For instance:

float i_jitter = 1.0 [[ string maya_name = "jitter" ]],

The supported parameter annotations are:

string maya_type

Specifies the type of the Maya attribute related to the shader parameter. For now, only bool is supported to display an integer parameter as a checkbox.

string maya_name

Specifies the name of the Maya attribute related to the shader parameter.

string maya_label

Specifies the label to use for the Maya attribute in the various Maya editors (Attribute Editor, Node Editor, Channel Box, etc.).

string maya_group

Specifies the label of a Frame Layout into which the Maya attribute will be displayed in the Attribute Editor.

float maya_min

Specifies the soft minimum value for the Maya attribute attribute related to the shader parameter.

float maya_max

Specifies the soft maximum value for the Maya attribute attribute related to the shader parameter.

int maya_hidden

When set to 1, the Maya attribute will not be shown in the Attribute Editor. It will still be visible in the other Maya editors (Node Editor, Channel Box, etc.).

Annotated OSL shader example

/** Returns the U comp of the default UV set */
float GetS()
{
	float st[2];
	if( getattribute("st", st) )
	{
		return st[0];
	}
	else
	{
		return u;
	}
}

/** Returns the T comp of the default UV set */
float GetT()
{
	float st[2];
	if( getattribute("st", st) )
	{
		return st[1];
	}
	else
	{
		return v;
	}
}


surface OSLVoronoi [[ string maya_type = "texture" ]] (
		float i_jitter = 1.0 [[
			string maya_name = "jitter",
			string maya_label = "Jitter",
			float maya_min = 0.0,
			float maya_max = 1.0,
			string maya_group = "3Delight Voronoi" ]],
		float i_seed = 1.0 [[
			string maya_name = "seed",
			string maya_label = "Seed",
			float maya_min = 0.0,
			float maya_max = 2.0,
			string maya_group = "3Delight Voronoi" ]],
		float i_uvCoord[2] = {GetS(), GetT()} [[
			string maya_name = "uv",
			int maya_hidden = 1,
			int skip_init = 1 ]],
		float i_uvFilterSize[2] = {0, 0} [[
			string maya_name = "uvFilterSize",
			int maya_hidden = 1,
			int skip_init = 1 ]],

		output color outColor = 0.0 [[
			int maya_hidden = 1 ]],
		output float outDistance = 0.0 [[
			int maya_hidden = 1 ]] )
{
	float edgeDist;
	float outside;

	/* 
		i_uvCoord is multiplied by 10 to produce a visible result with default 
		place2DTexture. This is similar to setting RepeatU / V to 10.
	*/
	point pp = point(i_uvCoord[0] * 10, i_uvCoord[1] * 10, i_seed);

	point position;

	point thiscell = point( floor(pp[0])+.5, floor(pp[1])+.5, floor(pp[2])+.5);
	float f1 = 1000;
	for (int i = -1;  i <= 1;  i += 1)
	{
		for (int j = -1;  j <= 1;  j += 1)
		{
			for (int k = -1;  k <= 1;  k += 1)
			{
				point testcell = thiscell + vector(i,j,k);
				point pos =
					testcell + i_jitter * ((vector)cellnoise(testcell) - 0.5);
				vector offset = pos - pp;
				float dist = dot(offset, offset); /* actually dist^2 */
				if (dist < f1)
				{
					f1 = dist;
					position = pos;
				}
			}
		}
	}

	outDistance = sqrt(1 - f1);
	outColor = outDistance;
}