27 July 2016
Katana is now supported on Microsoft Windows 7.
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.
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.
A new documentation/source preference controls where Katana looks for documentation:
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.
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
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:
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:
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:
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.
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:
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:
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.
WARNING: The timing report files produced in profiling mode can be extremely large -- of the order of the gigabytes. As a guide, note that typically one line of information is produced per Op instance, per scene graph location at which it is cooked. It is therefore advised that profiling mode be used selectively when measuring cook times, and not during normal production usage of Katana.
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.
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:
NOTE: The crash reports submission should not be viewed as an official support request. You will need to contact our Support team as per normal and where possible include a reproduction case, the crash report ID and any additional information about the context of the crash.
TP 117947 / BZ 49963 - The following additional Asset API functions have been exposed in DefaultAssetPlugin (C++) and Asset (OpScript):
TP 127956 / BZ 51571 - Basic support for Multi-sample anti-aliasing (MSAA) has been added in the Viewer tab. MSAA can be enabled, and the quality adjusted, from the Display > Anti-Aliasing menu in the Viewer tab.
NOTE: Full-quality MSAA may have a negative impact on real-time performance on lower-end machines.
TP 171824 - Katana's window titles and main menu bar have been improved cosmetically:
TP 176032 - The AttributeEditor node now supports keyboard shortcuts for enabling and disabling overrides. The D key toggles the disabled state of all selected items in the location table. Alt+D will disable all selected items.
TP 195293 - The file browser has been enhanced to be more consistent with other The Foundry products. Existing "Quick Links" will be preserved, and new links can now be added, edited and removed via the UI.
TP 199386 - Katana 2.5 ships with support for building C++ plug-ins using the CMake build system, removing the need to manually specify an ad-hoc set of Katana plug-in source files when compiling your plug-ins.
This takes the form of a CMake package file, located in plugin_apis/cmake. Importing this package file in your plug-in's CMakeLists.txt defines logical CMake targets corresponding to the various Katana API modules.
Katana’s own example plug-ins (in plugins/Src) have been updated to use this new build system, and their CMakeLists.txt files serve as a useful reference for build your own Ops and other plug-ins.
TP 199510 - When you launch Katana without previously having set up licensing, a Licensing dialog now appears to help you set up licensing for Katana.
TP 199701 - OpScript bindings for pystring's os.path methods have been added:
pystring.os.path.basename(string path) -> string pystring.os.path.dirname(string path) -> string pystring.os.path.isabs(string path) -> boolean pystring.os.path.abspath(string path, [string cwd]) -> string pystring.os.path.join(string component, [string component...]) -> string pystring.os.path.normpath(string path) -> string pystring.os.path.split(string path) -> string, string pystring.os.path.splitdrive(string path) -> string, string pystring.os.path.splitext(string path) -> string, string pystring.os.path.expanduser(string path) -> string pystring.os.path.expandvars(string path) -> string pystring.os.path.sep pystring.os.path.pathsep
TP 200857 - In parameter expressions, the globals object has been renamed to project to better reflect its purpose. It is still available under its old name.
Additionally, the following new values are available:
TP 215991 - The Alembic_In node now supports varying normals.
TP 216166 - Shelf scripts have been added to upgrade ScenegraphGeneratorSetup nodes with the generatorType set to ScenegraphXML to ScenegraphXML_In nodes, and AttributeModiferDefine nodes with modifierType set to AttributeFile to AttributeFile_In nodes.
These can be run globally from the shelf menu on the main window toolbar, or for a specific node from the shelf menu in the Parameters tab.
TP 216250 - AttributeScript per-location cook latency has been reduced by approximately 70%.
TP 216318 - The following API functions have been added for working with Look File Materials in GafferThree edit packages in Python:
They work in similar ways to the functions of the same names that are available on creation packages. Further information is available in their docstrings.
TP 217995 - Two new parameter expression variables have been added to allow easy cross-platform project configuration:
TP 219480 - Node names may now start with a numeric character.
TP 219509 - You can now browse for executables when setting up externalTools preferences in the Preferences dialog.
NOTE: For details of API changes and important information for developers, please refer to the accompanying Katana 2.5v1: API Changes and Compatibility document.
TP 71169 - Katana's alpha/beta version number format now includes an internal build number rather than an incremental number. Version numbers for stable releases are unchanged.
TP 118939 / BZ 50166 - The hotRender parameter from RenderManager.StartRender() is now deprecated.
TP 169121 - Python and Qt in Katana now use UTF-8 encoding by default.
TP 176527 - The Viewer Modifier Plug-in API as been updated: the ViewerModifierInput class now provides an isLookedThrough() method that can be used to alter the GL representation of a location if it is currently being looked through. This method takes an optional boolean argument, includeChildren (defaulting to false), that allows descendants of looked-through locations (such as light filters) to do the same if they so wish.
NOTE: Katana no longer automatically hides looked-through custom Viewer Modifiers. In order to replicate the behaviour of earlier versions of Katana, custom Viewer Modifier Plug-ins for locations of type 'camera' and 'light' should, in their draw function, call isLookedThrough() and return without drawing if the return value is true.
TP 187661 - The Help and Live Render Control tabs, which were deprecated in Katana 2.0, have been removed.
TP 189071 - The Foundry's Katana plug-ins for Arnold 4.1 and 4.2 have been removed; customers should use Solid Angle's KtoA plug-in.
TP 196747 - The keyboard shortcut for cancelling a render has changed from Esc to Ctrl+..
TP 198690 - Scene Graph Generator and Attribute Modifier plug-ins are now regarded as legacy APIs. Katana for Linux will continue to support customer-written SGG and AMP plug-ins, but we do not recommend these APIs, which have been superseded by the Op API.
TP 199106 - The Foundry's Katana plug-in for RenderMan 17 has been removed; customers should use Pixar's RfK plug-in where available.
TP 199475 - The following obsolete node types have been removed:
TP 218341 - The Linux "katana" launcher script no longer adds Katana's internal OpenSSL directory to LD_LIBRARY_PATH. This may affect the version of libcrypto/libssl used by subprocesses spawned from customer plug-ins and scripts. Katana itself continues to use its internal copy of libcrypto and libssl.
TP 17359 / BZ 19475 - The Copy Path to Clipboard option in the Monitor tab didn't work.
TP 57220 / BZ 29054 - The View Fullscreen item in the Layouts menu could become out-of-sync with the fullscreen state after switching to a layout which was saved in fullscreen mode.
TP 60133 / BZ 31466 - The File > Save As keyboard shortcut was previously unavailable on some desktop environments, including Windows and KDE.
TP 64048 / BZ 34074 - When using the context menu for the file path text widget in the file browser dialog, the Cut, Copy and Delete commands would have no effect.
TP 65343 / BZ 34945 - When renaming a user parameter, invalid characters were replaced with underscores, and name conflicts (the use of a name that is already used for another user parameter on the same node) were resolved by incrementing the number at the end of the parameter's name. In both of these cases, a misleading warning about name conflicts was displayed in the Rename Parameter dialog.
The warning message was inaccurate in the case where the name of a parameter was being modified due to the use of invalid characters, rather than because of a conflict with the name of an existing user parameter.
TP 101300 / BZ 46874 - Katana used unix domain sockets in the Katana temporary directory for communication with processes that host AttributeScripts and Python Asset plug-ins. As filesystem paths for unix domain sockets cannot exceed 108 characters in length, this imposed a limitation on the length of the Katana temporary directory path. This communication now happens over TCP, and so the limit on temporary directory path length no longer applies.
TP 101658 / BZ 46954 - Copying nodes from the Node Graph tab will now store them in the default clipboard buffer as well as the selection buffer.
TP 105002 / BZ 47454 - The GafferThree parameter interface scene graph view displayed nothing if the incoming scene was invalid and Show Incoming Scene was enabled. Error locations are no longer removed from this view.
TP 110272 / BZ 48574 - It was not possible to assign a Look File Material to an adopted GafferThree package using the popup of the Shader column.
TP 117465 / BZ 49877 - With a large number of nodes in the node graph, various node graph operations would cause Katana to freeze while evaluating the effect of the operations on any 2D renders.
TP 128448 / BZ 51652 - We have made general improvements to the reliability of Python asset plug-ins and AttributeScripts. In particular:
TP 130041 / BZ 51851 - The Viewer's Quick Editor did not respond correctly to mouse interaction.
TP 171963 - During interactive rendering, certain actions such as Undo and Redo, or anything that calls Utils.EventModule.ProcessAllEvents(), could cause the UI to temporarily lock up.
TP 174049 - Constraints added to a location with an existing resolved constraint of the same type were not be created with a unique constraint name, resulting in the existing constraint's xform group being overwritten on resolution.
TP 174138 - Addressed an unlikely race condition in the getSuite() function of many PluginApi classes. Plug-in authors will need to recompile against the new PluginAPI sources to benefit from the fix.
TP 175487 - When looking through a camera in the Viewer tab, the camera's scale was not respected. Scale now contributes to the projection when looking through locations of type 'camera'.
TP 176635 - When editing user parameters on a node in the Parameters tab, group parameters that were hinted to use specific widget types, e.g. Color Ramp, Float Ramp, or Gradient, were shown with a regular group parameter appearance, thereby wrongly exposing underlying child parameter structures and making them editable.
TP 194321 - Node connections in a nested Live Group were not restored correctly following a change to a Graph State Variable that caused the nested Live Group to be reloaded.
TP 196371 - Katana occasionally printed "Broken pipe" error messages in the render log when terminating a render.
TP 197079 - Two inconsistencies in the interaction with connections of Shading Nodes have been resolved:
TP 197267 - When switching away from the Radius viewer manipulator for a light with a zero radius, Katana raised an exception.
TP 197786 - GafferThree nodes did not display non-lighting locations from the incoming scene.
TP 197890 - Calling the RendererInfoBase::addRenderObjectParam() function from a renderer info plug-in's buildRendererObjectInfo() function always created parameters of type string in corresponding <Renderer>OutputChannelDefine nodes, irrespective of the type of parameter passed to the function, e.g. kFnRendererObjectValueTypeInt.
TP 197933 - A limitation in the Lua runtime that prevents OpScripts from working with attributes with more than 227 values has been documented in the Developer Guide.
TP 198125 - When a user chose an option from a registered LayeredMenuAPI.LayeredMenu that did not create a node, whatever action was performed was immediately undone.
TP 199322 - Live renders failed when the host name of an artist's workstation could not be resolved. Katana now falls back on 'localhost'.
TP 207560 - Handling of UI updates in response to changes of parameters of nodes in the node graph document has been revised to cause fewer unnecessary updates.
TP 208503 - Some operations modified or read the X11 selection buffer but not the main clipboard. All such operations now work with both the X11 selection buffer and the main clipboard.
TP 215272 - When dragging on the label of the red, green, or blue component of a color parameter in the Parameters tab, the sliders and resulting color were not updated interactively, but rather on pen-up only.
TP 216082 - Some buttons that provide a menu when clicked, e.g. the Add Locations button in the parameter interface of AttributeSet nodes, prevented the mouse wheel from scrolling parameters or attributes when the buttons were disabled, e.g. for locked nodes.
TP 216441 - When making changes to the node graph document, such changes were occasionally communicated to widgets that had been deleted, which could lead to RuntimeError exceptions being raised from UI code.
TP 217611 - Interacting with checkboxes in the GafferThree UI added too many undo entries. Undoing/redoing these entries could leave the GafferThree in an inconsistent state.
TP 217868 - Setting a hint string on a parameter using NodegraphAPI.Parameter.setHintString() did not create an undo entry, and did not mark a Katana project as dirty. This also meant that hint strings were not restored correctly when undoing and redoing groups of undo entries that included making changes to a parameter's hint string.
TP 217931 - Redoing actions that both created and renamed nodes raised an exception.
TP 218121 - When removing input or output ports from nodes, the removed ports still pointed to the nodes that they were previously a part of. This could lead to use-after-free crashes when undoing and redoing groups of undo entries that included the addition and removal of ports.
TP 218315 - The parameter UI of editing constraints in GafferThree nodes was rebuilt whenever the incoming scene changed, causing noticeable flickering.
TP 218363 - When choosing the Select in Scene Graph command of parameters or attributes that referenced scene graph locations through relative paths, exceptions were raised.
TP 218368 - When calling certain functions from the ScenegraphManager module with invalid arguments, multiple exceptions were raised from various event handlers. Now, when calling functions from that module with invalid arguments, TypeError or ValueError exceptions are raised from that module itself.
TP 221166 - The list of lights and cameras in the Viewer tab's Look Through Lights and Cameras popup did not include the render camera that is set in the renderSettings.cameraName attribute at /root.
TP 221170 - The Select in Scene Graph command of scene graph location parameters or attributes could not resolve absolute location paths that made use of relative components.
TP 224642 - RenderOutputDefine nodes with a type of "script" or "prescript" would incorrectly tokenise the scriptCommand parameter prior to resolving each token using the active asset plug-in's resolvePath() method.
TP 225183 - RenderManager's StartRender() function, when operating in synchronous mode, could fail to report the last received render messages via the render message callback.
TP 218742 - (Windows only) Katana must be installed to a path no longer than ~140 characters. Attempting to install to a longer path results in an unintuitive error: "The system cannot find the path specified."
TP 208936 - If the KATANA_FILEBROWSER_QUICKLINKS environment variable contains paths which share a basename (e.g. "/tmp/shot_a/assets:/tmp/shot_b/assets"), only one of the paths is added as a favorite in the file browser.
TP 208802 - Closing the Histogram tab after use leaves the Monitor tab unable to display rendered images.
TP 207623 - When entering a single number only in a Backdrop node, that number is not preserved when saving a Katana project or when copying and pasting that node.
TP 199304 - The namespace parameter on Material nodes wrongly allows the insertion of Unicode codepoints outside the ASCII range.
TP 191052 - Katana does not have any support for the texture reference object work-flows of V-Ray for Maya.
TP 188533 - Expressions linked to non-local parameters on not previously edited Material nodes can't be evaluated.
TP 176598 - Use of nodes that modify Graph State Variables in Interactive Render Filters is not currently supported.
TP 123558 / BZ 50911 - When changing an array parameter's tuple count/size, any corresponding attributes are not properly updated in the Attributes tab.
TP 114182 / BZ 49288 - When exporting a Catalog item you need to specify the export folder path to an existing folder. If the folder you're trying to export to does not exist on disk Katana will fail to export.
TP 112544 / BZ 49051 - The Viewer tab may lose sync with the Scene Graph tab when changes to expansion state are interrupted.
TP 107038 / BZ 47853 - Indication of attribute source nodes (such as the yellow 'glow' in the Node Graph tab) is not yet implemented in Katana 2.
TP 105434 / BZ 47520 - Reference Expressions may not refer to dynamic parameters such as shader parameters.
TP 85118 / BZ 41152 - When editing parameters of a node that is part of a LiveGroup node and reloading the parent LiveGroup node, the UI state of the Parameters tab is reset. This includes scroll bar positions, selections of items, and selections of nested tabs (for example Object, Material and Linking tabs for a Gaffer node).
TP 84998 / BZ 41092 - When reloading a LiveGroup node's parameter interface and contents from its source, parameters of child nodes that are edited in floating panes disappear from those panes.
TP 84326 / BZ 40709 - The Alembic library does not support multiple process or thread access to an Alembic file. This means that a crash occurs when modifying an Alembic file outside Katana, while it's loaded in an open Katana scene. To avoid this, you must Flush Caches before attempting to update any modified Alembic files.
TP 84020 / BZ 40598 - Reverting a LiveGroup node does not revert its user parameters.
TP 84019 / BZ 40599 - User parameters of non-editable LiveGroup nodes can incorrectly be edited.
TP 84018 / BZ 40600 - Undoing a revert of an unpublished LiveGroup node does not restore the LiveGroup's editable and modified state.
TP 83061 / BZ 40237 - Nodes can be dragged into the Group bubble of a non-editable LiveGroup node.
TP 80738 / BZ 39261 - Operations that lock and unlock nodes do not currently create entries in the Undo History, which can lead to an incorrect node graph state when undoing and redoing operations.
TP 74799 / BZ 36926 - The rendererSettings > displayOptions parameter of a RenderOutputDefine node for the PRMan renderer, shown when its type parameter is set to raw, cannot be set using the Parameters tab.
For a workaround, the UpdatePrmanSettingNodes shelf script can be used. The script, available in the PRMan17 shelf, creates an AttributeScript node that converts display options, set using string attributes, to group attributes.
TP 71965 / BZ 36691 - State badges are currently shown for attribute values of dynamic array child parameters, even though only their parent array parameter should appear with a state badge.
TP 71954 / BZ 36663 - It is not currently possible to sort notifications in the Notifications popup window.
TP 70217 / BZ 36176 - The 2D node Disk Render Upstream Render Outputs option does not use the batch render method, batchRender, for upstream render nodes, instead using diskRender.
TP 70196 / BZ 36170 - Control keys (notably arrow keys) do not function as expected in shell mode.
TP 65347 / BZ 34949 - Using Compiz can lead to text fields not receiving focus events correctly due to an incompatibility between Compiz and QT. Depending on your configuration, disabling Compiz "desktop effects" may resolve the problem.
TP 65242 / BZ 34870 - Katana doesn't support render output directory creation for shadow, merge and script output types.
TP 60457 / BZ 31790 - Setting an array or group parameter to an expression results in an invalid expression. Upon setting a valid expression (for example, an evaluation of an equivalent parameter on another node using getParam), the parameter is not immediately updated. To workaround this issue, close and reopen the parameter, or flush caches while the node is not edited.
TP 56545 / BZ 28549 - Main menu commands that create nodes, notably File > Import..., File > Import LiveGroup..., and Help > I want a pony, do not create the nodes in a Group or LiveGroup node that has been entered in a Node Graph tab, instead they create the nodes in the root level of the node graph document.
TP 12517 / BZ 16168 - Only one Monitor tab may display the results of a Preview Render. The use of multiple Monitor tabs is not currently supported.
Copyright © 2016 The Foundry Visionmongers Limited