-
Notifications
You must be signed in to change notification settings - Fork 117
Developer Guide
This page provides general information, guidelines, tips on the development practices of qLib. If you only want to use qLib this page's content may prove to be worthless but it won't hurt you if you understand the design principles behing the library.
First of all clone it with git:
git clone git://github.com/gadfly16/qLib.git
For better version management the assets are distributed in ascii form. This
means that the OTLs must be built before importing into houdini. qLib provides
the qdo utility script to aid you in this and other processes.
The following command executed in qLib's root directory will build the whole library:
./qdo build -R
The -R flags stands for recursive and that make qdo to descend into subdirectories. The following command will build just the 'base' otls:
./qdo build -R otls/base/
Of course the exact commands may be different if you are not in the top level of the qLib distribution.
You can also build just one single asset:
./qdo build otls/base/bend_ql_SOP_OTL
The logic is the same here, just the subcommand differs:
./qdo extract -R
./qdo extract -R otls/base
./qdo extract otls/base/bend_ql_SOP.otl
Sometimes it's handy to clean up the mess after your work. The logic is the
same here, you can use the -R flag to initiate recursive behavior. The next
command will clear all binary OTLs recursively under the current directory:
./qdo clean -R
If you want to remove the extracted directories use the -s or --source
flag. For example:
./qdo clean -sR otls/base
If you are uncertain you can always use the -h or --help flag to see all
the available subcommands and flags, or if you put it after a subcommand to get the
help of that particular command.
Naming a tool is hard. Think about it, think hard and discuss it with your fellow houdinistas. Make it as simple and short as possible. Avoid collision with Houdini's standard operator namespace if the tool does something different, but use the same name if it's a better or different solution of the same problem that the standard tool addresses.
Remember, it's real pain to rename a tool after other people are using it.
- operator name:
qLib::long_name_ql::1(see below) - operator label:
Long Name qL - otl file name:
long_name_ql_SOP.otl - extracted asset directory name:
long_name_ql_SOP_OTL
Houdini 12 introduced namespace and versioning support in asset names. To take advantage of this, operators should be named in the following manner:
- operator name:
qLib::<long_name_ql>::<interface revision>
...where the recommended initial interface revision is 1. Note that the interface revision is NOT
the same as the operator version and usually there is no need to increment it at all. Do NOT increment
the interface revision number unless you are building an entirely new implementation with a new interface.
The interface version number should be changed (incremented) only if...
- the asset's internals changed so drastically that it returns entirely different results with the same settings
- the asset's parameter interface changed so much that it's not backwards-compatible with the last version (this usually implies major internal changes, too)
In other words, an asset that has two interface versions are actually two different assets that happen to share the same basic name and do the same thing, but in a completely different way.
Please set "Tool / Options / Context / Tab Submenu Path" to "qLib" and use a comma separated list of category names, if you feel that a tool belongs to one or more standard categories.
Don't use the separator parameter, it hurts the eye. Use the label parameter without a label instead.
Don't use ascii art. It's not funny to bring 3D Max elements into the sacred software: it's blasphemy.
Don't put "informative" messages into the interface in the form of label parameters. Use the help card and the parameter help for static information and real like float or string parameters for dynamic information.
Don't get mad if we make changes on your interface before introducing it into the library, but feel free to argue if you think we made the wrong decision.
Use folders to break up your parameters if they occupy considerably more than half of the vertical space on a 1200 pixel high screen. Don't use folders if your asset can fit on that space comfortably.
Test your assets as thorough as you can. Create an example file, that serves as a development environment, as documentation and as the collection of test cases of various possible problems.
Use the performance monitor to profile your tools inner workings, and make them run as fast as possible.
Make sure your asset is compact and doesn't contain unnecessary nodes. Expect your node to be used with heavy data sets (this is supposed to be a production-driven library). Make it reliable. Use VEX whenever you can (and set the defaults to 1 thread per CPU), and avoid slow operators like the Point SOP if possible.
Break down your asset into smaller interoperable tools. Tools with too many features usually process simple tasks slower. Also integrate features in one tool that are faster to process in one pass than in two or more. Don't look stupid, this is life.
Please understand and copy the help card of a qLib asset as a template. Since qLib is designed to be used by others, proper documentation is paramount and considered a minimal requirement for the introduction of an asset into the library's main secions. Please be onest in the "Limations" section, and describe all the bugs, quirks and limitations of your asset.
Please choose an icon for your asset from existing Houdini icons, which express the functionality of your tool the best. It's a good idea to choose an icon from a different context from where your tool will be used to minimalise the chance of possible confusion with other tool in the context. Please be sure to include the icon description in the Tool/Options section as well, otherwise the icon won't be used in the tab menus. Of course you can design and include your own icon in the asset, if you have the time and mood to create one.
You can find all Houdini's icons under $HFS/houdini/help/icons/large/.
To minimize the possibility of attribute name clashing, and to don't leave unnecessary attributes after your operator, please place two underscores before and after your utility attribute names, and delete them before exiting the operator. So for example use "__my_inner_attrib__" instead of "my_inner_attrib".
As you probably know, vex parameters can be overridden with attributes with the same name. This is a good and useful thing when you develop your own 'one time' solution for a problem, but can lead to unexpected behavior in an asset intended for a wider audience. Since your users don't necessarily knows the internal working of your asset, they may accidentally create an attribute that later prevents your tool to work as intended.
The solution is to add the "vex" prefix to the parameter names of your VOP or VEX nodes inside the assets. So for example if you implement a surface operator in VOP SOP and you need a parameter that describes a length, you name your vex parameter "_vex_length". Since it's nicer and easier to use it in expressions we prefer to promote this to the asset's interface simply as 'length', but that's not a necessity. This way there is only a minimal chance that some name collisions occur accidentally.
It's a nice touch if you mention these special names in the help card of your tool, especially if overriding these parameters with attributes makes practical sense.
We should follow this branching model: "A Successful Branching Model":http://nvie.com/posts/a-successful-git-branching-model/
In fact currently we don't.