[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Customizing UI

Dialog Scripts

Dialog scripts provide a simple way of creating a graphical user interface for editing a string. The string is usually a command or shader of some sort. Basically a dialog script defines a set of parameters and options for a command or shader.

When Houdini reads a dialog script, it will automatically make a UI file and provide a graphical interface for editing a string. Houdini has "hooks" for a dialog script interface in several parts of the application. These are:

  • OBJmacro.ds - Object Macros (in the Edit menu of the Object Editor)
  • SOPmacro.ds - Macros for SOPs (in the Edit menu of the SOP editor)
  • COPmacro.ds - Macros for COPs (in the Edit menu of the COP editor)
  • MATmacro.ds - Material Macros (in the Edit menu of the Texture editor)

  • MANfog.ds - A shader string editor for Mantra Fog shaders
  • MANlight.ds - A shader string editor for Mantra Light shaders
  • MANlightfog.ds - A shader string editor for Mantra Atmospheric Light shaders

  • RMshader.ds - RenderMan(tm) Surface Shader Editor
  • RMdisplace.ds - RenderMan(tm) Displacement Shader Editor
  • RMlight.ds - RenderMan(tm) Light Shader Editor
  • RMinterior.ds - RenderMan(tm) Interior Shader Editor
  • RMatmosphere.ds - RenderMan(tm) Atmosphere Shader Editor

  • Renderers.ds - An interface to common Renderer Commands. This shows up in the Output Drivers when there is a command for a specific renderer.
  • When adding a macro/shader to a dialog script, it is not necessary to replace the scripts installed in $HFS/houdini/config/Scripts. Since all scripts found in the Houdini search path are merged, you can simply install these scripts in any of the path directories (i.e. /usr/local/config/Scripts).


    Syntax of a Dialog Script

    The syntax of the dialog script is quite simple. The script describes a nested set of parameters. Each parameter may be one of many types (i.e. a toggle button, a float or a string). Internally, each parameter is represented as either a string, float, or an integer vectored value. However, there are different ways of representing this value in the user interface. For example, a string might be a string that the user enters, or a file name, or a string chosen from a menu. The list of possible parameter types is constantly growing. In other words, the list below might be out of date, though we do endeavour to keep it current.

    As well, there are special controls in the script for special features. For example, if the script is supposed to parse a RenderMan shader, there is a special keyword to use the RenderMan syntax. Other special features are the ability to group parameters into individual pages.

    The general form of a dialog script is:

       command {
           header
    
           parameter_list
        }
    
    The header definition is basically used to define what the command is at a global level. There are certain fields which can be specified at this point:
  • name - Specifies the actual command name or shader name.
  • help - Specifies help for the command or shader.
  • label - Specifies a more descriptive name which is used by the user interface.
  • default - Specifies a default command/string which is used at startup.
  • rman - Specifies that this command should be interpreted using RenderMan syntax.
  • Only the rman keyword doesn't take any options after it. All of the other keywords expect a string to follow. The help keyword expects a series of strings enclosed by a set of braces ({ and }). See below for an example.
    HINT: When specifying strings, the script requires that the string be enclosed in double quotes (") if and only if there are spaces in the string. However, it doesn't hurt to put the double quotes for all strings.
    HINT: The name usually specifies the name of the command. Theoretically, it should not contain any blanks. However, this is not a limitation though presets may not work correctly.

    Parameter Types

    The form of a parameter definition is as follows:
        parm {
    	field	value
        }
    
    There are some fields which are mandatory for each parameter. These are:
  • name - The internal name for the field. This is used when saving and loading presets for the dialog script.
  • label - The "visible name". This is what appears in the graphical interface. It should be more descriptive than the internal name.
  • type - This determines the type of the parameter. The type may currently be defined as one of the following:
  • toggle A toggle button.
  • string An editable string.
  • object An editable string. However, a menu of all objects can be used to stuff the string.
  • render An editable string. However, a menu of all output drivers can be used to stuff the string.
  • file A string which has a file browser button beside it.
  • float A single or vector of floating point values.
  • integer A single or vector of integer values.
  • direction Three floating point values. The size field must be set to 3 for this type of value.
  • colorThree floating point values. Like direction, the size field must be set to 3. The user interface for this parameter type will include a set of color sliders.
  • Either one of required or option to specify whether this parameter is a required field or an optional field.
  • There are also optional fields which can be used to alter the parameter slightly. These are:
  • menu which specifies a list of strings that the parameter may contain. The syntax for menus is:
    	    menu {
    		    value    label
    		    value    label
    		    value    label
    	    }
    
    where the label will show up in the UI, while the value is what is actually used for the field.
  • size which specifies the vector size of the parameter. By default, this is 1.
  • default specifies the default value(s) for the parameter. The syntax is:
    	    default { value1 [value2...] }
    
    Where each value specified is for a different component of a vector. For example, if the size of the parameter was 3, you would probably want to specify three default values. If no default is specified in the parameter declaration, the parameter will default to 0 (or an empty string).
  • Examples of Parameter Definitions

    1. 	parm {
      	    name    rolloff
      	    label   "Spot Light Rolloff"
      	    type    float
      	    option  -r
      	    size    1
      	    default { 1 }
      	}
      
      This example shows an optional parameter which is a single float value. It defaults to 1.

    2. 	parm {
      	    name    scolor
      	    label   "Specular Color"
      	    type    color
      	    required
      	    size    3
      	    default { 1 1 1 }
      	}
      
      This example shows a required parameter which is a color. When the UI is built for this parameter, it will contain a set of RGB sliders for editing the parameter.

    3. 	parm {
      	    name    nproc
      	    label   "Number of Processes"
      	    type    string
      	    option  -n
      	    menu    {
      	                       1   "1 Process"
      	                       2   "2 Processes"
      	                       4   "4 Processes"
      			   }
      	}
      
      This example shows how you can use a menu to cheat and specify an integer as a string. The menu will simply use the value (i.e. 1, 2, or 4) but present the user with a list of choices.

    Specifying Groups (or Pages)

    The dialog script language allows you to group parameters together in pages (with a folder tab to specify each page). The syntax of the group specification is:
    	group {			# First group of parameters/folder tab
    	    name     string	# Name in the tab
    	    label    string
    
    	    parameter_list
    	}
    	group {			# Second group of parameters/folder tab
    	    name     string	# Name in the tab
    	    label    string
    
    	    parameter_list
    	}
    	...
    
    It's possible to fit as many folders as you want in the dialog script (however, there may be formatting problems when the UI is displayed). It is also possible to nest groups, though in general, this is bad UI design since it hides paramters from the user.

    It is also possible to mix parameters so that some are always displayed, then the folder tab is a separate entity. For example:

    	command {
    	    name	folder
    	    label	"Folder Example"
    	    help	{
    		"A simple dialog script to show that the always parameter"
    		"is always visible even when the groups get switched."
    		"The groups appear below the \"always\" parameter."
    	    }
    
    	    parm {
    		name	always
    		label	"Always visible"
    	    }
    
    	    group {
    		name	page1
    		label	page1
    
    		parm {
    		    name	opt1
    		    label	"Option 1"
    		}
    	    }
    	    group {
    		name	page2
    		label	page2
    
    		parm {
    		    name	opt2
    		    label	"Option 2"
    		}
    	    }
    
    	    parm {
    		name	always2
    		label	"Shows up after the folder"
    	    }
    	}
    

    Examples

    Many examples can be found by looking in $HFS/houdini/config/Scripts.

    Testing Dialog Scripts

    There is an application which is shipped with the development toolkit called dsparse. This will parse a dialog script and allow you to experiment with the layout and adding parameters.

    Common Problems

    When each dialog script first gets parsed, it creates a .ui file (See
    Customizing UI). This file is created in /usr/tmp/Dialogs/... This specifies the UI layout for the dialog script. When this file is created, the UI is locked for the script. Therefore, even if parameters change, the UI displayed will be the same. Therefore, when testing, it is almost mandatory that this UI file created is removed between each test.
    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