Shader Meta-data
The following attributes can be specified as shader meta-data. This kind of meta-data is specified between the shader name and its parameter list.
string tags[ ]
An array of strings that tag the shader. The supported tags are:
surface
displacement
Classifies the shader as a surface shader or a displacement shader, respectively, in Katana. 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. (Only shaders providing the proper tag will be listed as surface materials or displacement materials in a "material" node).
lightfilter
Classifies the shader as a light filter. (qu'est-ce que ça change au juste)
environment
Classifies the shader as an environment. (qu'est-ce que ça change au juste)
hidden
Providing the hidden tag will prevent the shader from appearing in the shading node layered menu that is shown in the node editor when pressing the "s" key (, and from the list of available shaders in a "material" node).
string maya_typeID
Specifies the type ID used for the node registration. The expected string value is the unique number in hexadecimal format, starting with 0x
. 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 related Maya 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 by Autodesk 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. Note that because of the limited range available, it is impossible to guarantee that the generated type ID will truly be unique.
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
texture/2d texture/3d surface lens
int maya_generateAETemplate
Setting this meta-data to 0 indicates that no Attribute Editor template should be generated by 3Delight for Maya. You are then responsible for providing one. This meta-data is specific to 3Delight for Maya and is ignored elsewhere.
string niceName
Specifies a string to be used in the user interface when referring to the shading node type name. This currently affects the labeling of the entries in the Create section of the Hypershade in Maya. Note that the node type name is set to the shader name.
Shader Parameter Meta-data
The following attributes can be specified for a given shader parameter.
Attribute specification Meta-data
The following meta-data provides details that are used when generating the attribute of the shading node that corresponds to a given shader parameter.
string attribute
string maya_attribute
string katana_attribute
Specifies the name of the attribute for a given shader parameter. When none of the above meta-data are specified, the parameter name will be used directly as for the attribute name. While it is much simpler to simply choose shader parameter names that can be directly, sometimes the Maya or Katana conventions imply some specific name that is disallowed in OSL (e.g. a node attribute named color
). In other times, each software has its own conventions for attributes related to specific UI constructions (e.g. ramp gadgets). In Maya, the value of maya_attribute
has precedence over the value of attribute. In Katana, the value of katana_attribute
has precedence over the value of attribute
.
The *none
special value indicates that there will not be any node attribute generated for that shader parameter.
string default_connection
Specifies the name of a shader to be connected to this shader parameter when no connection exists. The only supported value is uvCoord
. This should be used for float[2]
shader parameters that receive the st
coordinates; it centralizes the s, t
lookup in a single shader which improves performance.
int hidden
When this is set to a non-zero value, a Maya attribute will be defined for the given shader parameter, but it will not be shown in the Attribute Editor, Channel Box Editor, nor the Node Editor. If you only want to avoid getting a gadget for the parameter, see the widget
meta-data below (which also works in Katana).
string niceName
Defines the string to be used in the user interface when presenting the attribute. This will be shown in the Node Editor and the Channel Box Editor. It will also be used in the Attribute Editor, unless label
is specified.
string type
Specifies the attribute type. Regular OSL parameter types are mapped automatically to the relevant attribute type and don't require type to be specified.
This should be dropped?
User Interface Meta-data
The following meta-data provides details about the user interface presentation of the shader parameter.
string help
Specifies a string that will be shown in a help box or tool tip.
string label
The label of the gadget for the shader parameter. In Maya, this only has an effect in the Attribute Editor; if no label is specified, the niceName will be used if provided.
Using niceName
, page
and label
together allows a parameter named baseLayerColor
to be labeled simply as Color in a Base Layer page, and appear as Base Layer Color in the Node Editor.
string lock_op
string lock_left
string lock_right
Define a lock operator, its left operand and its right operand, respectively. Lock operations allow the gadget to become insensitive or locked when the operator returns true. The various operators are listed here. lock_left
should be set to an attribute name, and lock_right
to a value appropriate for the chosen operator. For example, this would make the gadget of an attribute insensitive when a barnDoor
attribute would not be set to 1:
string lock_left = "barnDoors", string lock_op="notEqualTo", int lock_right=1
These only have an effect in Katana.
int / float min
int / float max
Define the minimum and maximum values of a numeric parameter, respectively. When both are defined, the attribute gadget will be made of a numeric field and a slider. In Maya, this configures the attribute with the specified hard minimum and / or maximum value. In Katana, there is no way to enforce minimum or maximum values on attributes. Having a slider shown helps providing information about the parameter's useful range of values. Providing only min
or only max
has no effect in Katana.
string options
A string providing optional values for some widget
values. See widget
above for details.
string page
Specifies the name of a collapsable section that is used to group together related attributes. Nested pages can be defined by setting this metadata to a string containing the path to the given page. For instance:
string page = "Parent Page.Child Page"
int sliderexponent
Specifies the slider exponent. This only has an effect in Katana.
int / float slidermin
int / float slidermax
Define the range of values covered by the slider. In Katana, providing only one of slidermin
or slidermax
will have no effect.
int texturefile
This meta-data should be set to 1 for parameters that specify a texture file name.
string widget
Specifies the type of gadget that will show the attribute's value(s). By default, a gadget appropriate for the attribute type is generated. In Maya, matrix attributes are not shown in the Attribute Editor. In Katana? . The following values are supported when it is required to override the default gadget:
checkbox
The integer shader parameter will be presented as a checkbox. In Maya, this value will also cause a boolean attribute to be created instead of an integer one.
filename
The string shader parameter will be presented as a text field with a browse button that produces a file browser dialog when clicked.
mapper
The integer shader parameter will be presented as an option menu with predefined menu items that each set a specific value. In Maya, this value will also cause an enum attribute to be created instead of an integer one.
The list of labels and values are specified by the option
meta-data. Set options to a string containing one or more <label>:<value>
, separated by |
. For example:
string options = "No Operation:0|Multiply:1|Divide:2|Power:3"
null
No gadget will be offered for the attribute. Note that the attribute will still be defined.
popup
The string shader parameter will be presented as an option menu with predefined menu items. The menu items are specified by the options
meta-data. Set options
to a string containing the names of the menu items, separated by |
. For example:
string options = "clamp|black|mirror|periodic"
navigation
The attribute is shown as a text field displaying the name of the connected node and a "mapper" button that brings up a windows allowing the user to select the type of a new node to create and connect to this attribute. This is only available in Maya.
newScenegraphLocation
The attribute will be shown with a gadget suitable for defining a new scene graph location; the created location path is passed as the shader parameter value. This is only available in Katana.