Houdini 12 VEX

Overview of how to use the VEX language compiler vcc and its pre-processor and pragma statements.

The vcc compiler compiles VEX source code into a form executable by Houdini. 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.

Command-line options

-?, -H, -h

Show help message for the compiler.

-X context_name

Display a list of a global variables, statements, and functions which are valid in the given context. The available contexts are listed in the help message (vcc -h).

-D name=def, -D name

Define a macro for the pre-processor. If no value is given with the name, the name is defined as 1.

-I path

Add the path specified to the include path (the list of directories search for files referenced by the #include directive to the pre-processor). The standard Houdini include path is under vex/include.

-o file

Output to file rather than putting compiled .vex code in the current directory. If you use stdout as the filename, the output is redirected to STDOUT.

-c

Generate a binary/encrypted version of the file . The generated .vex code will not be human-readable. You can also use the #pragma crypt pre-processor directive to only encrypt certain blocks of code.

-e file

Redirect errors from STDERR to file.

-w wlist

Suppress printing of certain warnings. wlist is a comma-separated list of warning numbers to suppress.

-q, -Q

Quiet. Lower-case q suppresses normal messages. Upper-case Q suppresses messages and warnings. Both options still print errors.

-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. Houdini can use the script to create a window to let the user modify parameters interactively (rather than editing a string). If you use -U, only the dialog script file is generated (the code is not compiled).

-g n

When generating dialog scripts with the -u or -U option, automatically creates tabs for each group of n parameters. You can manually group parameters with the #pragma group pre-processor directive.

-v

Extract parameter information and build a dialog script from compiled .vex code. You should only use this option if you can’t generate the dialog script from the original source code (the compiled code does not include any of the pragma information from the source).

Preprocessor

The compiler has a pre-processor which strips comments, expands macros, and optionally encrypts the output.

The pre-processor supports many of the usual C Pre-Processor directives:

#define name token-string

Replace subsequent uses 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 token-string during expansion.

#undef name

“Undefine” the macro so subsequent uses of name are not expanded.

#include "filename"

Inserts the contents of the file at this point in the source code. When you use quotes, the directory containing the current file is searched for filename before the standard locations (including the path).

#ifdef name

The following lines until the next #endif or else directive 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 following lines until the next #endif or #else directive will be compiled if and only if constant-expr evaluates to non-zero.

The expression can use the following operators:

  • Comparisons (==, !=, <=, >=, <, >)

  • Logical AND (&&), OR (||), and NOT (!).

  • Bitwise AND (&), OR (|), exclusive OR (^), and NOT (~).

  • Arithmetic (+, -, *, /, %).

  • Parentheses.

The expression can also use the following functions:

defined(name)

Returns 1 if the name is a defined macro, or 0 if it is not. 

#if defined(foo) && defined(fum)
environment(name)

Returns 1 if name is a defined environment variable.

access(filename)

Returns 1 if filename can be read by the application, or 0 if the file cannot be read. 

#if access("/etc/passwd")
#include </etc/passwd>
#endif
strcmp(str1, str2)

Works the same as the C/C++ function of the same name, if the two strings have the same contents, the function returns 0. Each argument should be a quoted string or a macro that expands to a quoted string. 

#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

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.

#else

The following lines until the next #endif directive will be compiled if and only if the previous #if directive evaluated to non-zero.

#endif

Marks the end of a section of conditional code. Every test directive must have a matching #endif.

#pragma ...

Specifies extended language features. See the list of pragmas.

Predefined macros

The following macros are pre-defined:

__vex

This symbol is always defined. You can use this in an if pre-processor directive to check that the program is being compiled by vcc.

__vex_major

The major version number of the compiler.

__vex_minor

The minor version number of the compiler.

__LINE__

The current line number of the source file.

__FILE__

The 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" 

printf("Starting shader %s at %s", __FILE__, __DATE__);

Code encryption

In some cases you may want to produce compiled code that is not human-readable. For example, your code may contain proprietary algorithms you don’t want to become public knowledge.

You can encrypt an entire file with the -c compiler flag, or mark a block of code to be encrypted with the #pragma crypt and #pragma endcrypt pre-processor directives: 

float
wavenoise(float height, float distance)
{
#pragma crypt

return sin(distance)*height;

#pragma endcrypt
}
When this code is compiled it is encrypted to be reasonable secure.

You may sometimes need to encrypt the proprietary information in the source code (especially since vcc doesn’t support linking in library code). You can use the vcrypt utility to encrypt the parts of the source code designated by #pragma crypt. The compiler will be able to read and compile the encrypted source code.

If the compiler detects encrypted source in its input stream, the final output will be encrypted. This means it’s not possible to reverse engineer an encrypted function by compiling it and decoding the assembler output.