Cutter - Ui-Hints

Cutter
Ui-Hints

Introduction

When Cutter writes an appearance or template slim file it parses the data for each shader/function parameter. Cutter reads the datatype, name, default value and any commented text that accompanies a parameter. Converting a parameter datatype, name and value to the appropriate Slim file format is straight forward. However, Cutter uses certain items of information "embedded" within the comments as a guide to how it should define the GUI of a node. Cutter determines what information to put into a slim file in a two step process.

Step 1

First, it guesses what each parameter should look like when they are displayed by the Slim editor. The guesses are based on the data type and name of each shader parameter or function argument.

Step 2

Next, Cutter looks for a user-interface hint (ui-hint) within the comments associated with a parameter. Cutter considers any text it finds within "[" and "]" brackets as possible sources of information that it can use to refine the "look" of the GUI.

Table 1 gives a full listing of the rules that it applies when making a guess about the "look" of a GUI. Table 2 lists what Cutter considers to be valid ui-hints.

Table 1 Guessing

float param

If param begins with "K", for example,
float Kz = 0;
or the param name is either,
roughness, blend, mix, smooth or step
The slider will have the range 0 to 1.

If the name of a parameter matches the names shown on the left, or if its initial character is "K", Cutter will write a slim document that will assign a slider. This occurs only if the parameter is of type float

string param

A guess is made about the type of popup menu that should appear next o the text field based on a partial match of param with the following,
tex, tra, env, filter, shad, refl, world, shader, camera, current or coord

The list of partial names on the left are associated with the following Slim subtype's. Subtypes configure the popup menu that appears next to a text field. Sub-types are,
"texture" "environment" "filter" "shadow" "reflection" "spacename" "spacename"

Table 2 UI-hints
float param Examples /* [-2 5] / / [-2 5 1] / / [0 or 1] / / [low med high 1 2 3] */	"slider" range from -2 to 5 "slider" 1 unit increments "switch" on or off "selector" popup names/values
string param Examples /* [texture] / / [environment] / / [filter] / / [shadow] / / [reflection] / / [spacename] */	A Slim popup will match th ui-hint. In the case of filter a "selector" will be assigned with following values, box gaussian disk radial-bspline
ANY param Examples /* [collection foo] / / [group foo 0 or 1] / / [collection foo pixar,FNoise]*/	If a hint begins with collection or group the parameter is bundled into a Slim collection . The collection is displayed in a "closed" state.
ANY param (but not strings) Examples /* [inline pixar,FNoise] */	The connected node will appear (inline) with a parameter. Can only be used when converting a shader or a rsl function to a Slim template.
ANY param Examples /* [exp {lerp(0.0,1,$pct)}] / / [expr {lerp(0.0,1,$pct)}] / / [expression "lerp(0.0,1,$pct)"] */	A hint beginning with exp, expr or expression followed by text bounded by "{" and "}" or by double quotes defines a Tcl expression.
ANY param Examples /* [Label "Hello World"] / / [label "Hello World"] */
ANY param Examples /* [default "1 1 1"] / / [Default 1.2] */	Multiple values, the components of a color for example, must be quoted. Can only be used when converting a shader or a rsl function to a Slim template.

Limitations

There's probably lots of them, but here are the known ones!

#include's
If the include statement does not specify the full path to a header, Cutter applies a number of rules when determining what path to provide in the output template document

System headers ie. #include <foo.h>, appear in the template file prefixed with the full path to the lib/shaders directory of the Pixar installation. Cutter does not check the existence of the file.

Include statements such as #include "foo.h" cause Cutter to search for the header file in the following locations.

the same directory as the source document
the rsl source directory specified in the Preferences (figure 1)
the shaders directory specified in the Preferences (figure 1)
the system headers directory

Figure 1

The first location in which the file is found will be used as the specification of the full path given to the slim output document. If the include file cannot be found it is specified "as is" in the output slim document - this will almost certainly cause an error later if the template is loaded into slim.

While it is acceptable to use header files that reference other headers when compiling a shader, it appears that slim template documents cannot do the same. Therefore, you will have to edit your include files so that they do not reference "secondary" headers. There may be a work-around but I do not know what it is!

Appearances, Shader Instance Variables and their Default Values

Cutter can "read" these assignments,

    float foo = 5,
          koo = radians(5);

but not these assignments,

    float foo = 1/(2 * PI);
    float pp  = PI;

Cutter can handle fixed length arrays but not the newer kind of variable length arrays. For example, this is acceptable,

    color nnn[3] = {1, (1,2,3), color(1)};

#define's
These cannot appear in the document from which a slim template will be generated. They must be moved to an include file. Functions called by shader must be moved to an include file.

Signatures

The Languages->Slim preferences panel (figure 2) enables a user to set their "studio", "author" and "prefix" signatures. These items are used to identify the slim templates generated by Cutter.

Figure 2