Page tree
Skip to end of metadata
Go to start of metadata




Sample Render using the custom Voronoi 3D Texture Node.
The following package contains all the material described in this tutorial:
Custom_Hypershade_Nodes.zip

Shader development in 3Delight for Maya is quite simple. With OSL shaders, the process gets simpler yet as 3Delight for Maya can automatically register as Maya shading nodes user-provided OSL shaders. 3Delight supports all the required functions to properly run OSL shaders including all advanced closures, refer to Performance Analysis for more informations.

This tutorial explains how to create your own HyperShade node. As an example, we show how to develop a simple voronoi noise pattern as a Maya 2D Texture. For more informations about procedural textures we recommend this modern classic: Texture & Modeling: a procedural approach.

Content:

Using the example package

Download and decompress Custom_Hypershade_Nodes.zip. To use the package files, you can either copy them to specific locations of your 3Delight installation, or define environment variables to indicate their locations.

Copying example files to your 3Delight installation

  • Copy the customShadingNodes directory itself into the maya folder of your 3Delight installation - for instance, place the directory copy into C:\Program Files\3Delight\maya\ on a default Windows installation of 3Delight, so to have it in C:\Program Files\3Delight\maya\customShadingNodes
  • Optional - copy the files from the icons directory into the icons folder of your 3Delight installation. Make sure to choose the subdirectory that corresponds to the Maya version you are using. For instance, on a default Windows installation, the correct destination location is C:\Program Files\3Delight\maya\2018\icons.

Or, defining environment variables

The XBMLANGPATH definition is optional. On Linux, paths set in XBMLANGPATH must end with /%B .

Environment VariableValue
_3DFM_USER_OSL_PATHPath to the customShadingNodes directory of the downloaded package.
XBMLANGPATHPath to the icons directory of the downloaded package.

 

Lauch Maya and go to the Hypershade editor. The OSLVoronoi node should appear listed under 3Delight → Texture in the Create tab, and under 3Delight OSL Texture in the Create menu. Note that the Maya script editor will report the creation of the new OSL nodes.

The Voronoi node viewed in the Create menu of the HyperShade

The Voronoi node viewed in the Node Editor. The place2dTexture node is automatically created and connected.

 

Voronoi noise connected to the 3Delight Material.

Components of a custom shading node

There is only one required component to define a custom shading node: a compiled OSL shader. Optionally, it is possible to add icons to have a better visual representation of the node inside the Hypershade and the Outliner.

Components location

The following table shows the default location where 3Delight for Maya will look for components, and the environment variable that allows you to specify another location for them.

ComponentEnvironment VariableDefault Location
Compiled OSL shaders_3DFM_USER_OSL_PATHC:\Program Files\3Delight\maya\customShadingNodes
IconsXBMLANGPATHC:\Program Files\3Delight\maya\2015\icons (varies according to the Maya version being used)

The compiled shader

This is a standard Open Shading Language surface shader, complied with oslc (provided with the 3Delight package). The shader source code can be annotated to provide indications to 3Delight for Maya about the Maya shading node classification and its appearance in the Attribute Editor.

While metadata is optional, it is highly recommended to provide the shader metadata that specifies the type ID.

 More info...

When no type ID is provided as metadata, 3Delight for Maya will attempt to generate one in the range reserved for studio internal node types Because this range is not large enough, it is possible that two different OSL shader names will result in identical type IDs; this will cause problems when reading a scene in Maya Binary format. For this reason, using the automatically generated IDs is not recommended for usage outside of prototyping purposes, refer to mayaid.autodesk.io to obtain a reserved block of IDs.

See the Shader metadata section below for details about the maya_typeID.

Re-loading the compiled shader in Maya

Once the edited shader has been re-compiled, the Maya node type definition and the Attribute Editor template can be refreshed by issuing this command:

dlOslUtils -reload <shader node type name>

The Attribute Editor will be refreshed to reflect the changes done in the shader metadata that describe the UI, or the changes in the provided AE<shader node type name>Template.mel file if one is used (see the maya_generateAETemplate shader metadata below).

Note that existing nodes in the scene will not see their attributes changed by the re-load operation. Nodes created after the re-load operation will reflect the updated compiled shader.

The icons

You can add icons to both the Outliner and Hypershade (this applies to both texture nodes and shader nodes). The table below details the convention for creating the icons for our Voronoi Noise.

Outliner

HyperShade - Node Lister

Format & Naming
20 x 20 pixels32 x 32 pixels
Transparent 24 bits PNGTransparent 24 bits PNG
"out_" + <node_type> + ".png"

"render_" + <node_type> + ".png"

Example

render_3DelightVoronoi.png

Note the transparent corners of the icon matching Maya's built-in 2D Texture nodes.

Supported Shader metadata

Shader Metadata

The shader metadata must be 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 niceName

Specifies the string to use for the shader name in the user interface, when possible.

string tags[n] = { tag1, ... tagN }

Katana-specific
An array of n strings defining tags for the shader. The supported tags are:

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.

texture/3d

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

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.

Shader Parameter Metadata

Shader parameter metadata is provided between a parameter's default value and the comma that ends its declaration. For instance:

float i_jitter = 1.0 [[ string attribute = "jitter" ]],

Attribute specification Metadata

The following metadata 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 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 none of the above metadata are provided, the parameter name is used directly to define the attribute name.

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

Maya-specific
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, in the Channel Box Editor, nor in 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).

int skip_init

Setting this metadata to 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:
normal normalCamera = N [[ int skip_init = 1 ]],

string type

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.

bool

Map the shader parameter to a boolean attribute. Valid for integer shader parameters.

enum

Maya-specific
Map the shader parameter to an enum attribute. Valid for integer shader parameters. The enumeration list should be set using the options metadata. For example:
string options = "No Operation:0|Multiply:1|Divide:2|Power:3" 

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.

User Interface Metadata

The following metadata 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. This is currently only supported in Katana.

string label

Specifies the label of the widget that controls the attribute. In Maya, this only has an effect in the Attribute Editor. If no label is specified but niceName is, the later will be used as a label too.

Using niceNamepage and label together allow 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

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 herelock_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 min or only max has no effect in Katana.

string niceName

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 label is specified.

string options

This metadata provides extra options for specific widget types. See widget 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"

float slidermin, float slidermax
int slidermin, int slidermax

Specifies the range of of the slider widget that controls the attribute. 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. The following values are supported when it is required to override the default gadget:

checkBox

A check box widget. Implies a boolean attribute type.

filename

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.

mapper

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 options metadata. In Maya, this widget implies an enum attribute. The enumeration list and values is expected to be defined using the options metadata. 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"

navigation

Maya-specific
A combination of widgets suitable to handle a connection from another node. The attribute is shown as a text field displaying the name of the connected node and a "map" button that brings up a windows allowing the user to select the type of a new node to create and connect to this attribute.

newScenegraphLocation

Katana-specific
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.

null

No widget will be created for this 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"

floatRamp
maya_colorRamp
maya_floatRamp

The ramp widgets require more than one shader parameters and are explained in a dedicated section.

Getting the texture coordinates

Because retrieving the s,t 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:

float uvCoord[2] = { 0, 0 } 
[[
	string default_connection = "uvCoord",
	string label = "UV Coordinates",
	string widget = "null" 
]],


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

The triplet of shader parameters required to present a Maya-style float ramp can be declared as follows:

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"
]],

  • No labels
Write a comment…