Houdini 12 Compositing

You can create a custom compositing operation with VOPs or raw VEX. Custom COPs created with VEX are very similar to other generators and filters, with a few extra features:

  • All VEX-based generators have the same characteristics as normal generators .

    Generators do not have inputs. You set the image size, data format, frame range and planes in the node.

  • VEX-based filters inherit sequence settings (image size, data format, frame range, planes) from their first input.

    All VEX-based filters have a mask input to control the effect of the filter per-pixel.

VEX-based compositing operators cannot:

  • Change any of the sequence parameters: the length or start of the sequence, the resolution or the data format of existing planes.

  • Write to multiple output pixel locations at a time.

  • Do more than one pass over the data (multi-pass algorithms).

  • Efficiently use globally computed data (like the average luminance of the image). The node runs the VEX script for each pixel, so the global data would need to be recalculated for each pixel.

Key concepts

  • A VEX/VOP COP must write to one of the following variable sets: R, G, B, A or Cr, Cg, Cb, C4. R, G, B, A map directly to the Color plane’s C.r, C.g, C.b components and Alpha. Cr, Cg, Cb, C4 map to the currently processed plane’s components.

  • All of these variables can be read as well as written. For generators, they will contain black. For filters, they will contain the value of the corresponding image plane in input #1.

  • X,Y return the position of the current pixel in 0-1 notation. IX,IY return the position of the current pixel in 0 to XRES-1, 0 to YRES-1.

  • Often you need to process different planes differently (like Color and Alpha). You can do this by testing the PNAME variable (current plane name) against the planes you need to process (colorname, alphaname, etc.).

To read other pixel locations, image planes, frames, or other inputs:

VOPs

The COP Input VOP allows you to pick the input, plane, frame and pixel location of the pixel you want to read. You can also specify how it is filtered - no filtering (fast), bilinear (for sub-pixel accuracy) and full filtered (slow, but good for continuous transforms or deformations)

VEX

The cinput, binput, and finput functions correspond to the no-filtering, bilinear and full filtered input functions. VEX also has a ninput function, which returns a 3×3 kernel of the pixel and its neighbors in a matrix. This is done per-component, so for color, you would need to call this 3 times.

Create a custom COP from VOPs

  1. Use the tab menu to create a VOP COP2 Generator Definition or VOP COP2 Filter Definition (in the Managers sub-menu).

  2. Go inside the node to the VOP network.

  3. Create a Global Variables VOP. You will probably need to use some of the variables in your definition.

  4. If you want to affect Color/Alpha only, use the R,G,B,A outputs. If you want to generally affect any plane or a specific plane, use Cr,Cg,Cb,C4. You can read the corresponding input values from R,G,B,A or Cr,Cg,Cb,C4 (even though you can’t write to both at once, you can still read from any of them).

  5. To create parameters, connect Parameter VOPs to those inputs you want to control.

  6. Once you've set up the VOP network, return to the VOP COP2 Generator/Filter Definition node. Change the name of the definition to the human readable name for the new operator type, and the internal name of the operator definition. You can also reorder the parameters as they will appear in the new node’s parameter editor interface.

  7. Create an instance of the new operator and test it.

Create a custom COP from VEX code

  1. Create a new text file with the .vfl extension (for example, myFunction.vfl). We recommend the name of the file match the name of the VEX function inside.

  2. When writing the VEX function, use the context name cop2.

  3. Write the results of your function to R,G,B,A or Cr,Cg,Cb,C4.

  4. To compile the COP to an OTL (the easiest way to use the code in Houdini), use the following command line: 

              vcc -l myfunction.otl myfunction.vfl

    This will produce an operator type library (OTL) for your new COP, which you can then merge with other OTL libs (like OPlibCOP2.otl, using hotl) or install directly in Houdini.

Note

Arguments to the function show up as parameters for the new node type. You can use #pragmas to set the type, name, range, menu items and disable behavior of the parameters.

Getting data from the COP inputs into VEX/VOPs

If the first input has a plane which matches a VEX parameter’s name, the node will use the input plane as the parameter’s value (effectively overriding the parameter). The node evaluates the overloaded parameter from the plane on a per-pixel basis.

For example, if the COP has the following planes:

  • C{r,g,b}

  • A

  • fogdens

...and it is fed into a VEX Fog COP, the fog density will be determined at each pixel by the fogdens plane, since the Fog Density parameter’s channel name is fogdens.

Creating new planes from exported VEX variables

If the VEX script for a custom COP exports a variable, Houdini creates a new plane with the same name as the VEX parameter. If that plane already exists in the input sequence, it is replaced by the VEX version. Each VEX type maps to a COP data type:

VEX Type COP Type
int Single channel 32 bit integer
float Single channel 32 bit float
vector 3 channel 32 bit float
vector4 4 channel 32 bit float
matrix3 3 element array of 3 channel 32 bit floats
matrix4 4 element array of 4 channel 32 bit floats

New planes are created as 32 bit floating point (except for int planes, which are 32 bit int) and their vector size is determined by the type of variable exported (float, vector, vector4).