This section provide details about how to configure the appearance of RenderMan shader nodes in the Attribute Editor.
Attribute Grouping
It is possible to define groups of parameters for RenderMan shader nodes. This feature is particularly useful for shaders exposing a large number of parameters since it enables the shader writer to group logically related parameters in a clean interface.
Grouping definition is done using shader annotations in the shader’s RenderMan shading language source file. The grouping information will be used to create frame layouts containing the specified shader parameters’ gadgets in the Attribute Editor. The supported annotation syntax is:
#pragma annotation "grouping" "<group>/[<subgroup>/...]<parameter name>;"
As an example, the following annotation will create a frame layout labeled ‘Hair Color’ and put the ‘tipcolor’ parameter gadgets in it.
#pragma annotation "grouping" "hairColor/tipcolor;"
It is possible to define any number of frame layout levels; for instance:
#pragma annotation "grouping" "hair/hairColor/tipcolor;"
would create a ‘Hair’ frame layout, then create a ‘Hair Color’ frame layout inside the ‘Hair’ frame layout, and finally insert the ‘tipcolor’ gadgets there.
The parameters will appear in the order they are annotated. Parameters that have no annotations will end up in the usual ‘Shader Parameters’ and ‘Output Parameters’ frame layouts.
It is possible to generate pragma statements from macros by using the Pragma operator. For example, this is equivalent to the above pragma:
#define MY_PRAGMA \ _Pragma( "annotation \"grouping\" \"hairColor/tipcolor;\"" )
Performing string substitution on the operator’s string parameter requires some advanced macro tricks which are explained in 3Delight's User's Manual.
Defining Shader Parameter Gadgets
It is possible to modify the gadgets that are created by default using shader annotations in the shader’s RenderMan shading language source file. The annotations to define the user interface for a given parameter should adhere to the following form:
#pragma annotation <shader_param_name> "annotation[;annotation;...];"
It is possible to specify multiple annotations lines for the same shader parameter; they will all be concatenated in a single annotation string by the shader compiler. The supported annotations for defining the user interface of a parameter are:
gadgettype=<type>
It specifies the type of gadget to create. The supported types are:
| Option | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
floatfield | A numeric text field that supports floating point values. | ||||||||
floatslider | A float text field with a slider. Supported only for the float shader parameter type. It is recommended to also supply the ‘min’ and ‘max’ annotations as the default range is from 0 to 1. | ||||||||
intfield | A numeric text field that supports integer values. | ||||||||
intslider | A integer text field with a slider. Supported only for the float shader parameter type. It is recommended to also supply the ‘min’ and ‘max’ annotations as the default range is from 0 to 1. | ||||||||
textfield | A simple text field. Supported only for the string shader parameter type. | ||||||||
inputfile | A text field with a browse button and a view button. Supported only for the string shader parameter type. | ||||||||
optionmenu:menuitem1<=value1>:... | An option menu that offers specified menu items. Supported only for string and float parameter types. For the "gadgettype=optionmenu:zero:one:fifty=50:fifty-one;" | ||||||||
___________________________________________ | An option menu that lists nodes that can be connected to this shader node. Supported only for string parameters. The string shader parameter will receive the name of the connected node. Since the node name is resolved through the connection, it will always be up-to-date and take reference prefixes into account. The following gadget options are available:
| ||||||||
checkbox | A checkbox. Supported only for the float shader parameter type. | ||||||||
colorslider | A color slider. Supported only for the color shader parameter type. | ||||||||
label=<label text> | Specifies a label for the gadget. When no label annotation is supplied, the gadget’s label is the parameter name itself. | ||||||||
hide=<true/false> | When true, no gadget is generated for that parameter. However, the shader node will still contain an attribute related to this parameter, thus the parameter’s value can be defined outside of the Attribute Editor (by a setAttr command for instance). | ||||||||
disable=<true/false> | When true, the gadget is generated for the parameter, but will be disabled (insensitive). | ||||||||
ignore=<true/false> | When true, the shader parameter is completely ignored - no gadget and no related attribute in the shader node are created; the shader parameter will not be specified in the shader call made when rendering. | ||||||||
| Specify min and max values for the attribute. These values are used at attribute creation time so Maya will enforce these limits even for incoming connections, scripted setAttr commands, etc. | ||||||||
hint=<hint text> | Specify a gadget annotation that appears when the mouse pointer is left over the gadget for a little while. |
The following illustrates how gadget annotations can be constructed:
#pragma annotation floatenum "label=Float Opt Menu Label;"
#pragma annotation floatenum "gadgettype=optionmenu:Zero=0:One:Two:Fifty=50:Fifty-one;"
#pragma annotation stringenum "gadgettype=optionmenu:item 1:item 2:item 3=custom value;"
#pragma annotation floatParam "label=int slider label;gadgettype=intslider;min=1;max=50;"
#pragma annotation cameraParam "label=camera label;"
#pragma annotation cameraParam "gadgettype=connectednodeoptionmenu:listcmd=ls -type camera"
#pragma annotation coordSysParam "label=coordinate system;"
#pragma annotation coordSysParam "gadgettype=connectednodeoptionmenu
#pragma annotation coordSysParam ":type=delightCoordinateSystem"
#pragma annotation coordSysParam ":noconnectionlabel=no connection"
surface annotationTestShader( float floatenum=0; string stringenum="item 2"; float floatParam = 2; string cameraParam = ""; string coordSysParam = "";)
{ }