Houdini communicates with renderers through the SOHO (Scripted Output of Houdini Objects) Python bindings. All renderers use the same process for parameter definition and evaluation. The Mantra and RenderMan output drivers are now simply front-ends to Python scripts (they are now digital assets). Each renderer can add its own parameter definitions and bindings using Python mappings.

SOHO provides two main benefits:

• Easy to define new render output nodes for alternative renderers. SOHO provides the interface to interrogate Houdini for necessary information to output the renderer-specific file format.

• You can customize generation of render output by creating a new render node and customizing the soho_program parameter (see below). In some cases this may be more convenient or flexible for you than adding rendering properties to lights, cameras, and/or render nodes.

The SOHO interface is used to send geometry, object transforms, and rendering properties to a renderer. Each supported renderer has a set of predefined rendering properties. If an object has any of these properties defined as spare parameters, its value will be sent to the renderer.

There are a set of predefined rendering parameters which can be added to objects (or materials) using the “Edit Rendering Parameters” interface. There is a one to one mapping of these parameters from the Houdini interface to the renderer’s properties.

SOHO uses the new Material workflow to process shaders and rendering properties. For more information, see the materials and property overrides help.

The SOHO renderer property default values correspond to the target renderer’s default values. If the property value is left at the default value, the property is generally not written out to the input stream for the renderer.

If you look at the type properties of the Mantra render output digital asset, you will see an invisible parameter called soho_program, which contains the Python script Houdini will run to write the output file (in the case of the Mantra driver, an IFD file).

The Python script will contain code like this:

value = obj.getDefaultedFloat('vm_displacebound', 0.0)

(or, more likely, batch evaluation of properties). When a SOHO program evaluates a parameter like this, it applies the property inheritance order so more specifically-defined properties (for example, on a shader) have priority over more broadly-defined properties (for example, on the output driver node).

The SOHO API and implementation are in Python scripts in $HFS/houdini/soho.

You can use the following parameters to control the SOHO generation process.

See the render property documentation for information about the render properties.

To get mantra to dump a list of properties it knows about, use the ray_show command. It takes an argument representing the category of properties to print.

echo ray_show device | mantra
echo ray_show global | mantra
echo ray_show object | mantra
echo ray_show light | mantra
echo ray_show image | mantra
echo ray_show fog | mantra

SOHO supports callback functions, or hooks to allow advanced users to modify or replace low-level parts of the render process.

(In previous versions of Houdini, it was possible to “monkey patch” SOHO functions as a means of changing SOHO functionality. However, the callbacks are a much cleaner and future-proof method.)

See $HFS/houdini/soho/IFDhooks.py or $HFS/houdini/soho/RIBhooks.py for documentation.

Here’s a sample hooks file:

'''
    IFDuserhooks.py
    A simple example to illustrate the IFDhooks features
'''
import traceback
from IFDapi import *

def pre_lockObjects(parmlist, objparms, now, camera):
    ''' Called before SOHO locks objects.  This allows you to modify the
        objects that are visible to SOHO '''
    ray_comment('IFD Hook - rendering from camera: %s' % repr(camera))
    return False

def pre_render(camlist, now, objlist, lightlist, spacelist, foglist,
                fromlight, forphoton, cubemap, photoncam):
    ''' Called before an image gets rendered '''
    ray_comment('IFD Hook - Render at time: %g %s' % (now, repr(camlist)))
    return False

''' List of hooks in this file '''
_HOOKS = {
    'pre_lockObjects'   : pre_lockObjects,
    'pre_render'        : pre_render,
}

def call(name='', *args, **kwargs):
    ''' Hook callback function '''
    method = _HOOKS.get(name, None)
    if method:
        try:
            if method(*args, **kwargs):
                return True
            else:
                return False
        except Exception, err:
            ray_comment('Hook Error[%s]: %s %s' % (name, __file__, str(err)))
            ray_comment('Traceback:\n# %s\n' %
                        '\n#'.join(traceback.format_exc().split('\n')))
    return False