[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Command And Expression

Adding a New Command

The built-in Houdini commands can listed by typing help in the textport. This section will show you how to add your own custom commands to Houdini.

As an example, suppose we want to add the command date which simply prints out the current date. We want date to behave as follows:

/ -> date
Mon Mar 10 15:16:18 EST 1997

For pedagogical reasons, let's also make date accept an option -s num_spaces which left pads the returned date string with the specified number of spaces.

/ -> date -s 5
     Mon Mar 10 15:16:18 EST 1997

The C++ Source Code

The following is the C++ source code which adds the date command to Houdini. We will be referring back to this code throughout the example. /* * Produced by: * Side Effects Software Inc * 477 Richmond Street West * Toronto, Ontario * Canada M5V 3E7 * 416-504-9876 * * NAME: date.C * * COMMENTS: An simple example of adding a 'date' * command to Houdini. */ #include <UT/UT_DSOVersion.h> #include <CMD/CMD_Manager.h> #include <CMD/CMD_Args.h> #include <time.h> /* * cmd_date() * * callback function for the new 'date' command */ static void cmd_date( CMD_Args &args ) { time_t time_struct; char *time_string; char *argv[CMD_MAX_ARGS]; int i; // the 's' option left pads with some spaces, // just for an example if( args.found('s') ) { int num_spaces =args.iargp( 's' ); for( i = num_spaces; i>0; i-- ) args.out() << " "; } // call the standard C function 'time'. // see 'man time' for details time_struct = time(0); time_string = ctime( &time_struct ); // printout the date to the args out stream args.out() << time_string; } /* * this function gets called once during Houdini initialization */ void CMDextendLibrary( CMD_Manager *cman ) { // install the date command into the command manager // name = "date", options_string = "s:", // callback = cmd_date cman->installCommand("date", "s:", cmd_date ); }

Compiling

To compile this file (suppose we call it date.C) into a shared library, we simply need to type:
hcustom date.C

Explanation

When Houdini loads the dso during start-up, it looks for the function named:

void CMDextendLibrary( CMD_Manager *cman )
and calls this function during initialization. The function is passed a pointer to the Houdini command manager, which is the object we will use to install our new command. The call to:
cman->installCommand("date", "s:", cmd_date );
actually installs the date command. The first argument specifies the new command's name. The second argument specifies the option string that the new command will take. This string is similar to the option parsing string of the standard C function getopt. The string contains the option letters that the new command will recognise. If the letter is followed by a colon, the option is expected to have an argument (use two or three colons to indicate two or three arguments respectively).

The last argument is the name of the C++ callback function for the new command, in this case cmd_date.


C++ callback

The callback function should be declared static to avoid possible name clashes with other Houdini functions. The callback takes one argument, a reference to a CMD_Args object. This object has two main functions: to provide access to the command line options for the command and to provide an output stream so you can return output to the Houdini shell.

In this example, we used the found method to check if date was called with the -s option. We then use the iargp method to get an integer version of the argument of this option (the command manager knows that -s expects one argument because we used an option string of "s:" when we installed the command). Similar methods exist for getting a floating point representation (fargp) and string representation (argp) of the argument. Please refer to the CMD_Args.h header file for more details.


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