[SESI logo]

VEX Language Reference - Version 6.5

Side Effects Software Inc. 2003

VEX Compiler Reference

  • Basic Language Information
  • Language Structure
  • The Pre-Processor
  • VCC Options
  • Encryption of source
  • Data Types
  • Type Casting
  • Pragma Definitions

  • Basic Language Information

    The compiler (vcc) compiles VEX code into an "executable" form. VEX is loosely based on the C language but takes pieces from C++ as well as the RenderMan(tm) shading language.

    Unlike C or C++ VEX has different "contexts" for compiling. These contexts define how the function is to be used. For example, one context is the "COP" context. Functions written in this context can only be used to do image compositing. The "POP" context is a different context where functions are used to define the motion or attributes of particle systems. While a COP function processes pixel color information, a POP function deals with particle velocities and positions. Therefore, the information and functions required for each "context" have to be slightly different.

    Each VEX context has different global variables as well as a special set of runtime functions suited to the context.

    It is also possible to define user functions which return one of the standard VEX types (or void). These functions must be declared before they are referenced. The functions are in-lined automatically by the compiler, meaning that recursion is not possible.

    Like with the RenderMan(tm) shading language, parameters to user functions are always passed by reference. This means that modifications in a user function affect the variable the function was called with.

    The RenderMan(tm) shading language has certain restrictions on user functions which do not exist in VEX. It is possible to have multiple return points from within user functions. It is also possible to reference global variables from within user functions without requiring "extern" declarations. Although it is possible to reference global variables, this practice is discouraged since this limits the function to be used solely within the context containing the global variables referenced. Since parameters are passed by reference, it is probably better coding practice to pass references for global variables to be modified within a user function.

    The compiler expects that each source file contains one (and only one) context function definition. Any number of user functions can be defined.

    Parameters to context functions are dealt with in a special way with VEX. It is possible to override a parameter's value using a geometry attribute with the same name as the variable. Aside from this special case, parameters should be considered "const" within the scope of the shader. This means that it is illegal to modify a parameter value. The compiler will generate errors if this occurs.

    The RenderMan(tm) style of parameter declaration is used by VEX. This is similar to the ANSI C/C++ style of parameter declarations with some minor differences for context functions.

    1. Parameters to a context function must be declared with default values. This does not apply to user functions.
    2. Parameters of the same are declared in a comma separated list without needing to re-declare the type.
    3. Different type declarations must be separated by a semi-colon.
    Some examples of function declarations are:

    void user_function1(float a, b; vector c) {...} cop cop_function(float a=0, b=0; vector c=1) {...} pop pop_function(string a="string1", b="string2"; float c = 1, d = 1.3; vector e={1,2,3}, f={-1,0,.1}) {...}

    Language Structure

    The structure of VEX is similar to the structure of a C program. A function is declared and consists of statements which operate on variables. Expressions are defined using the standard C operators which have the precedence as follows:

    Operator Associativity Function
    ( )    . left to right Function call or expression grouping, Structure member
    ! ~ + - ++ -- (type) right to left Logical negation, ones complement, unary plus, unary minus, increment, decrement, explicit type cast
    * / % left to right Multiplication, Division, Modulus
    + - left to right Addition, Subtraction
    < > <= >= left to right Less than, Greater than, Less or equal, Greater or equal
    == != left to right Equal, Not equal
    & left to right Bitwise and
    ^ left to right Bitwise exclusive or
    | left to right Bitwise or
    && left to right Logical and
    || left to right Logical or
    ? : left to right Conditional
    = += -= *= /= %= &= ^= |= right to left Assignment (or short-hand assignment)
    , left to right Comma

    Statements

    The basic control statements in VEX are:
  • { }

    Multiple statements may be grouped together to form one statement by enclosing the statements in-side of curly braces.

  • if-else

    One of two statements will be executed.
    if (boolean expression) statement [ else statement ] where statement is either a single statement or a series of statements enclosed by curly braces ({ }). The else clause is optional.

  • while

    A statement can be executed repeatedly with the while construct. The statement is repeated as long as the boolean expression is true. while (boolean expression) statement

  • for

    Like the while statement, the for statement can execute a statement repeatedly. for (expr; boolean_expression; expr) statement The first expression is executed once before the loop is entered. The boolean expression is evaluated before the execution of the statement. The statement is evaluated only if the boolean expression is true. The second expression is evaluated after the statement.

  • break

    A for or while loop can be terminated by using the break statement. Unlike the C language, there is currently no continue statement.

  • return

    A user function (not a context function) can terminate execution at any time by using the return statement. If the function is non-void (i.e. returns a value), then the value must be specified. return expr
  • Some contexts have additional statements (i.e. the surface context adds an illuminance statement to the language). Please see the context specific information for further details.


    Compiler Pre-Processor

    The compiler has a pre-processor which is responsible for macro expansion as well as stripping out comments. Comments can be in either the C form (/* */) or the C++ form (//). The pre-processor is also responsible for handling encryption of source code. The pre-processor supports many of the standard C Pre-Processor directives:
  • #define name token-string
    Replace subsequent instances of name with token-string.
  • #define name(arg,...,arg) token-string
    Replace subsequent instances of name with token-string. Each argument to name() is replaced in the token-string during expansion.
  • #undef name Un-define the name macro
  • #include "filename"
    #include <filename>
    Include the contents of the filename specified at this point in the compilation. When the quoted notation is used, the "current" directory is searched before the standard locations (include path). The "current" directory is the location of the current file being processed.
  • #ifdef name
    The lines following will be compiled if and only if name is a defined macro.
  • #ifndef name
    The lines following will be compiled if and only if name is not a defined macro.
  • #if constant-expr
    The lines following will be compiled if and only if the constant-expr evaluates to non-zero. The expression may contain the operators:
  • Logical And/Or/Not (&&, ||, !)
  • Equality Operators (==, !=, <=, >=, <, >)
  • Bitwise And/Or/Exclusive Or/Not (&, |, ^, ~)
  • Arithmetic Operators (+, -, *, /, %)
  • Parentheses.
  • Expressions are evaluated from left to right (unlike the ANSI C standard of right to left). As with the ANSI pre-procssor, all numbers must be integers.

    As well, there are four special functions defined(name), environment(name), access(name) and strcmp(str1, str2). defined will return 1 if the name is a defined macro or 0 if it is not. environment will return 1 if there is an environment variable or 0 if not. For example, to test whether symbols foo and fum are defined and the system variable HFS is also defined:

    #if defined(foo) && defined(fum) && environment(HFS) The strcmp function works in the same fashion as the C/C++ function of the same name. If the two strings are lexigraphically equal, the result of the strcmp() function is zero. Each argument to strcmp() should be either a quoted string or a macro which expands to a quoted string. For example:
    #define VALUE "foo" #if strcmp(VALUE, "bar") != 0 This statement is false since "foo" != "bar" #endif #if !strcmp(VALUE, "foo") This statement is TRUE since strcmp("foo", "bar") == 0 #endif The access function works in a similar fashion as the UNIX system call of the same name. It will return 1 if the filename specified can be read by the running application. If the file cannot be read, it will return 0. For example:
    #if access("/etc/passwd") #include </etc/passwd> #endif
  • #else
    The lines following will be compiled if and only if the preceding test directive evaluated to zero.
  • #endif
    Ends a conditional secion of code begun by a test directive (#if, #ifdef, #ifndef). Every test directive must have a matching #endif
  • #pragma crypt
    The following lines should be encrypted
  • #pragma endcrypt
    End of an encryption block.
  • Symbols can be defined using the -D option of vcc.

    The compiler (vcc) has several pre-defined macros which can be used for compiling.

  • __vex
    This symbol is always defined so that you know the source is being compiled by vcc.
  • __vex_major
    The major version number of the compiler being used to compile.
  • __vex_minor
    The minor version number of the compiler being used to compile.
  • __LINE__ The current line of the source code being compiled.
  • __FILE__ The current file being compiled.
  • __DATE__ The current date (as a quoted string). Example: "Dec 31 1999"
  • __TIME__ The current time (as a quoted string). Example: "23:59:59"

  • Compiler Options

    The VEX compiler (vcc) is capable of compiling VEX code, generating dialog scripts for VEX functions and also giving quick help by listing the global variables and functions available in any given context.

  • -?, -H, -h
    Show help message for the compiler

  • -X context_name
    Rather than compiling code, this option will display the list of global variables, VEX constructs and all functions available for the context specified.

  • -D name=def, -D name
    Define a name for the pre-processor. If no value is given with the name, the name is defined with a value of 1.

  • -I path
    Add the path specified to the include path for the pre-processor. By default, the standard Houdini path is searched for include files (under vex/include).

  • -o file
    By default, the compiler will generate the compiled .vex code in the current directory. This option allows you to specify an alternate location and name for the output.

    It is possible to specify "stdout" as a filename. In this case, output will be generated to the stdout file descriptor rather than a disk file.

  • -c
    Generate a binary/crypted version of the function. This means that the generated .vex file will not be readable by a human. However, it can still be used by Houdini. See also #pragma crypt.

  • -e file
    Send error messages to this file rather than stderr.

  • -w wlist
    The -w will supress the printing of the specified warnings. The wlist should be a comma separated list of warning numbers to suppress.

  • -q, -Q
    The -q will cause the compiler to omit printing of messages. The -Q option will supress both messages and warnings. Errors will still be printed out with either option.

  • -i
    Make the generated .vex code more readable by indenting the output based on nesting.

  • -u, -U
    Generate a corresponding dialog script for the VEX function. This dialog script will be usable by Houdini to let the user modify parameters interactively (rather than editing a string). If the -U option is specified, only the dialog script file will be generated, compilation of the code will be bypassed.

  • -g nparms
    When generating dialog scripts (with the -u or -U option), it is possible to "auto-group" parameters in to groups of N parameters. If no groups are specified using the #pragma group directive, then this option will force groups to be created with a maximum of nparms per folder tab.

  • -v
    If you only have compiled VEX code, this option can be used to extract the parameter information and build a dialog script for the compiled code. Warning: All pragma information is lost in the compiled code so it is much better to generate dialog scripts from the source code where possible.


  • Encryption

    In some cases, VEX code may contain proprietary algorithms which the author doesn't wish to become public knowledge. The compiler has a special set of directives to turn on/off crypting (#pragma crypt, and #pragma endcrypt). For example: float wavenoise(float height, float distance) { #pragma crypt return sin(distance)*height; #pragma endcrypt }
    When this code is compiled, the output of the compiler will be encrypted so that the code is reasonably secure. However, since VEX does not support dynamic linking (i.e. linking of pre-compiled code), there is a utility vcrypt which will encrypt the specific portions of the source files. The compiler can still read these encrypted files, however, the code contained will be secure.

    If the compiler detects encrypted source in its input stream, then the final output will be encrypted. This guarantees the integrity of the encryption (meaning it's not possible to reverse engineer an encrypted function by compiling it and decoding the assembler output). To generate encrypted object code, use the -c option on vcc.

    The usage of the vcrypt program is:

    Usage: vcrypt [source [destination]] If no source and destination files are specified, then input is read from stdin and output to stdout. If no destination file is specified, the crypted code is output to stdout.

    The #pragma crypt does not require a closing #pragma endcrypt. The two directives can be thought of as turning encryption on and off.

    It is also possible to generate encrypted compiled code by using the -c option on the vcc command line.


    Data Types

    VEX supports a fixed set of data types and does not allow user data types to be defined. As well, arrays are not currently supported within VEX. The data types supported by VEX are:

    Type Name Definition Example
    int Integer values 21, -3, 0x31
    float Floating point scalar values 21.3, -3.2, 1.0
    vector Three floating point values. These values can be used to represent positions, directions, normals or colors (RGB or HSV) {0,0,0}, {0.3,0.5,-0.5}
    vector4 Four floating point values. These values can be used to represent positions in homogeneous coordinates, colors (RGBA) {0,0,0,1}, {0.3,0.5,-0.5,0.2}
    matrix3 Nine floating point values representing a 3D rotation matrix or a 2D transformation matrix.
    matrix Sixteen floating point values representing a 3D transformation matrix.
    string A string of characters. "hello world", "Mandril.pic"

    The standard C operations are defined (with the standard precedence order). There are several special exceptions to the C standard.

  • Multiplication is defined between two vectors or points. The multiplication performs an element by element multiplication (rather than a dot or cross product).

  • The dot operator (.) is defined only for vector and vector4. The structure names have been arbitrarily chosen to be:

  • .x or .r to reference the first data element.
  • .y or .g to reference the second data element.
  • .z or .b to reference the third data element.
  • .w or .a to reference the fouth data element (for vector4 types only).
  • Many operators are defined for non-scalar data types (i.e. a vector multiplied by a matrix will transform the vector by the matrix).

  • Constants are declared in a similar fashion to C.

    1, 392, -43 integer constants
    1.0, 3.14, -1e3 float constants
    {1,2,3}, {0,1,0} vector constants
    {1,2,3,4}, {0,1,0,1} vector4 constants
    { {1,0,0}, {0,1,0}, {0,0,1} } matrix3 constant
    { {1,0,0,0}, {0,1,0,0}, {0,0,1,0}, {0,0,0,1} } matrix constant
  • Please see the Quick Reference guide for a more complete guide to operators and functions.


    Type Casting

    There are two separate ways to cast a variable or return type in VEX. VEX is a polymorphic language, meaning that the same function can have different signatures to specify different calling syntaxes. For example, the noise() function can take different arguments to generate 1D, 2D, 3D, or 4D noise (noise(float), noise(float, float), noise(vector), noise(vector4)). However, unlike similar languages (i.e. C++), the return code is also considered in constructing the signature of the function. This is an open ended problem, so in many cases, it is possible to give the compiler a "hint" as to which version of the function should be used.

    This is done by function casting which simply gives the compiler a hint as to which version of the function to use. For example:

    float n; n = noise(noise(P)); As stated above, the noise function can take different sets of parameters. However, there are also versions of the noise() function which return different types. In particular, the noise() function can return either a float or a vector.

    When generating code for the above fragment, the compiler has a choice for the nested noise function. It can choose from:

    1. float noise(vector)
    2. vector noise(vector)
    Both of these forms of the noise() function are valid, so the compiler has to guess which version to use. When it makes a guess, it will print out a warning: WARNING (2005) Implicit casting failed for noise - guessing noise@VF - please try to use an explicit cast

    To eliminate this warning, we can use an explicit function cast which takes the form:

    n = noise( vector(noise(P))); This form of cast generates no additional code, it just tells the compiler which version of the function to use.

    The other form of casting involves additional code generation and therefore is less desirable than the previous function casting. The second form is the form which is used in C and C++.

    n = noise( (vector) noise(P)); This form will cause the compiler to guess the return code and then take the returned value and cast it to the type specified. The compiler has some heuristics to attempt to minimize the cost of functions, so in the above case, the nested noise() function will return a float, which is then cast to a vector. This is most likely not the desired behaviour, and is also more expensive.

    However, the second form of casting is occasionally necessary. Consider the following example:

    int a, b; float c; c = a / b; In this case, the compiler will generate the instruction for integer division. If the floating point result is desired, then, it is important to cast the integers to floats. This is done using the second form.

    c = (float)a / (float)b; This, however, will generate additional instructions to perform the cast of the variables.

    The general rule of thumb is to try to perform function type casting as much as you want. There is no run-time cost to this casting and it ensures correct code generation. However, it is also a good rule of thumb to avoid variable casting since this can incur a run-time cost.


    VEX Compiler Pragmas

    The VEX compiler (vcc) supports pragmas for automatically building UI dialog scripts. These pragmas are typically ignored unless the -u option is specified on the vcc command line. The pragma's allow specification of help, hints for how to represent the parameter, improving readability etc.

    The pragmas supported are:

  • #pragma callback
  • #pragma crypt
  • #pragma help
  • #pragma info
  • #pragma name
  • #pragma label
  • #pragma parmhelp
  • #pragma hint
  • #pragma range
  • #pragma choice
  • #pragma disable
  • #pragma group
  • #pragma rendermask
  • #pragma export
  • #pragma bindhandle
  • #pragma bindhandlereserved
  • #pragma bindselector
  • #pragma bindselectorreserved
  • #pragma opname
  • #pragma oplabel
  • #pragma opshader
  • #pragma opicon
  • #pragma opmininputs
  • #pragma opmaxinputs
  • #pragma inputlabel

  • #pragma callback name script

    If this pragma is a little on the esoteric side. It allows an hscript command file to be bound to the parameter specified by name. If the UI dialog script is bound to a Houdini operator (i.e. a SHOP, SOP, POP, etc.), when the parameter is changed, the script specified will be executed.

    Because of architectural limitations in Houdini, certain criteria need to be met for this #pragma to work:

    1. The dialog script needs to be bound to a Houdini Operator (i.e. SHOP, POP, SOP, etc.)
    2. The parameter needs to be either a toggle button, or have a menu bound to it (see #pragma hint and #pragma choice).
    Example: #pragma callback initialize_menu "sop/initialize_sop.cmd" The standard $HOUDINI_PATH/scripts path is searched for the script to run. If the script is found, then a local variable $script_parm will be set to the name of the parameter being changed, and the script will be executed. For example, with the above specification, the following hscript commands would be run: set -l script_parm initialize_menu source -q sop/initialize_sop.cmd


    #pragma crypt

    If this pragma is found in the source, the generated VEX bytecode will be encrypted. This prevents users of the source from reverse engineering the object code.


    #pragma help "text"

    The help pragma will add the text argument to the help in the dialog script. This can be used to give hints to users of the VEX code as to what parameters mean, what the code is useful for, etc.

    Example:

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

    #pragma info "text"

    Like the help pragma, this information is displayed in the help for the dialog script. However, the info text shows up in a separate section of the help at the very beginning of the help display. This is intended to be used to specify any copyrights, version information, etc.

    Example:

    #pragma info "Created by Bob Loblaws - (c)1999" Caveats: At the current time, only SHOPs display the info text.

    #pragma name "text"

    This defines the label which appears in the UI. This pragma is typically not required since the label is now usually defined in the operator table definition.

    Example:

    #pragma name "Shiny Marble"

    #pragma label parameter_name "text"

    This allows the definition of a more descriptive label for a parameter.

    Example:

    // The "amp" parameter represents noise amplitude #pragma label amp "Noise Amplitude" displacement bumpy(float amp=0) {...}

    #pragma parmhelp parameter_name "parameter help text"

    This allows the definition of a help string that appears when the user hovers the mouse over the specified parameter label.

    Example:

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

    #pragma hint parameter_name hint_type

    This pragma gives more information about what a parameter is meant to represent. For example, in VEX, a vector may represent a point in space, a color or a direction. This hint allows precise definition of what a parameter is intended to be used for. The UI generated for the parameter will then reflect this hint.

    Hint Type Meaning
    none No hint is available.
    toggle The integer (or float) parameter represents a toggle button. The UI will generate a toggle button for this parameter and generate values 0 for off and 1 for on.
    color The parameter represents a color. The UI will generate color sliders for this parameter.
    direction The parameter represents a direction vector. The UI will generate a direction gadget for this parameter.
    vector The parameter represents a 3 dimensional vector in space. The UI for this is the same as the default UI for a parameter with 3 floats. The difference is that the channel names for this parameter will end with x, y, z instead of 1, 2, 3.
    vector4 The parameter represents a 4 dimensional vector in space. The UI for this is the same as the default UI for a parameter with 4 floats. The difference is that the channel names for this parameter will end with x, y, z, w instead of 1, 2, 3, 4.
    uv The parameter represents a pair of uv coordinates. The UI for this type of parameter will be two entry fields instead of three. The third value passed to the VEX function will always be 0. Also, the channel names for the parameter will end with u, v instead of 1, 2.
    uvw The parameter represents a set of uvw coordinates. The UI for this is the same as the default UI for a parameter with 3 floats. The difference is that the channel names for this parameter will end with u, v, w instead of 1, 2, 3.
    angle The parameter represents a direction vector. The UI will generate an angle gadget for this parameter.
    file The parameter represents a disk file. A file prompter will be available for this parameter.
    image The parameter represents an image on disk. A file prompter will be available for this parameter. Only recognized image files will be displayed in the file prompter.
    geometry The parameter represents an image on disk. A file prompter will be available for this parameter. Only recognized geometry files will be displayed in the file prompter.
    hidden There will be no UI generated for this parameter. This is quite useful when a parameter is intended to be overridden by a geometry attribute.
    oppath [opfilter] The parameter represents a path to an object. Optionally, an opfilter can be specified to limit the types of operators which can be selected. The current list of strings handled for opfilters are:
    obj Any Object
    sop Any SOP
    pop Any POP
    chop Any CHOP
    cop Any COP
    vop Any VOP
    rop Any Output Driver

    Furthermore, it is possible to choose a specific type of object using an opfilter of:

    obj/geo Any Geometry Object
    obj/null Any Null Object
    obj/light Any Light Object
    obj/camera Any Camera Object
    obj/fog Any Fog Object
    obj/bone Any Bone Object

    Or a specific type of SHOP, by using one of:

    shop/surface Any Surface SHOP
    shop/displace Any Displacement SHOP
    shop/interior Any Interior SHOP
    shop/light Any Light SHOP
    shop/shadow Any Shadow SHOP
    shop/fog Any Atmosphere SHOP
    shop/photon Any Photon SHOP
    shop/image3d Any Image3D SHOP

    Example:

    #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 range parameter_name min_value max_value

    This pragma defines an ideal range for a parameter. The slider generated for the float value will have the range specified by the minimum and maximum values specified. This works for both integers and floating point parameters.

    Example:

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

    #pragma choice parameter_name "value" "label"

    #pragma choicereplace parameter_name "value" "label"

    #pragma choicetoggle parameter_name "value" "label"

    When a choice pragma is defined for a parameter, the parameter is then represented as a menu of all the choice pragmas defined for that parameter. This is an exclusive list and there is no easy way for a user to set the parameter to something other than a choice in the list.

    If the choicereplace pragma is used, the menu is non-exclusive, and the user can choose to either use the menu or enter a different text value. The choicetoggle also creates a non-exclusive menu, but unlike the choicereplace menu selecting an item from a toggle menu will add it to the string if it is not already present, or remove it from the string if it is there. If not all menu items are specified with the same pragma, the menu style specified in the first menu item is used.

    This can also be used to define integer values. However, the integer values ignore the labels and instead number the choices in order from 0 to N (where N is the number of entries in the menu). The choicereplace and choicetoggle pragmas can only be used for parameters with string values.

    Example:

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

    #pragma disable ParmToDisableName ControlParmName ControlValue [ControlParmName2 ControlValue2...]

    This pragma allows you to define simple rules for disabling a parameter based on the values of other parameters in the VEX function. It takes the name of the parm to potentially be disabled, followed by at least one pair of a control parm name and a value. If more than 1 pair is in the pragma, all of the conditions must be met (like an AND function). This pragma may be called several times on the same parameter - if any of the conditions are met, the parameter will be disabled (like an OR).

    Disabling parameters is a good way to let the user know what context a given parameters is valid in (ie, "Number of Subdivisions" is only valid when "Subdivide" is on).

    Examples:

    // 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 group group_name parameter_name1 parameter_name2 ...

    This pragma allows you to group like parameters into a single folder in the dialog box. There can be multiple pragmas for each group. Example: // Group Ka, Kd, Ks, roughness into a folder called BRDF #pragma group BRDF Ka Kd Ks #pragma group BRDF roughness

    #pragma rendermask (VMantra | RIB | MI)

    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. At the time that this document was written, the different renderers which support SHOPs are:

  • MI - Output generation for MentalRay compliant renderers.
  • RIB - RIB generation for RenderMan compliant renderers.
  • VMantra - The version of mantra which uses VEX for shading.
  • OGL - OpenGL(tm) rendering. This is a special renderer which automatically adds itself to most render masks. There is currently no way to prevent this.

  • #pragma export parmName (none | dialog | all)

    When generating dialog scripts for OPs, it is possible to "export" parameters to the operation parameters dialog, or the operation controls bar above the viewport. There are three levels of export for parameters:
    1. 0 or none - the parameter will appear only in the standard dialog box for the OP.
    2. 1 or dialog - the parameter will appear in the operation parameters dialog for the OP.
    3. 2 or all - the parameter will appear in both the operation parameters dialog and the operation controls bar for the OP.
    See also the hidden hint.

    #pragma bindhandle channel_name h_name h_label h_index h_settings

    When generating dialog scripts for OPs, it is possible to bind handles to specific parameters by default. This can, of course, be overridden by users, but defaults can be specified without modifying the OPbindings file. The bindhandle pragma expects five arguments:
    1. The name of the channel in the VEX operator that should be bound to the handle.
    2. Handle name. This is one of the pre-defined Houdini handles (i.e. ladder). Please see run omls in Houdini for a full list of available handles.
    3. Label. A brief description of the handle.
    4. Handle index. Many handles (for example xform) have multiple parameters associated with them. This allows you to choose which handle parameter gets bound to the VEX parameter.
    5. Default Settings. An optional handle-specific string that can be used to set some default behavior for the handle.
    Examples: #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:

    1. The entity to select. Please run the omsls command from within Houdini for a complete list of possibilities.
    2. A label. This is a brief description of the selector.
    3. A user prompt. This is the description which is presented to the user when they are required to select geometry.
    4. A primitive mask. This is a pattern which allows selection of specific primitive types. The list of possible primitive types are:
    5. all - Select all primitive types
    6. face - Select polygons, NURBs or Bezier curves.
    7. surface - Select mesh, NURBs or Bezier surfaces
    8. quadric - Select primitive circles, spheres or tubes.
    9. poly - Select polygons
    10. nurbscurve - Select NURBS curves
    11. bezcurve - Select Bezier curves
    12. mesh - Select meshes
    13. nurbs - Select NURBS surfaces
    14. bezier - Select Bezier surfaces
    15. circle - Select primitive circles
    16. sphere - Select primitive spheres
    17. tube - Select primitive tubes
    18. meta - Select metaballs
    19. particle - Select particle systems
    20. The primitive types can be combined in standard Houdini grouping mechanisms. For example:
    21. all,^p* - Select all primitive types except polygons and particles.
    22. face,surface - Select face and surface primitives.
    23. *,^quad*,^meta - Select any primitive but quadrics or metaballs.
    24. Dragging. This can be either 0 or 1 to allow the selection to be modified without forcing the user to hit the right mouse button to complete the selection. For example, if this parameter is set to 1, the user would be able to click on a primitive and start moving the mouse. The selection would be completed and the mouse movement would be passed to the operator handles.
    25. Group menu parameter. This parameter is used to indicate what geometry type the selection group will have. Typically this will point to a menu for choosing "Points", "Primitives", or "Guess from group". Please see the OMbindings file for the Blast SOP.
    26. Asterisk selects all. This can be either 0 or 1, and indicates whether the selector needs to set the selection string to "*" to indicate that all geometry was selected. If this parameter is 0, the selector assumes that an empty group parameter indicates that all geometry was selected.
    For per-parameter selectors, the bindselector pragma expects 10 arguments:
    1. The VEX parameter to bind the selector to.
    2. The entity to select.
    3. A label.
    4. A description.
    5. A primitive mask.
    6. Dragging.
    7. Group menu parameter.
    8. Asterisk selects all.
    9. Input Index. When the user selects geometry, the selector must connect the output from the selected operator to the input of this operator. This parameter specifies the index of the input number where the operator should be connected. This parameter can be -1 if the selector needs to connect multiple input operators into this operator.
    10. Input Required. Whether the user is required to select geometry for this input.
    Examples: #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 pragma allows you to bind selectors to reserved parameters in your scriped operators. The arguments to this pragma are the same as those passed to the bindselector pragma used to bind a selector to a parameter defined in the dialog script. The only difference is that the parameter name argument must specify a reserved parameter.

    #pragma opname "text"

    This pragma lets you specify the internal operator name that should be assigned to this operator type. By default the name of the source file is used. Using the -n command line option to vcc overrides this pragma.

    Example:

    #pragma opname "myshop"

    #pragma oplabel "text"

    This pragma lets you specify the descriptive name that should be assigned to this operator type. This is the name that appears in the operator toolbars. By default the operator name is used. Using the -N command line option to vcc overrides this pragma.

    Example:

    #pragma oplabel "My New Shop"

    #pragma opshader "text"

    If this operator type represents a shader that can be used from renderers other than mantra, this pragma lets you set the name of the shader file that these other renderers should look for. By using this pragma, the operator type name does not need to match the shader file name. The -S option on the vcc command line overrides this pragma.

    Example:

    #pragma opshader "rman_myshader"

    #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. The -C option on the vcc command line overrides this pragma.

    Example:

    #pragma opicon "SHOP_plastic"

    #pragma opmininputs num

    For VEX operator types, this pragma 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 to vcc overrides this pragma.

    Example:

    #pragma opmininputs 1

    #pragma opmaxinputs num

    For VEX operator types, this pragma 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 to vcc overrides this pragma.

    Example:

    #pragma opmaxinputs 4

    #pragma inputlabel inputnum "Input Label"

    For VEX operator types, this pragma sets the label for one of the operator inputs. 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 for which you want to set the label. The first input is specified with inputnum = 1.

    Example:

    #pragma inputlabel 1 "Geometry to Modify"

    Copyright © 1999-2003 Side Effects Software Inc.
    477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7