Houdini Plugins

In addition to creating standalone applications, you can use the HDK to create custom plugins that hook into the Houdini interface. In its simplest form, a plugin is simply a library file (a .so file on Linux, .dll on Windows, .dylib on Mac OSX) which is loaded by Houdini on startup. The library can contain custom node operators, custom script commands and any other objects that are recognized by Houdini.

How does Houdini Load Plugins?

At runtime, Houdini searches for .so (.dll, .dylib) plugin files in folders determined by the Houdini Search Path. By default, Houdini searches:

./dso
$HOME/houdiniX.Y/dso
$HOME/Library/Preferences/houdini/X.Y/dso (only on Mac OSX)
/Users/Shared/houdini/X.Y/dso (only on Mac OSX)
$HSITE/houdiniX.Y/dso
$HFS/houdini/dso

When Houdini finds a plugin library, it locates and executes hook functions in the library which are responsible for registering custom HDK code with the interface.

To find out .so plugins have been attached to Houdini you can run the hscript dsoinfo command.

Here is a complete list of those registration functions:

Category	Function	Description
Agent Shape Deformers	`GUregisterAgentShapeDeformer` ()	Add custom deformers for agent shapes.
Agent Custom Data Item Types	`GUregisterAgentCustomDataItemType` ()	Add custom data types that can be attached to an agent definition.
Channel Operators (CHOPs)	`newChopOperator` ()	Add custom channel operators. Example: CHOP/CHOP_Stair.C.
Clips	`CLregisterClipReader` () `CLregisterClipWriter` ()	Register readers.writers to import/export clips in custom file formats.
Compositing Operators (COPs)	`newCop2Operator` ()	Add custom compositing operators. Example: COP2/COP2_PixelAdd.C.
Dynamics Operators (DOPs)	`newDopOperator` ()	Add custom dynamics operators. Example: DOP/DOP_GroundAndApply.C.
Dynamic Simulations	`initializeSIM` ()	Add new SIM_Data constructors to the data factory. Example: SIM/SIM_GasAdd.C.
Expressions/Commands	`CMDextendLibrary` ()	Add new commands to the hscript expression and scripting languages. Example: expr/command.C.
Handles	`newOpHandleBinding` () `newOpHandleLink` ()	Register custom operator-handles that can be bound to node parameters.
Houdini Object Model (HOM)	`HOMextendLibrary` ()	Add commands to existing HOM classes or to the hou module. Example: HOM/ObjNode_setSelectable.C.
Image Formats	`newIMGFormat` ()	Add new image file formats to be supported by Houdini. Example: IMG/IMG_Raw.C.
Mocap Stream Devices	`newMocapStreamDevice` ()	Add new device to the Mocap Stream SOP's "Device" menu. Example: mocapstream/MocapStreamRokokoHDK.C.
Modeling States	`newModelState` ()	Add new modeling states to the viewport. Example: SOP/MSS_CustomBrushState.C.
Object Operators (OBJs)	`newObjectOperator` ()	Add custom object operators. Example: OBJ/OBJ_Shake.C.
Output Driver Operators (ROPs)	`newDriverOperator` ()	Add custom output drivers or ROP nodes. Example: ROP/ROP_Dumper.C.
Render File Formats	`IFDnewRenderDefinition` ()	Add a new instantaneous frame description (IFD) file format to be supported by output drivers. This has been deprecated in favor of SOHO.
Shader Clerks	`newShopClerk` ()	Create new shader clerks. This function is deprecated in favor of using SOHO to evaluate clerks.
Shader Operators (SHOPs)	`newShopOperator` ()	Add custom shader operators.
Surface Operators (SOPs)	`newSopOperator` ()	Add custom surface operators. Example: SOP/SOP_Flatten.C.
VEX Operators (VOPs)	`newVopOperator` ()	Add custom VEX operators. Example: VOP/VOP_Switch.C.
Viewport Handles	`newHandle` ()	Add custom viewport state handles.
Viewport Rendering	`newRenderHook` () `newRenderOption` ()	Enhance the Houdini viewport by adding new options and hooks to the render pipeline.
Viewport Selectors	`newSelector` ()	Add custom states for selecting objects or geometry in the viewport. Example: SOP/MSS_BrushHairLenSelector.C.

Note that every Houdini application loads plugin libraries found in the Houdini Search Path. For example, if you create a custom material shader and build it into a plugin library, then your shader will be loaded not only by Houdini, but also by Mantra and any other tool which uses materials.

HOUDINI_DSO_PATH

To change the folders that Houdini searches when looking for custom plugins, use the HOUDINI_DSO_PATH environment variable. For example, if you want Houdini to search /usr/local/lib for your custom plugins, then set HOUDINI_DSO_PATH to /usr/local/lib. You can use the ':' character (';' on Windows) to separate multiple paths. Additionally, you can use the '@' character to refer to expansion of the HOUDINI_PATH environment variable.

For example:

export HOUDINI_DSO_PATH="/usr/local/lib:@/custom_plugins"

will force Houdini to search for plugins in the following folders:

/usr/local/lib
$HIP/custom_plugins
$HOME/houdiniX.Y/custom_plugins
$HOME/Library/Preferences/houdini/X.Y/custom_plugins (only on Mac OSX)
/Users/Shared/houdini/X.Y/custom_plugins (only on Mac OSX)
$HSITE/houdiniX.Y/custom_plugins
$HFS/houdini/custom_plugins

Furthermore, there are also the HOUDINI_IMAGE_DSO_PATH and HOUDINI_AUDIO_DSO_PATH environment variables. HOUDINI_IMAGE_DSO_PATH specifies the paths to search for plugin image readers/writers while HOUDINI_AUDIO_DSO_PATH specifies the paths to search for plugin audio readers/writers. All other types of plugins should be installed somewhere in HOUDINI_DSO_PATH.

To find out which directories will be searched, use hconfig. Type hconfig -ap in a command-line shell and it will output a description and a list of search directories for each Houdini path variable.

Building a Plugin: SOP_Flatten.C Example

To build an HDK Pugin, you can use the hcustom tool. For example, to build the SOP/SOP_Flatten.C sample, open a command-line shell and run:

cd $HFS/toolkit/samples/SOP

hcustom SOP_Flatten.C

hcustom generates SOP_Flatten.so and installs it into $HOME/houdiniX.Y/dso. That's it! The SOP Flatten is now available for use. To verify this, open Houdini and drop down a Geometry object. Dive into the geometry and press TAB in the Network Editor. Now if you type "Flatten" the HDK Flatten operator should appear. Press ENTER and click on the network to drop down a SOP Flatten node. You have now built, loaded and used your first Houdini plugin!

Of course your own HDK plugin library will probably be more complex than SOP_Flatten.so. In which case using CMake or the Makefiles from $HFS/toolkit/makefiles is recommended over using hcustom to compile and build your code. For more information, see Compiling with CMake or Compiling with Makefiles.

SOP_Flatten.C: Further Inspection

If you look at the source code of SOP/SOP_Flatten.C, you will notice that it defines the newSopOperator function:

void
newSopOperator(OP_OperatorTable *table)
{
    table->addOperator(
        new OP_Operator("hdk_flatten",              // Internal name
                        "Flatten",                  // UI name
                        SOP_Flatten::myConstructor, // How to build the SOP
                        SOP_Flatten::myTemplateList,// My parameters
                        1,                          // Min # of sources
                        1,                          // Max # of sources
                        NULL,                       // Local variables
                        0)                          // Flags such as OP_FLAG_GENERATOR
    );
}

When Houdini loads SOP_Flatten.so, it locates this function and executes it to add a the hdk_flatten operator to Houdini's internal list of SOPs.

Note

You can add multiple surface operators in a single call to newSopOperator, or any of the other hook functions for that matter.
You can have multiple hook functions in a single plugin library.

Support Files

To fully support your custom node operators, you will want to create icons and help cards for them. So you need to create additional *.png, *.svg and *.txt files to accommodate your plugin library. Here is a list of support files and where they should be installed:

Support File	Search Path	Example Destination
Operator Icon (*.svg)	`HOUDINI_UI_ICON_PATH`	`$HOME/houdiniX`.Y/config/Icons
Help Card (*.txt)	`HOUDINI_PATH/help`	`$HOME/houdiniX`.Y/help/<path/to/helpcard>
Help Card Icon (*.png)	`HOUDINI_PATH/help`	`$HOME/houdiniX`.Y/help/<path/to/helpcard>

On Mac OSX, you should install the support files into $HOME/Library/Preferences/houdini/X.Y instead of $HOME/houdiniX.Y.

For more information on how to write help documentation for your custom operators, please see HDK > Houdini Operators > Building Custom Operators > Help.

For more information on how to create an operator icon, please see HDK > Houdini Operators > Building Custom Operators > Icon.

The hdk_flatten operator in the SOP Flatten example has a corresponding icon (SOP_hdk_flatten.svg) and help files (hdk_flatten.txt, SOP_hdk_flatten.png). However, you have probably already noticed that after installing the example using hcustom, no icon or help card appeared in Houdini. That is because hcustom only installs the plugin library, not any of the support files. You need to manually copy the additional files into the Houdini Search Path in order for them to be put into action. Assuming that you have installed SOP_Flatten.so into $HOME/houdiniX.Y/dso, here is what you can do next:

Copy SOP_hdk_flatten.svg to $HOME/houdiniX.Y/config/Icons.
Copy hdk_flatten.txt to $HOME/houdiniX.Y/help/nodes/sop.
Copy SOP_hdk_flatten.png to $HOME/houdiniX.Y/help/nodes/sop.

Now you have a fully-supported HDK SOP Flatten example installed!

Setting Tag Information

The sesitag program displays information about custom .so files. There is a little information automatically installed in the .so file for you. This includes the date that the .so file was created, and also the person who did the compiling. If you want to add some other specific information, you can do this by setting the SESI_TAGINFO environment variable before running hcustom.

For example, in a bash shell on Linux, you can do:

export SESI_TAGINFO="Produced by: Side Effects Software"

hcustom SOP_Flatten.C

Licensing Your Plugin

If you plan to share your plugin with the Houdini community (i.e. on your personal website or on the Houdini Exchange), then you may want to add licensing to your library. One way to do this is by using the UT_Exit::addExitCallback HDK function. So when your plugin is loaded, it can check out a license, and when Houdini quits, it can return the license.

Here is an example of how you could add licensing to the SOP/SOP_Flatten.C sample:

#include <UT/UT_Exit.h>
static void
dsoExit(void *)
{
    // Return the checked out license.
    // You must implement returnLicense()!
    returnLicense();
}
void
newSopOperator(OP_OperatorTable *table)
{
    // Check out a license.
    // You must implement checkoutLicense()!
    if (!checked_out_license && checkoutLicense())
    {
        // Register a callback which is invoked when Houdini quits.
        UT_Exit::addExitCallback(dsoExit);
        checked_out_license = true;
    }
    table->addOperator(
        new OP_Operator("hdk_flatten",              // Internal name
                        "Flatten",                  // UI name
                        SOP_Flatten::myConstructor, // How to build the SOP
                        SOP_Flatten::myTemplateList,// My parameters
                        1,                          // Min # of sources
                        1,                          // Max # of sources
                        nullptr,                    // Local variables
                        0)                          // Additional flags
    );
}

Note: To be nice to other plugins, please do not call exit() or abort() from within your exit handler.

Table of Contents