The metadata about the shader itself is provided between the shader name and its parameter list. For instance: The supported shader annotations are: Specifies the string to use for the shader name in the user interface, when possible. Katana-specific An array of n strings defining tags for the shader. The supported tags are: texture/3d Maya-specific 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 The IDs from You may use any ID between Maya-specific 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: 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 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. 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 The shading node will be classified as a Utility node and will be listed under 3Delight → Utilities. Maya-specific Setting this to 0 allows providing a complete custom template using a MEL file, just like any other node. Setting this metadata to 1 (or not specifying it at all) will have 3Delight for Maya generate an Attribute Editor template automatically based on the shader parameters' metadata. Parameter metadata is provided between a parameter's default value and the comma that ends its declaration. For instance: The supported parameter annotations are: Specifies the name of the attribute that corresponds to this parameter. There are many reasons to use these attribute - parameter mapping: because the software or OSL imposes restrictions (e.g. an attribute named "color" in Maya, which is a reserved word in OSL), because the shader has different parameter naming conventions than what is expected in the software, or because the required attribute in the software is part of a complex attribute structure that does not have an OSL counterpart. When none of the above metadata are provided, the parameter name is used directly to define the attribute name. Specifies the label of the widget that controls the attribute. Specifies the minimum and maximum values allowed for the attribute. In Katana, this defines the slider range, as an attribute value cannot be bounded. Maya-specific Specifies the attribute name to use in the user interface, when possible. This will be used in the Maya editors, notably the Node Editor and the Channel Box. It will also be used for the automatically generated Attribute Editor template, unless This metadata provides extra options for specific widget types. See Defines the name of a group under which the widget of the attribute will be placed. Nested groups can be defined by formatting the Specifies the range of of the slider widget that controls the attribute. This is ignored in Katana. Specifies the type of the attribute related to this shader parameter. By default, the attribute type is derived from the parameter type and the widget type. Valid for integer shader parameters. Valid for integer shader parameters. The enumeration list should be set using the options metadata. Maya-specific Valid for string shader parameters. A message attribute will be created and the connected node's name will be passed as this shader parameter's value. Defines the type of widget to control the attribute's value. A check box widget. Implies a boolean attribute type. A combination of widgets suitable for a filename. This usually consists of a text field and a file browser button, with some extra features depending of the host software. An option menu with a list of items that have an associated numeric value. The list of item labels and values are defined using the A combination of widgets suitable to handle a connection from another node. No widget will be created for this attribute. An option menu. The selected menu item label is set as the attribute value. This widget works for string shader parameters. The menu items are defined by the The ramp widgets require more than one shader parameters and are explained in a dedicated section. Getting the texture coordinates Because retrieving the UV coordinates is a costly process, it is best to centralize this operation in a single shader and share the results with all shaders. For a shader to benefit of this, it may declare a parameter similar to this: This uses the following metadata intended to address this specific problem: This combination of metadata instruct that when no incoming connection exists on the node attribute, one should be established between the uvCoord shader that 3Delight outputs by default and this parameter. The uvCoord shader is the centralized place to fetch the UV coordinates. The ramp widgets in Maya and Katana both require 3 different attributes. They also have diverging expectations and features. The triplet of shader parameters required to present a Maya-style float ramp can be declared as follows:Shader Metadata
surface voronoi [[ string maya_type = "2Dtexture", string maya_typeID = "0x00" ]] ( ... )
string niceName
string tags[n] = { tag1, ... tagN }
surface
displacement
The shader will be considered a surface shader or a displacement shader, respectively. Tagging a shader with one of these values will have 3Delight for Katana create a Network Shader node along with the surface shader or displacement shader, and connect it appropriately. The tag will also allow the shader to be listed as surface material or displacement material in a Material node.
The shader will be considered a 3D texture.hidden
The shader will not be listed in the shading node layered menu (shown when pressing the s
key in the Node Graph).string maya_typeID
0x0000
and 0x007F
, or between 0x7F01
and 0x7FFF
for your shading node type.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.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
surface
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
texture/3d
placementMatrix
or mapped to the placementMatrix
attribute name using the attribute
or maya_attribute
metadata.utility
int maya_generateAETemplate
Parameter metadata
float i_jitter = 1.0 [[ string attribute = "jitter" ]],
string attribute
string maya_attribute
string katana_attribute
maya_attribute
is Maya-specific and overrides attribute
, whereas katana_attribute
is Katana-specific and overrides attribute
.string label
float min, float max
int min, int max
string niceName
label
is specified.string options
widget
for details.string page
page
value string as "parent group.child group".
float slidermin,
float slidermaxint slidermin,
int slidermaxstring type
bool
enum
message
string widget
checkBox
filename
mapper
options
metadata. In Maya, this widget implies an enum attribute, which has an integer value. The enumeration list and values for a type set to enum or a widget set to mapper is expected to be defined using the options
metadata. The expected format is a list of labels, optionally with values, separated by a |
. For instance:string options =
"Euclidean:0|"
"Manhattan:1|"
"Chebyshev:2|"
"Minkowski:3|"
navigation
null
popup
options
metadata as a list of labels separated by |
. For instance:string options = "clamp|black|mirror|periodic"
floatRamp
maya_colorRamp
maya_floatRamp
float uvCoord[2] = { 0, 0 }
[[
string default_connection = "uvCoord",
int skip_init = 1,
string label = "UV Coordinates",
string widget = "null"
]],
string default_connection = "uvCoord"
int skip_init = 1
Ramp widgets
Maya-style float ramp widget
float i_value_Position[] = { 0, 1 }
[[
string katana_attribute = "value_Knots",
string maya_attribute = "value.value_Position",
string related_to_widget = "maya_floatRamp",
string widget = "null"
]],
float i_value_FloatValue[] = { 0, 1 }
[[
string katana_attribute = "value_Floats",
string maya_attribute = "value.value_FloatValue",
string label = "value",
string widget = "maya_floatRamp"
]],
int i_value_Interp[] = { 1, 1 }
[[
string katana_attribute = "value_Interpolation",
string attribute = "value.value_Interp",
string related_to_widget = "maya_floatRamp",
string widget = "null"
]],
Maya-style color ramp widget
float i_color_Position[] = { 0, 1 }
[[
string katana_attribute = "color_Knots",
string maya_attribute = "color.color_Position",
string related_to_widget = "maya_colorRamp",
string widget = "null"
]],
color i_color_Color[] = { 0, 1 }
[[
string katana_attribute = "color_Colors",
string maya_attribute = "color.color_Color",
string label = "color",
string widget = "maya_colorRamp"
]],
int i_color_Interp[] = { 1, 1 }
[[
string katana_attribute = "color_Interpolation",
string maya_attribute = "color.color_Interp",
string related_to_widget = "maya_colorRamp",
string widget = "null"
]],
Overview
Content Tools