Building a Custom VOP Part 4: Writing Help Published: Tuesday, May 30, 2008

Video [27MB QT - 8 Min.]

writing_help.zip

You can write your help as either straight HTML or use wiki formatting. Houdini 9 has implemented a wiki like markup language for the help to both speed up and simplify the process. The video looks at creating some basic help. What follows here are guidelines and features in great detail for you to refer to. It is based on the wiki markup language Textbook.

This style of writing (wiki markup) help is now adopted throughout Houdini. Everything discussed here applies to help in other areas of houdini. You can refer to the Houdini help for a complete guide to all the wiki options available. Just search for "writing help in wiki format". You can also reference the on-line documentation: Writing help in wiki format

Using Images in your help

Images are supported in the Help. You can reference images from disk or save the image inside a Digital Asset and reference it from there. The images can be any format supported by Mozilla. You can use either .jpg or .gif images. You can also use animated .gif images embedded in the help. To do that open up the type properties on your Digital Asset and in the Extra Files area, inject your image file. To reference the image in your help, you would type the following:

[Image:opdef:/Object/my_asset_name?my_image_name.gif]

You need to supply the category of the asset (Object, Sop, Dop, Pop, etc) and the actual name of the asset, not the label. All of this information is available if you open up the Operator Type Manager. Just RMB on your Digital Asset and choose the Operator Type Manager entry to quickly jump to your asset definition.

I have supplied a start file that can be used to quickly work up your operator's help from. It should cover most of the options you will typically need. Just copy and paste this wiki help template file into the help section and modify to suit.

Some Help Text Guidelines

• Always provide enough help to make the VOP usable. Never leave a VOP without help, no matter how trivial the operator.
• The first paragraph should offer nothing more than a brief description of the functionality.
• Provide full documentation of each input, output, and intrinsic parameter. (An intrinsic parameter is a parameter without an input). See the help for the Parameter VOP as a good example.
• Provide one or two useful tips suggesting good parameter values and ways to connect the VOP to inputs and outputs.

• If an input is expected to be normalized, mention it. Also, mention if a global variable is used as a substitute for a non-connected input. Displace Along Normal offers a good example of how to document these facts:

  The input normal (N) should be normalized if explicitly connected. If the position (P) and normal (N) inputs are not connected, the global variables by the same names will be used instead. Here is a snipet of code from the same VOP to further clarify how the VOP deals with those inputs:

  vector $nn = $isconnected_nN ? $nN : normalize(N);
  vector $pp = $isconnected_P ? $P : P;

• Always make sure the help text ends with an @related help block.

Icons

All icons referenced in to help are to be .png format and 64x64 pixels in resolution.

SVG Icons

SVG Icons are vector based icons. These icons are used by the Houdini operators directly as Houdini will generate the .png bitmap images it needs. Houdini help currently only can display .png images. If you have a pre-existing .svg icon, create an icon of resolution 64x64 and inject it in to your digital asset.

Bitmap Icons

If you use bitmap images, produce 64x64 pic files for your VOPs. You can use the attached hip file to generate pic icons. Render out and convert to .png format. The switch SOP in the shader_geo object allows you to choose a sphere, a tube, a grid or a torus for display. Display either the gray_walls object or the checkered_walls object if you want walls behind the shaderball. Use the headon_mantra output driver to render the image.

Embedding Icons in Digital Asset Help

As with images you can embed your icons inside a Digital Asset if your tool uses one. If you have a .svg icon, save out a .png icon image. Next follow the same method to inject the icon in to the digital asset using the Edit Operator Type Properties editor and the Extra Files folder.

The #icon line will take on the following form:

[#icon: opdef:/Object/my_asset_name?my_icon_name.gif]

Please login or register to add comments.