[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Houdini

Areas of Customization

Houdini has several areas of customization. Without the developer toolkit, it is possible to write scripts or even customize the UI. However, sometimes, this is not enough. The development toolkit allows a user to customize in one of several areas:
  • Add custom expression functions
  • Add custom commands
  • Add custom operators (SOPs, COPs, Materials, TOPs, CHOPs, and even Objects)
  • Add output to a non-standard Renderer
  • Add custom lighting or atmospheric effects to the renderer
  • The custom functions are added to Houdini using DSO's (Dynamic Shared Objects). These object files are loaded at run-time.


    The DSO Mechanism

    At runtime, Houdini searches for .so files in certain places (determined by the Houdini Search Path). By default, Houdini will search:
    1. $HIP/dso
    2. $HOME/houdini/dso
    3. /usr/local/houdini/dso
    4. $HFS/houdini/dso
    Once Houdini finds the DSO's, it runs a function in each DSO. This function is responsible for wiring the interface to the custom code and the rest of Houdini. The mechanism is usually very straight-forward.

    The function names for each section are:

    Customization Type Function
    Expressions/CommandsCMDextendLibrary()
    Render Output IFDnewRenderer()
    Mantra Fog Shader RAYaddFogShader()
    SOPs newSopOperator()
    COPs newCopOperator()
    Material/Shader newMaterialOperator()
    TOP newTextureOperator()
    Object newObjectOperator()
    CHOPs newChopOperator()
    Output Driver newDriverOperator()


    Making a DSO

    This couldn't be simpler (aside from the algorithms). Once you have source, use the hcustom command to compile the source. This automatically creates a DSO so that the next time you run Houdini, the custom function will be added.


    Setting tag information

    The program sesitag will display 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 environement variable SESI_TAGINFO before you run hcustom on your source files. For example:

    % setenv SESI_TAGINFO "Produced by: Fantastic Graphics" % hcustom *.C


    Distributing a DSO

    For some reason, you may want to distribute your new DSO to the rest of the Houdini community. In this case, you can distribute it in one of many ways. You can publish the .so file on your web site, you can publish it on Side Effects Software's web site, you can post a copy of the DSO to the sidefx mailing list (though this is probably not a good idea), you can send out DAT tapes or CD-ROMs.

    If you're very kind at heart, you can send it out so that any Houdini user can use your software. Or, you can put some encryption code in the initialization function which enables only users with a specific key to run the software.

    It is possible to add licensing to your DSO. One useful function to look at in this case is UT_Exit::addExitCallback. This will allow you to add a callback which gets called every time the application quits. In the callback, you can return license tokens (or do other stuff). To be nice to other DSO's, please do not call exit() or abort() from within your exit handler. For example:

    static void dsoExit(void *) { returnLicense(); } MyDSO::construct() { if (getLicense()) { // Add stuff for Houdini UT_Exit::addExitCallback(dsoExit); } }


    Sample Source

    Samples of DSO's can be found throughout this documentation. The source files are located at: Sample Source. Each sub-directory here contains a DSO example or script example of extending Houdini.


    Table of Contents
    Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
    Material & Texture | Objects | Command and Expression | Render Output |
    Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
    Customizing UI | Questions & Answers

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