Katana on Microsoft Windows

Katana is now supported on Microsoft Windows 7.

Online Help

Katana's User, Technical and Reference Guides have been combined into a single help system - Katana Online Help. The Online Help is presented in HTML and available both on the web and as part of the Katana installation.

The Katana Online Help allows you to search the content previously contained in the individual guides in one single location. In addition to being restructured, it also now contains a brief summary of new features and where to find information on them. It also offers context-sensitivity that allows you to open the node reference from within Katana.

Katana Developer Guide

A new Katana Developer Guide brings together references for Katana's plug-in APIs and scripting interface, including C++, Python, OpScript, AttributeScript, CEL and parameter expressions. The dev guide is fully searchable and available both on the web and as part of the Katana installation. It replaces the previous Epydoc- and Doxygen-based documentation.

The Python reference is laid out by topic, making larger modules easier to understand. Functions that were previously documented under the nonexistent "python" module are now correctly namespaced. We plan to expand the Python reference, and we welcome feedback on which modules or tasks are most in need of documentation.

The OpScript and parameter expression references now have near-complete coverage of their respective APIs. However, most of the OpScript reference contains signatures only; we're looking to correct this in a future release.

This feature resolves the following bugs and feature enhancement requests:

• TP 17706 / BZ 19825 - No API documentation for connecting and disconnecting nodes was available.

• TP 103438 / BZ 47208 - Katana's C++ API documentation listed filesystem paths to headers that did not match the paths in the Katana installation directory.

• TP 119958 / BZ 50344 - Documentation for Katana's Python APIs grouped many module contents under a spurious "python" module.

• TP 126302 / BZ 51350 - NodeTypeBuilder was not documented.

Other Documentation Changes

A new documentation/source preference controls where Katana looks for documentation:

• remote (default): load documentation from help.thefoundry.co.uk. This documentation may be more up-to-date than the local copy.
• local: load documentation from the Katana installation directory. Choose this if your machine has no internet access.

Node documentation for Katana's built-in nodes is now opened in an external web browser. Plug-in authors can specify a helpURL hint to provide web browser-based help for their own node types.

Ramp Widgets

Color Ramp and Float Ramp widget types are now available to use for shader parameters and as user parameter types.

Color Ramp widgets allow users to define a color gradient by placing knots with positions between 0 and 1 (including 0 and 1) and picking colors for them using Katana's color picker dialog. Widget hints can be used to specify the height of the gradient portion of Color Ramp widgets, as well as to turn filmlook visualisation on or off, and to restrict RGB(A) components in the color picker dialog when picking knot colors.

Float Ramp widgets allow users to define a curve by placing knots with positions and values in ranges that can be specified via widget hints.

A number of presets are available for users to choose from for individual Color Ramp and Float Ramp widgets.

This completes a long-standing feature request: TP 60262 / BZ 31564 - Support for ramp widgets

GafferThree Light Filters

Light Filters are arbitrary shaders that can be added to lights to modify a light's effects on a rendered scene. Examples of Light Filters are:

• Barndoors
• Blockers
• Filters to control a light's Decay effect
• Gobos

This release of Katana adds Light Filters to the GafferThree SuperTool node type, by adding new types of GafferThree packages.

Light Filters can be added to lights in a GafferThree node's table of objects in one of two ways:

• From the context menu of a light, choose Add > Light Filter, or
• Select a light, and press the F key.

You can re-use Light Filters between a number of lights by using Light Filter References, which are a distinct type of package in GafferThree. To create a Light Filter Reference based on an existing Light Filter underneath a light:

• From the context menu of the Light Filter, choose Create Shared Light Filter, or
• Select the Light Filter, and press Shift+F.

The Linking tab in the GafferThree’s interface provides parameters for configuring linking options for Light Filters. The parameters in this tab are similar to those for controlling illumination linking for lights.

Details of the expected attribute conventions for light filters can be found in the Katana Online Help, Appendix H: Standard Attributes.

Op Cook Profiling

A profiling mode has been added to Katana. When launched in profiling mode, Katana can generate reports on Op cook times within profiling sessions. Cook times are aggregated per Op instance, per location. These reports can help in pinpointing slow areas of the Op tree and scene graph.

Katana can be launched in profiling mode with the --profile command-line option:

./katana --profile

In profiling mode, Katana loads a special version of the Geolib3 Runtime that implements profiling. The profiling is low overhead to minimize its effect on cook performance; the more computationally demanding data aggregation is performed at the end of the profiling session.

A profiling session is specific to a Geolib3 Runtime instance that is started in profiling mode, and one report is generated at the end of each profiling session, hence multiple reports may be generated for each process (katanaBin and renderboot, for example). Renders that call the Katana procedural on multiple threads, for example, instantiate one Runtime per thread. Each report consists of two files:

• A .dot file that contains the graph with the Op tree at the end of the profiling session.
• A .csv file containing the recorded cook times in a table format.

The .dot files can be converted, for example, into a PDF document using Graphviz.

The .csv (comma-separated values) files contain the aggregated cook times and number of cooks. This can be read directly into a spreadsheet application or other reporting tool.

Viewer Draw Call Batching

The Viewer Modifier Plug-in API exposes new static callbacks for onFrameBegin() and onFrameEnd(). These enable users to implement the batching of draw calls: the onFrameBegin() callback is raised once per VMP type, before the draw() method is called on all active and visible VMP instances, and onFrameEnd() is called after drawing is complete.

An example plug-in called "BatchViewerModifier" has been added to demonstrate the use of the new API functions for batching draw calls in Viewer Modifier Plug-ins. This plug-in can be found in $KATANA_ROOT/plugins/Src/ViewerModifiers/BatchViewerModifier. This plug-in is not intended for use in production, but provides an example of how the onFrameBegin() and onFrameEnd() calls could be used to batch draw calls together. An example project that uses this VMP is available online.

This change increases the VMP API version to 2.0; see the accompanying Katana 2.5v1: API Changes and Compatibility document for further detail.

Improved Crash Handling

Katana has a new system to handle crashes, and allow users to submit crash reports to The Foundry. Crash reports will be saved on our servers and cross-referenced with similar reports to identify common causes of instability in Katana.

By default, crash reporting is enabled in UI mode and disabled in all other modes. This behavior can be controlled using the following environment variables:

• FN_CRASH_DUMP_PATH: Allows you to specify where Issue Reporter dumps are saved by default.
• KATANA_CRASH_HANDLING: By default, crash handling is enabled in GUI mode and disabled in terminal mode.
  • When KATANA_CRASH_HANDLING is set to 1, crash reporting is enabled in both GUI and terminal mode.
  • When KATANA_CRASH_HANDLING is set to 0, crash reporting is disabled in both GUI and terminal mode.
• KATANA_NO_CRASH_PROMPT: When crash handling is enabled in GUI mode, by default a crash reporter dialog will be shown before submitting a crash report.
  • When KATANA_NO_CRASH_PROMPT is set to 1, crash reports are submitted automatically without displaying a crash reporter dialog.