Q: How do I start using the HDK?
Windows
Compiler requirements
First, you must determine which compiler built the version of Houdini you are using.
No other versions of the compiler other than the one that was used to build Houdini will work.
For some reasons as to why you can't use something else, for example say, the free MinGW compiler, see the following post: http://www.mail-archive.com/cygwin@cygwin.com/msg43848.html
Currently (Houdini 9.5), there are two builds for 32-bit: vc7 and vc8, but only a vc8 build for 64-bit. vc7 refers to the Microsoft Visual C++ .NET 2003 compiler, while vc8 refers to Microsoft Visual C++ 2005. Use of vc7 is being deprecated so given the choice, choose vc8. When installing Visual Studio on 64-bit Windows, make sure to choose Custom Install and install the 64-bit compiler tools! (it's not enabled by default).
It's currently not possible to use the free (aka express) editions of Visual C++ because they lack the ability to link with DLLs.
Set up the MSVCDir environment variable
Right-click on My Computer and choose Properties > Advanced > Environment Variables. Add a System Variable called MSVCDir. Set the value for this to the path to where you have Visual C++ installed, using forward slashes. Also, append /VC at the end (use vc7 instead if using the vc7 build of Houdini). For example, if you had installed it under c:\vstudio8, the value for MSVCDir should be "c:/vstudio8/VC" (note the forward slashes). If your installation directory has spaces, you should use the 8.3 filename for it to avoid putting spaces into the value.
Also make sure that your Visual C++ installation is included in your PATH environment variable. Following the example above, you need to add
"c:/vstudio8/VC/bin";"c:/vstudio8/Common7/Tools/bin";"c:/vstudio8/Common7/IDE"
If you're doing this from the Environment Variables dialog, these should be in 8.3 file paths without spaces and backslashes. You should also take the time to convert all your path directories there to 8.3 file format to avoid potential problems.
That sets things up, proceed to the next step below.
Test your HDK setup
From the Start menu, choose Program Files > Side Effects Software > Houdini X.X.XXX > Command Line Tools. This opens up a cmd prompt. Now type in the following commands:
csh cd $HT/samples/SOP hcustom SOP_Star.C
Now start Houdini. Create an object, dive inside and try to create a Star SOP. If this works, then you're well on your way. After this, you want to read up on the outdated HDK documentation under $HT/html. You can use the Command Line Tools to start the appropriate shell for you that has the Houdini environment variables set up.
Old versions of Houdini
For Houdini 7.0 or Houdini 8.X, you must use Microsoft Visual C++ .NET 2003 (aka MSVC 7). You can't use the free version either as that doesn't allow you to link to DLLs. To confirm the compiler needed, hdkinstall.exe will tell you when you run it (see below).
Assuming that you installed the HDK when installing Houdini, start up a shell from the "Command Line Tools" menu entry in the Start menu and in it type "hdkinstall". This will do some stuff like installing a HDK license if none is present, extract the header files, and prepare your installation for usage with the HDK. At the end of this, it will also tell you which compiler you must use. This will supercede whatever this wiki page says.
Bash
If you're using Cywin with bash and NOT invoking bash from Command Line Tools, here is an example .bash_profile using the default installation directory for Visual C++ .Net 2003. You must modify the below accordingly for Visual Studio 2005.
... all the default stuff ...
cd "/cygdrive/c/Program Files/Side Effects Software/Houdini 7.0.301"
source houdini_setup_bash
PATH="/cygdrive/c/Program Files/Side Effects Software/Houdini 7.0.301/toolkit/bin":${PATH}
PATH="/cygdrive/c/Program Files/Microsoft Visual Studio .NET 2003/Common7/Tools/bin":${PATH}
PATH="/cygdrive/c/Program Files/Microsoft Visual Studio .NET 2003/Vc7/bin":${PATH}
PATH="/cygdrive/c/Program Files/Microsoft Visual Studio .NET 2003/Common7/IDE":${PATH}
export PATH
MSVCDir=`cygpath -ams "/cygdrive/c/Program Files/Microsoft Visual Studio .NET 2003/Vc7"`
export MSVCDir
cd
set complete
Linux
Setting up the HDK on Linux is simple. You must be root to install the HDK, and you must have gcc and some preferred editor or IDE to use the HDK.
First, open a shell and source houdini_setup if it is not already your default shell environment. Once your shell is in Houdini's environment, type
hdkinstall
to install the HDK. It will extract all the files you need.
Update: Houdini 9.5 no longer requires hdkinstall. You must be careful to use the same compiler as the build of Houdini you installed.
Now, test the installation by compiling some examples. Copy the sample source code to your home directory
cp -R /opt/houdini/toolkit/samples $HOME
Change the permissions on the newly copied sample directory so you have full access to it.
chmod 777 -R $HOME/samples
From your user account, within a Houdini shell environment, try compiling some samples. Navigate to the SOP samples directory.
cd $HOME/samples/SOP
Then run the provided shell script to build and install the samples.
./sample_install.sh
This will compile and install all the samples in the SOP sample directory. If you do not see any errors in your shell after running sample_install.sh, the HDK is properly installed. To be certain, open Houdini, place a Geometry object and dive into SOPs. In the tab menu you should have access to the SOP samples you just compiled and installed, such as the Star Generator and Flatten Filter.
Specific platform setups
Ubuntu 8.04 Linux (Desktop)
- Install "csh" package
- Install "xi-dev" package
- You might find that your hcustom will say "Unsupported architecture". This seems to be an unsupported case in hcustom, and I got it to work by editing the hcustom script and commenting out the "exit 1" statement.
Q: How do I use the HDK when running multiple versions of Houdini?
Custom HDK plugins work only for EACH build of Houdini. If you compile a custom DSO for Houdini version P.Q.XYZ, then it can *only* be used for Houdini version P.Q.XYZ. It will NOT work if you try to use it for Houdini version P.Q.ABC. Do NOT put your custom HDK plugins into your $HOME/houdiniP.Q (eg. $HOME/houdini8.1) directory as then it will be attempted to be loaded by each different build of Houdini P.Q.
You must put each custom HDK plugin into different directories such that each different build of Houdini will only see 1 copy of the DSO, compiled specifically for that particular build. The easiest way is to simply put each compiled custom DSO into the $HFS/houdini/dso of your respective Houdini builds.
If you want to keep the custom DSOs separate from the main Houdini installation, the HOUDINI_DSO_PATH environment variable may be used. This environment variable is used for search for DSOs when Houdini starts up. So if you put your custom DSOs for each version of Houdini in a separate directory, you can add the proper version specific directory to HOUDINI_DSO_PATH depending on which Houdini version you want to run.
Q: Do I need to use hcustom?
The answer is no longer. hcustom is now merely provided as a convenience. For more flexible compiling of HDK code, see the files in $HFS/toolkit/makefiles.
If you want to use Visual Studio, please see Setup_visual_Studio for more information.
Q: Where should the compiled HDK code be installed?
There are environment variables that controls where plugins are loaded from in Houdini:
HOUDINI_IMAGE_DSO_PATH (for image readers/writers) HOUDINI_AUDIO_DSO_PATH (for audio readers/writers) HOUDINI_DSO_PATH (for all other plugins)
To see the values of these search paths, using the command line tool, hconfig, like so hconfig -ap.
Note that by default, hcustom will install into the current user's HOUDINI_DSO_PATH, ie. $HOME/houdiniX.X/dso
It is best to example the sample_install script that is found in each of the HDK sample file directories to see where the plugins should be installed.
For mantra, plugins are searched in the VRAYprocedural file which itself is found via HOUDINI_PATH. The convention is to put plugins under HOUDINI_DSO_PATH/mantra.
Q: How do I debug my code when using the HDK?
Windows
- When compiling using hcustom, use the -g option.
- From within Command Line Tools, start the Visual Studio IDE with %HB%/houdini.exe (or $HB/houdini.exe in csh/bash).
Linux
- When compiling using hcustom, use the -g option.
- Start houdini using gdb: gdb $HB/houdini
- Run with: run -foreground
Q: Why doesn't it work when I multiply a matrix by a vector?
- UT_Vector3's when multiplied with matrices, are treated as row vectors.
The implication is that when concatenating transforms, the point is applied to the leftmost matrix first. So you usually need to concantenate transforms in the reverse order than what you were taught in class. If you're copying matrices from papers, you typically need to reverse the order of the indices.
Let's work through some examples.
UT_Vector3 p; UT_Matrix4 xform1, xform2; // transform the point p in local space by the transform xform p *= xform1; // this is equivalent to: p = p * xform1; // treat the variable p as a direction instead of as a point p.multiply3( xform1 ); // transform the point p first by xform1 and then by xform2 // another way to think about this is that xform1 is the parent // space of p and xform2 is the parent transform of xform1 p *= xform1; p *= xform2; // another way to do the same thing: p = p * xform1 * xform2; // or ... xform1 *= xform2; p *= xform1; // create a matrix that translates and then scales the point p // note that translate()/scale()/rotate() calls create a // temporary matrix which is then right multiplied with *this UT_Matrix4 xform( 1.0 ); // start off with identity xform.translate( 1, 2, 3 ); xform.scale( 2, 2, 2 ); p *= xform; // or in the reverse order ... UT_Matrix4 xform( 1.0 ); // start off with identity xform.prescale( 2, 2, 2 ); xform.pretranslate( 1, 2, 3 ); p *= xform;
Q: How can I bind handles to custom operators?
You can edit a copy of the $HIH/OPbindings file and put it somewhere in the path.
The problem is that it doesn't read ALL OPbindings in your path and doesn't support preprocessor statements like #include. If this was the case, you could just add an OPbindings earlier in your path with only your new operator and #include the system one in $HIH if need be. Ultimately just having Houdini read all OPbindings files in the PATH would be a lot better, IMHO.
The current way, you're not receiving the handles to new OPs or whatever as new versions of Houdini get released. You have to re-edit the OPbindings file for every (significant) release of Houdini to take into account when SESI change handle bindings or add new ones. Also, you cannot have an OPbindings files in parallel locations to custom DSOs, so if you have permutations of certain custom OPs being loaded by certain shows, you still have to maintain one master OPbindings file which will print errors for OPs you're trying to bind handles to which are not defined.
Hopefully SESI will change this in the future.