Shader Metadata
The metadata about the shader itself is provided between the shader name and its parameter list. For instance:
surface voronoi [[ string maya_type = "2Dtexture", string maya_typeID = "0x00" ]] ( ... )
The supported shader annotations are:
string niceNam
e
Specifies the string to use for the shader name in the user interface, when possible.
string maya_typeID
Only supported in Maya
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_classification
Only supported in Maya
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 classification string will be prepended with the standard 3Delight shader node classification string so that the nodes are correctly identified as supported shading nodes when the scene is output to the renderer. The classification string can be set to any value, but using one of the following will list the shader in the specified 3Delight category in the HyperShade:
surface
The shading node will be classified as a surface shader and will be listed under 3Delight → Surface in the HyperShade. Upon creation, Maya will create a new shading group and connect this surface shader's outColor
attribute to it. The shader must provide an output color closure parameter that is either named outColor
or mapped to that attribute name using the attribute
or maya_attribute
metadata.
texture/2d
The shading node will be classified as a 2D Texture node and will be listed under 3Delight → 2D Textures in the HypersShade. Upon creation, Maya will automatically create and connect a place2DTexture node to the shader's uvCoord parameter. See UV Coordinate parameter below for details on how to declare such parameter.
texture/3d
The shading node will be classified as a 3D Texture node and will be listed under 3Delight → 3D Textures in the HypersShade. Upon creation, Maya will automatically create and connect a place3DTexture node to the shader's placementMatrix attribute. The OSL shader must provide a matrix input parameter that is either named placementMatrix
or mapped to the placementMatrix
attribute name using the attribute
or maya_attribute
metadata.
utility
The shading node will be classified as a Utility node and will be listed under 3Delight → Utilities.
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.).
float uvCoord[2] = { 0, 0 }
[[
string default_connection = "uvCoord",
int skip_init = 1,
string label = "UV Coordinates",
string widget = "null"
]],