-
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
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. (In that case, try your best to stick with the exact parameter list and naming as in the original OP!)
Remember, it's real pain to rename a tool after other people started 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 version>
...where the recommended initial interface version is 1.
Do NOT increment the interface version number unless you are building an entirely new implementation with a new interface.
Don't increment if you're...
- adding a new parameter. Choose a default value for the parameter so the asset gives the exact same results as if the parameter wouldn't exist. (This way you'll be able to reopen old scenes without a problem.)
- fixing a bug. We don't tolerate long-standing bugs "becoming" features. Just fix it.
- doing significant internal changes? (e.g. heavy optimizations) Make sure the new stuff produces the exact same thing for the same parameter sets. Build test cases (also re-check with production scenes, if possible).
The interface version number should be changed (incremented) only if...
- the asset's internals changed in a way that it returns different results with the same parameter 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, this is the case when 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.
These rules apply slightly differently for asset classes:
- base assets: all backwards-compatibility rules are strictly observed
- future assets: all rules are observed, but there's room for minor changes after due consideration
- experimental: "anything goes" while an asset is in the experimental stage
In whichever contexts applicable, make sure you subvert to the following annoyances:
- The asset's output OP should be a Null called OUT [1]
- The guide geometry (mostly SOPs) output OP should be a Null called GUIDE [1]
- Make sure your asset is NOT time-dependent (unless it's part of its functionality of course)
- When saving example scenes, make sure asset embedding in scene is off
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.
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 "rookie" operators like the Point SOP if possible :) Never process data with OPs that run hscript/expressions on geometry, use VEX.
Break down your asset into smaller interoperable tools, if possible. 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. (The ideal case is to do everything within a single VOP or VEX code block -- won't happen very often, though.)
If the above sounds contradictory, there's another factor to consider: maintainability. The tool you create will have to be maintained (bugfixes, etc.) so make sure the internals are understandable and won't be a pain to maintain.
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_internal_attrib__" instead of "my_internal_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.
One 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.