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. This tutorial explains how to create your own HyperShade node. As an example, we show how to develop a simple voronoi noise as a Maya 2D Texture.
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 toi indicate their locations.
Copying example files to your 3Delight installation
- Copy the
customShadingNodes
directory itself into themaya
folder of your 3Delight installation - for instance, place the directory copy intoC:\Program Files\3Delight\maya\
on a default Windows installation of 3Delight Studio Pro. - 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 of 3Delight Studio Pro, for Maya 2015, the correct destination location is
C:\Program Files\3Delight\maya\2015\icons
.
Or, defining environment variables
The XBMLANGPATH
definition is optional. On Linux, paths set in XBMLANGPATH
must end with /%B
.
Environment Variable | Value |
---|---|
_3DFM_USER_OSL_PATH | Path to the customShadingNodes directory of the downloaded package. |
XBMLANGPATH | Path 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.
The Voronoi node viewed in the Create menu of the HyperShade
place2dTexture
node is automatically created and connected.
Voronoi noise connected to the
Components
To create a shading node, a compiled OSL shader is required. Its location must be indicated to 3Delight for Maya by an environment variable.
Optionally, it is possible to add icons to have a better visual representation of the node inside the Hypershade and the Outliner. The icon location can be customized using an environment variable.
The following table shows where each component should be installed for a Maya 2015 package.
Component | Environment Variable | Default Location |
---|---|---|
Compiled OSL shaders | _3DFM_USER_OSL_PATH | C:\Program Files\3Delight\maya\customShadingNodes |
Icons | XBMLANGPATH | C:\Program Files\3Delight\maya\2015\icons |
The OSL Source Code
The Voronoi texture looks like a standard Open Shading Language surface shader but with some optional annotation:
string maya_type
Specifies the shading node classification or the attribute type.
Shading Node classification
To define the shading node classification, this annotation mus be provided right after the shader name and before the shader parameter list. For instance:
surface OSLVoronoi [[ string maya_type = "texture" ]] ( ... )
The classification affects where the node is presented in the Hypershade tree lister and menus. Some classification types will 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 currently supported types are:
texture
The shading node will be classified as a texture node. The node will be classified as a 2D texture node, for which Maya automatically create and connect a place2DTexture node, if:
- it contains a
float[2]
parameter that has thestring maya_name = "uv"
annotation, and - it contains a
float[2]
parameter that has thestring maya_name = "uvFilter"
annotation.
- it contains a
lens
The shading node will be classified as a lens shader. Lens shaders can be connected to a camera's lens shader 3Delight extension attribute.
surface
The shading node will be classified as a surface shader. It will be connected to a shading group upon creation.
Attribute type
When this is provided right after the shader name, specifies how to display the attribute in the attribute editor. For now, only "bool" is supported to display an integer parameter as a checkbox.
string maya_name
Specifies the script name of the attribute in Maya.
string maya_label
Specifies the display name of the attribute in the Attribute Editor.
string maya_group
Specifies the name of the group in the Attribute Editor.
float maya_min
Sets the soft minimum value for this attribute.
float maya_max
Sets the soft maximum value for this attribute.
int maya_hidden
If 1, the attribute is hidden and not appears in the Attribute Editor.
The source code for our voronoi texture follows. To use it as Maya HyperShade node, the shader should be compiled using oslc
utility from the 3Delight Studio Pro package (or the standard OSL distribution). The resulting .oso
file must be placed in the directory designated by the _3DFM_USER_OSL_PATH
environment variable.
Adding Icons for the Outliner and Hypershade
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 | HyperShade - Work Area | |
---|---|---|---|
Icon Resolution | 20 x 20 pixels | 32 x 32 pixels | 128 x 128 pixels (up to 512 x 512 pixels) |
Format | Transparent 24 bits PNG | Transparent 24 bits PNG | Transparent 24 bits PNG |
Naming Convention | "out_" + <node_type> + ".png" | "render_" + <node_type> + ".png" | <node_type> + ".png" |
Example | Note the transparent corners of the icon matching Maya |