vcc compiler pragmas

#pragma bindhandle channel_name h_name h_label h_index h_settings

Binds handles to specific parameters by default (users can override bindings).

#pragma bindhandle offset1 xform "Translate" tx "invisible(1)"
#pragma bindhandle offset2 xform "Translate" ty
#pragma bindhandle offset3 xform "Translate" tz
sop translate(vector offset=0) { P += offset; }

#pragma bindhandlereserved reserved_channel_name h_name h_label h_index h_settings

Each scripted operator type has a number of parameters that are added to every operator of that type (regardless of the contents of the dialog script file). To bind a handle to one of these parameters, you must use the bindhandlereserved pragma. This pragma takes exactly the same arguments as the bindhandle pragma. The only exception is that the channel name argument must specify the name of a reserved parameter.

#pragma bindselector [parm_name] sel_type sel_name sel_prompt sel_mask allow_dragging group_type_parm asterisk_sel_all [input_index input_required]

When an operator is created interactively in Houdini, the user can be prompted for the data to work on. These prompts are handled by selectors. Selectors can be defined on a per-OP basis, or a per-parameter basis.

For per-OP selectors, the bindselector pragma expects 7 arguments. For per-parameter selectors, it expects 10 arguments.

#pragma bindselector prims "Switch Geometry" \
    "Choose the geometry to switch between" \
    all 0 "" 0
#pragma bindhandle input_number 0 ladder Input parm0
sop switcher(int input_number=0) { import("P", P, input_number) }

#pragma bindselectorreserved reserved_parm_name sel_type sel_name sel_prompt sel_mask allow_dragging group_type_parm asterisk_sel_all input_index input_required

Similar to the bindhandlereserved pragma, this binds selectors to reserved parameters in your scripted operators. The arguments to this pragma are the same as those passed to the bindselector pragma. The only difference is that the parameter name argument must specify a reserved parameter.

#pragma callback name script

Binds an HScript script to parameter name. If the UI dialog script is bound to an operator (for example, a SHOP, SOP, POP, etc.), when the parameter changes, Houdini runs the associated script.

Because of architectural limitations in Houdini, the parameter and script must meet certain conditions:

• The dialog script needs to be bound to a Houdini Operator (i.e. SHOP, POP, SOP, etc.).

• The parameter must be either a toggle button, or have a menu bound to it (see #pragma hint and #pragma choice).

#pragma callback initialize_menu "sop/initialize_sop.cmd"

Houdini searches the standard $HOUDINI_PATH/scripts path for the script to run. If it finds the script, it sets the local variable $script_parm to the name of the parameter being changed, and runs the script.

#pragma crypt: The following lines should be encrypted .

#pragma endcrypt: Stop encrypting a block of code starting with #pragma encrypt.

#pragma crypt does not require a closing #pragma endcrypt. You can think of the two directives as turning encryption on and off.

#pragma disable parm_to_disable control_parm control_value [control_parm2 control_value2 ...]

Disables parm_name when control_parm equals control_value

If you supply more than one pair of control parameters and values, parm_name is only disabled if all the conditions are true. To specify conditions where the parameter will be disabled if any one of them is true, use multiple pragma directives.

Disabling parameters helps make it clear to the user which parameters are useful in the current situation (for example, “Number of Subdivisions” is only useful when “Subdivide” is on).

// Disable parm B when A is 0 or A is 1:
#pragma disable B  A 0
#pragma disable B  A 1
// Disable parm C when A is 0 and B is 0, or just when A is 1.
#pragma disable C  A 0  B 0
#pragma disable C  A 1
// Disable parm D when C is "none".
#pragma disable D  C "none"
cop2 function(int     A = 0;
              int     B = 0;
              string  C = "gaussian";
              vector  D = { 0,0,0 })
{ ... }

#pragma export parm_name (none | dialog | all)

Adds the parameter UI to the operation parameters dialog, and optionally also the operator toolbar.

You can use #pragma hint hidden in combination with this pragma.

#pragma group group_name parameter_name1 parameter_name2 ...

Groups the named parameters into a tab in the UI.

// Group Ka, Kd, Ks, roughness into a folder called BRDF
#pragma group BRDF Ka Kd Ks
#pragma group BRDF roughness

#pragma group "Group/Sub Group 1" p1 p2
#pragma group "Group/Sub Group 2" p3 p4

#pragma help "text"

Adds text to the help in the dialog script. You can use this to document functions and parameters for end-users.

#pragma help "This is help for the VEX function."
#pragma help "It gets added automatically to the help text"

Like #pragma help, #pragma info text is added to the help in the dialog script. However, the info text is in a separate section at the beginning of the help. You can use this to specify copyrights, version information, etc.

#pragma info "Created by Bob Loblaw - (c) 2006"

Currently, only SOPs display info text.

#pragma hint parameter_name hint_type

Adds information about what type of value a parameter represents (for example, a VEX vector may represent a point in space, a color, or a direction). The hint is used to specialize the UI for editing the value.

The hint_type can be one of the following:

#pragma hint __nondiffuse toggle // Define as a toggle button
#pragma hint specularcolor color // This represents a color
#pragma hint rest hidden         // Don't show rest parameter in UI
#pragma hint mapname image       // This represents an image file
#pragma hint nullobject oppath "obj/null" // Only null objects

#pragma inputlabel inputnum "label"

For VEX operator types, sets the label for an operator input. This label appears when the user presses the middle mouse button on one of the operator inputs. The inputnum is the index of the input, starting at 1.

#pragma inputlabel 1 "Geometry to Modify"

#pragma label parameter_name "text"

Specifies a descriptive label for a parameter.

#pragma label amp    "Noise Amplitude"
displacement bumpy(float amp=0) {
...
}

Sets the label that appears in the UI. This pragma is obsolete since the label is now defined in the operator table definition.

#pragma opicon "text"

Use this pragma to set the icon to use for this operator type. It can be a path to an external .icon or .bicon file, or the name of one of the standard icons.

vcc’s -C command line option overrides this pragma.

#pragma opmininputs num

For VEX operator types, this sets the minimum number of inputs that must be connected to the operator. This value is ignored for SHOPs, which take no inputs. The operator will generate an error if fewer than this many nodes are connected as inputs. The -t command line option overrides this pragma.

#pragma opmaxinputs num

For VEX operator types, this sets the maximum number of inputs that can be connected to the operator. This value is ignored for SHOPs, which take no inputs. The -T command line option overrides this pragma.

#pragma opmininputs 1
#pragma opmaxinputs 4

#pragma opname "text"

Specifies the internal operator name of this operator type. By default the compiler uses the name of the source file. vcc’s -n command line option overrides this pragma.

#pragma oplabel "text"

Specifies a descriptive name for this operator type. By default the compiler uses internal operator name. vcc’s -N command line option overrides this pragma.

#pragma opname "myshop"
#pragma oplabel "My New Shop"

#pragma opshader"text"

If this operator type is a shader that can be used from renderers other than mantra, this pragma lets you set the name of the shader file that the renderer should look for. If you use this pragma, the operator type name does not need to match the shader file name. vcc’s -S command line option overrides this pragma.

#pragma opshader "rman_myshader"

#pragma parmhelp parameter_name "text"

Sets the tooltip that appears when the user hovers over parameter_name.

#pragma parmhelp amp "Increase this value to add more noise."
displacement bumpy(float amp=0) {
...
}

#pragma parmtag parmName token value

Each parameter defined in an operator has a set of token/value tags associated with it. This pragma adds a token/value pair to a parameter.

The following tokens are available:

#pragma parmtag lightmask opfilter "!!OBJ/LIGHT!!"
#pragma parmtag lightmask oprelative "/obj"
#pragma parmtag lightmask opexpand 1
#pragma parmtag reflectmask opfilter "!!OBJ/GEOMETRY!!"
#pragma parmtag reflectmask opexpand 1
#pragma parmtag reflectmask opfullpath 1

#pragma range parameter_name[!] min_value max_value[!]

Defines the ideal range for the parameter. If you append ! to a value, the parameter value will be clamped at that range. The UI also uses this information to set the range of the slider.

#pragma range seed    0 10
#pragma range roughness 0.001! 1!
#pragma range gamma     0.001! 10

#pragma rendermask (VMantra | RIB | MI | OGL)

This pragma is only useful for SHOP dialog generation. Each SHOP has a mask defining which renderers can use the SHOP. It is possible to have a similar shader written in the RenderMan shading language and also in VEX (or another shading language). In this case, the rendermask can be specified to include more than just VMantra.

The rendermask parameter is closely bound to the code which generates scene descriptions for a renderer. Thus, the renderer names are quite specific. The renderers which support SHOPs are…

You can define choice pragmas to create a menu UI for a parameter.

You build the list for a parameter by doing one of the following:

• Use multiple choice pragmas for a parameter to create menu items (choice, choicescript, choicereplace, choicetoggle).

• Use one or more choicescript pragmas for a parameter to create a script that creates the menu items (choicescript, choicereplacescript, choicetogglescript).

  This script is run whenever Houdini needs to generate the menu entries (i.e. the generated values are not cached) so this script should be as efficient as possible. The output of the script must be a series of value/label pairs, which have the same meaning as the value and label fields in the choice pragma.

The plain choice pragma creates a UI that only allows the user to choose values from the menu. The choicereplace pragma creates UI with a menu but also lets the user enter a different value manually. The choicetoggle pragma allows user input, but also provides a menu where choosing a menu item adds or removes it to/from the input.

menu or input their own.

menu or input their own.

the user input.

the user input.

#pragma choice operation "over"    "Composite A Over B"
#pragma choice operation "under"    "Composite A Under B"
#pragma choice operation "add"    "Add A and B"
#pragma choice operation "sub"    "Subtract A from B"
cop texture(string operation="over")
{
if (operation == "over") ...    // texture coordinates
if (operation == "under") ...    // parametric coordinates
if (operation == "add")     ...    // orthographic
if (operation == "sub")     ...    // polar
}

#pragma choice operation "0"    "Use texture coordinates"
#pragma choice operation "1"    "Use parametric coordinates"
#pragma choice operation "2"    "Orthographic Projection"
#pragma choice operation "3"    "Polar Projection"
sop texture(int operation=0)
{
if (operation == 0) ...    // texture coordinates
if (operation == 1) ...    // parametric coordinates
if (operation == 2) ...    // orthographic
if (operation == 3) ...    // polar
}

These are the parameters you can use for the opfilter argument of certain pragmas.