Creating Custom Plugins

Table of Contents

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:

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
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.
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.
Particle Operators (POPs) newPopOperator () Add custom particle operators. Example: POP/POP_SpotLight.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 favour of SOHO.
Shader Clerks newShopClerk () Create new shader clerks. This function is deprecated in favour of using SOHO to evaluate clerks.
Shader Operators (SOPs) newShopOperator () Add custom shader operators.
Surface Operators (SOPs) newSopOperator () Add custom surface operators. Example: SOP/SOP_Star.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:

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_Star.C Example

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

    cd $HFS/toolkit/samples/SOP
    hcustom SOP_Star.C

hcustom generates SOP_Star.so and installs it into $HOME/houdiniX.Y/dso. That's it! The SOP Star 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 "Star" the HDK Star operator should appear. Press ENTER and click on the network to drop down a SOP Star 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_Star.so. In which case using the Makefiles from $HFS/toolkit/makefiles is recommended over using hcustom to compile and build your code. For more information, see Compiling with Makefiles

SOP_Star.C: Further Inspection

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

    void
    newSopOperator(OP_OperatorTable *table)
    {
        table->addOperator(
            new OP_Operator("hdk_star",                // Internal name
                            "Star",                    // UI name
                            SOP_Star::myConstructor,   // How to build the SOP
                            SOP_Star::myTemplateList,  // My parameters
                            0,                         // Min # of sources
                            0,                         // Max # of sources
                            SOP_Star::myVariables,     // Local variables
                            OP_FLAG_GENERATOR)         // Flag it as generator
        );
    }

When Houdini loads SOP_Star.so, it locates this function and executes it to add a the hdk_star 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 accomodate 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_star operator in the SOP Star example has a corresponding icon (SOP_hdk_star.svg) and help files (hdk_star.txt, SOP_hdk_star.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_Star.so into $HOME/houdiniX.Y/dso, here is what you can do next:

Now you have a fully-supported HDK SOP Star 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_Star.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_Star.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_star",                // Internal name
                            "Star",                    // UI name
                            SOP_Star::myConstructor,   // How to build the SOP
                            SOP_Star::myTemplateList,  // My parameters
                            0,                         // Min # of sources
                            0,                         // Max # of sources
                            SOP_Star::myVariables,     // Local variables
                            OP_FLAG_GENERATOR)         // Flag it as generator
        );
    }

Note:
To be nice to other plugins, please do not call exit() or abort() from within your exit handler.
Generated on Mon Jan 28 00:27:57 2013 for HDK by  doxygen 1.5.9