*Supported Meta-data

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. 

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.