Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.




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


Section


Column

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 OSL in 3Delight 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.


Column
width35%


Panel
borderColor#e0e0e0
bgColor#f0f0f0
titleColor#444444
titleContent:

Table of Contents
maxLevel2



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.

Warning

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

Expand
titleMore 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:

Code Block
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 abovebelow).

Note that existing nodes in the scene will not see their attributes changed by the reload 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

Excerpt Include
3DSP:Supported 3Delight's OSL Metadata
3DSP:Supported 3Delight's OSL Metadata
nopaneltrue