...
Elements and Properties
Args files were originally created as a way of providing UI hinting for shaders in Katana. PRMan has since adopted and extended this format. Katana's set of elements, parameters and tags are described in detail in the Katana documentation and in the Args File UI Hinting document. Below is a summary of the most commonly used components for the built-in PRMan shaders. Portions that have been adopted specifically for PRMan and RenderMan for Katana and Maya are noted.
Parameter Definition
Details about each param element can be specified using the following properties:
Parameter Properties| Property | Description | Requirement | Origin |
|---|---|---|---|
name | Specifies the exact shader parameter. | Required | Katana |
label | String to display in the UI for the parameter. If no label is specified the name of the parameter is used. | Optional | Katana |
type | The parameter type. Recognized types are: float, int, string, color, normal, point, matrix, shader, vector, struct, and bxdf, lightfilter, displayfilter, and samplefilter. | Required for plugin shaders in RfM. | PRMan extension |
default | Specifies default parameter value. For color, point, normal, and vector, three values are required. For array size > 1, default values are separated by space. Examples: type = "float" default = "5.0". type = "color"", default="0.18 0.18 0.18" type = "normal" default="0 0 0" type = "float" arraySize = "5" default = "15.0 25.0 8.0 5.0 40.0" type = "color" arraySize = "2" default = "0.18 0.18 0.18 0.18 0.18 0.18" For dynamic array, since the array size is unknown, specifying the default values will not work. | Required for plugin shaders | Katana |
arraySize | Specify the array size. Default values are separated by spaces. <param name="resolution" type="float"
arraySize="2" default="1024 1024"/>
| Optional | Katana |
isDynamicArray | Set to "1" if the parameter is a dynamic array. Note that default for dynamic array must not be specified. <param name="layers" isDynamicArray="1"
arraySize="-1" widget="dynamicArray"/>
| Optional | Katana |
widget | The widget property specifies which user interface widget should used for a parameter. If no widget type is defined the widget will default to a numeric type. The standard widget types are defined below. | Optional | Katana |
The following table is a list of the commonly used widget types for RfM and RfK. There are several other widget types defined by Katana which are recognized by RfK but they are not currently recognized by RfM. The table includes a list of commonly-used hints for each widget types. Please see Args File UI Hinting for detailed explanations of these and other available hints.
List of Common Widget Types| Widget Type | Tag Name | Description | Common Hints |
|---|---|---|---|
| Default | default or none | Each parameter type has a default widget type. If the widget type is not specified in the args file it will be determined by the shader parameter data type. | None |
| Numeric | int | Default widget used for numeric parameter types. Common hints are listed below. | min, max, sensitivity, int slider, slidermin, slidermax |
| String | string | Default widget for string parameters. | replaceRegex, replaceWith |
| Boolean | boolean | A dropdown list with "Yes" and "No" options. | None |
| Check Box | checkBox | Boolean parameter displayed as a check box rather than a pop-up. | None |
| Popup/Selector | popup | A pop-up menu or combo box with literal choices for paramter values. | options, editable |
| Mapping Popup | mapper | A pop-up menu with associative choices. Each value has an associated display value. | options, hintdict |
| Color | color | A color parameter where a color picker will be available to pick a color. Note that in Katana, the color picked will return a linearized RGB value. | None |
| File Input | fileInput | A file parameter where a file browser icon will be available to pick a file. | typefilter, presets, fileType. In addition RfM supports the options="texture" option for automatically running txmake. |
| Null/Hidden | null | Hide the parameter from the user interface. | None |
| Float Ramp | floatRamp | Float ramp editor. Require_Knots, _Floats, and _Interpolation for the parameter. See example below. | None |
| Color Ramp | colorRamp | Color ramp editor. Require _Knots, _Colors, and _Interpolation for the parameter. See example below. | None |
| Asset Input | assetIdInput | An asset browser for selecting an input. Use with options="texture". See example below. | None |
Widget Type Examples
| Code Block | ||
|---|---|---|
| ||
<param name="diffuseColor" widget="default"/>
<param name="channel" type="string" widget="popup" options="R|G|B|A"/>
<param name="stops" label="Stops" type="float"
default="0.0" min="-10" max="10"
slider="True" slidermin="-4" slidermax="4"
widget="float">
<param name="atlasStyle" type="int" default="0" widget="mapper">
<hintdict name="options">
<string name="None" value="0"/>
<string name="MARI" value="1"/>
<string name="Mudbox" value="2"/>
</hintdict>
</param>
<param name="filename"
label="Filename"
type="string"
default=""
widget="assetIdInput"
options="texture"
connectable="False">
</param>
<page name="Color Ramp" open="False">
<param name="colorRamp"
label="Color Ramp"
type="int" widget="colorRamp" default="4"
colorBarHeight="25" restrictComponents="True">
</param>
<param name="colorRamp_Knots"
type="float"
widget="null"
default="0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1" arraySize="16"/>
<param name="colorRamp_Colors"
type="color"
widget="null"
default="1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1"
arraySize="16"/>
<param name="colorRamp_Interpolation"
type="string"
default="linear"
widget="null" options="linear|catmull-rom|bspline|constant"/>
</page>
<page name="Falloff" open="False">
<param name="falloff"
label="Fall Off"
type="int" widget="floatRamp" default="6"
connectable="False"
bgColor="0.25 0.25 0.25" underSplineColor="0.5 0.5 0.5">
<help>falloff: Controls the transition from the core to the edge.</help>
</param>
<param name="falloff_Knots"
type="float"
widget="null"
default="0 0 0.3 0.7 1 1 1 1 1 1 1 1 1 1 1 1"
arraySize="16"/>
<param name="falloff_Floats"
type="float"
widget="null"
default="0 0 0.2 0.8 1 1 1 1 1 1 1 1 1 1 1 1"
arraySize="16"/>
<param name="falloff_Interpolation"
type="string"
default="bspline"
widget="null" options="linear|catmull-rom|bspline|constant"/>
</page> |
...