#pragma c++rawstring 0|1

VEX supports C++ style raw strings. The c++rawstring pragma can be used to disable or re-enable raw string support. For example:

string a = R"(Hello world\n)";
string b = "Hello world\\n";
#pragma c++rawstrings 0        // Disable C++ style raw string support
string b = R"(This will generate an error!)";
#pragma c++rawstrings 1        // Re-enable C++ style raw string support

#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 a callback HScript script or Python function to the ‹name› parameter. When the parameter changes, Houdini executes the ‹script› string.

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

• The dialog script needs to be bound to a Houdini node (e.g. SHOP, SOP, etc.).

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

To indicate the language of the callback (hscript or python), use #pragma parmtag. If you don’t use a #pragma parmtag for a callback the default is hscript. However, the recommended method for programming callback scripts is python.

#pragma callback parm1 "message $script_parm"
#pragma parmtag parm1 script_callback_language hscript

#pragma callback parm2 "import hou; hou.ui.displayMessage(kwargs)"
#pragma parmtag initialize_menu script_callback_language hscript

• For HScript callbacks, ‹script› can be an HScript statement or the name of a script on the $HOUDINI_PATH/scripts path.

• For Python callbacks, ‹script› should be Python source code.

Houdini executes ‹script› in a context with certain variables available indicating which parameter changed.

• For HScript callbacks, Houdini creates variables such as $node containing the path to the node on which the parameter changed.

• For Python callbacks, Houdini creates a kwargs variable containing a dictionary of information about the parameter that changed.

See callback scripts for more information.

#pragma disablewhen ‹parm_name› ‹conditional_expression›

Disables ‹parm_name› when the ‹conditional_expression› evaluates to true.

#pragma hidewhen ‹parm_name› ‹conditional_expression›

Hides ‹parm_name› from the UI when the ‹conditional_expression› evaluates to true.

The syntax of the ‹conditional_expression› is the same as for the Disable when and Hide when options on parameters. See the help for conditional rules for more information on the conditional syntax.

// Disable 'samples' parameter when 'enable' parameter is toggled off
#pragma disablewhen samples { enable == 0 }

// Hide 'choice_dep1' parameter when string menu 'choice' is set to 'off'.
#pragma hidewhen choice_dep1 { choice == "off" }

#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 opscript "‹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 opscript "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

Creates a ramp parameter and connects it to shader function arguments.

• #pragma ramp_rgb ‹ramp_parm› ‹basis_parm› ‹keys_parm› ‹values_parm›

• #pragma ramp_flt ‹ramp_parm› ‹basis_parm› ‹keys_parm› ‹values_parm›

#pragma ramp_rgb color color_the_basis_strings color_the_key_positions color_the_key_values

surface
sky(
    string color_the_basis_strings[] = { "linear", "linear" };
    float color_the_key_positions[] = { 0, 1};
    vector color_the_key_values[] = { {0,0,0}, {0,0,1} };
) { ... }

Unlike most other pragmas which set up UI for parameters defined in the shader, the ramp pragma creates a new UI element in Houdini.

Default values are currently not supported by Houdini ramp parameters, so the initial values given are not passed through to the UI.

Although the values aren’t passed, the number of keys given in the values parameter will be used to set the initial number of keys in the ramp.

See ramp parameters for more information.

#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 | 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…

#pragma optable vop

This pragma can be used to indicate which operator type to generate. Currently the only supported option is vop meaning to create a VOP operator.

VOP otls generated using this option have a very specific structure:

• The inputs on the VOP are generated from non-export shader parameters

• The outputs on the VOP are generated from export shader parameters

• The parameters on the VOP are created for all non-export shader parameters, with UI generation working the same way it does for SHOP operators

• The outer code imports the shader function from an external file using the import directive

• The inner code calls this shader using the shader call syntax

Since the implementation of the shader is not actually stored in the generated VOP, it must be accessible through an external .vfl or .vex file for the VOP to work correctly. Placing the .vfl or compiled .vex file for the shader in a location accessible to the VEX search path will meet this requirement.

#pragma rename ‹oldname› ‹newname›

Specify a different name for the operator parameter than is used in the shader interface. This directive should occur after all other #pragmas referring to that parameter.

When using #pragma optable vop, this can be useful to allow a VOP input or output to use the same name as a VEX global variable, since such a name collision is valid in VOPs but not in VEX.

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 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.

#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
}

This would define a menu for the parameter “operation”. The menu would consist of 4 entries. The values for the string parameter would be one of “over”, “under”, “add” or “sub”. However, the user would be presented with more meaningful labels for the operation types.

#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.