Excerpt |
---|
Shader MetadataThe |
...
shader metadata must be provided between the shader name and its parameter list. For instance:
|
...
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:
|
...
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. texture/3d The shader will be considered a 3D texture. 3D texture will have a 3D placement matrix added automatically in all plug-ins.
The shader will be considered as a 2D texture.
The shader will be considered as a utility node.
The shader will not be listed in the shading node menu. Shader Parameter MetadataShader parameter |
texture/3d :
the shader will be considered a 3D texture.
hidden :
the shader will not be listed in the create shader node overlay menu.
string maya_typeID
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 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
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:
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.
int maya_generateAETemplate
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
...
metadata is provided between a parameter's default value and the comma that ends its declaration. For instance:
|
The supported parameter annotations are:
string attribute
string maya_attribute
Attribute specification MetadataThe following metadata provides details that are used when generating the attribute of the shading node that corresponds to a given shader parameter.
|
...
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. |
maya_attribute
is Maya-specific and overrides attribute
, whereas katana_attribute
is Katana-specific and overrides attribute
.
...
When this metadata are provided, the parameter name is used directly to define the attribute name. The
Specifies the name of a shader to be connected to this shader parameter when no connection exists. The only supported value is
Maya-specific int skip_init Setting this metadatato 1 will will prevent the attribute value from being passed as a shader parameter value when rendering. Only incoming connections to this attribute will be defined when rendering. This allows passing implicit values to shader parameters, such as:
|
Info |
---|
Using |
string lock_op
string lock_left
string lock_right
Katana-specific
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
float min, float max
int min, int 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. Nevertheless, having a slider shown helps providing information about the parameter's useful range of values. Providing only
|
Maya-specific
Specifies the attribute name to use in the user interface, when possible. |
...
This metadata provides extra options for specific widget types. |
...
See |
...
for details.
|
...
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:
Specifies the range of of the slider widget that controls the attribute. |
...
This meta-data should be set to 1 for parameters that specify a texture file name.
|
...
Specifies the type of gadget that will show the attribute |
...
's value(s). By default, a gadget appropriate for the attribute type is |
...
bool
Valid for integer shader parameters.
enum
Valid for integer shader parameters. The enumeration list should be set using the options metadata.
message
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.
string widget
...
generated. In Maya, matrix attributes are not shown in the Attribute Editor. The following values are supported when it is required to override the default gadget:
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 with a browse button that produces a file browser |
...
dialog when clicked.
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 |
...
. The |
...
enumeration list and values |
...
is expected to be defined using |
...
Code Block |
---|
string options =
"Euclidean:0|"
"Manhattan:1|"
"Chebyshev:2|"
"Minkowski:3|" |
...
the |
...
metadata. Set options to a string containing one or more string options = "No Operation:0|Multiply:1|Divide:2|Power:3"
Maya-specific |
Katana-specific
No widget will be created for this attribute. Note that the attribute will still be defined.
|
...
The string shader parameter will be presented as an option menu |
...
with predefined menu items. The menu items are |
...
specified by the string options = |
Code Block |
---|
string options = "clamp|black|mirror|periodic" floatRamp |
...
colorRamp |
maya_floatRamp
The ramp widgets require more than one shader parameters and are explained in a dedicated section. Getting the texture coordinatesBecause retrieving the |
...
|
This uses the following metadata intended to address this specific problem:
string default_connection = "uvCoord"
int skip_init = 1
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.
Ramp widgets
|
...
The ramp widgets in Maya and Katana both require 3 different attributes. They also have diverging expectations and features. |
...
Maya-style float ramp widget
Note that The triplet of shader parameters required to present a Maya-style float ramp can be declared as follows:
|
Maya-style color ramp widget
Maya-SpecificMaya requirues both a typeID and a template file. The following meta-data allow you to to automatically take car of these.
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
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. |