Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# Katana 3.0v1 Release Notes

# Introduction

These release notes describe changes from Katana 2.6v4 to 3.0v1 in detail.

For a high-level overview of all changes in the Katana 3.0 line, see What's New in Katana 3.0.

# Release Date

30 May 2018

# Previous Releases

• Release Notes for Katana 2.6v4

# System Requirements

## Officially Supported Operating Systems

- Windows 7 64-bit or higher
- Linux 64-bit operating system (CentOS/RHEL 6)

## Hardware Requirements

| Minimum | Recommended
--- | --- | ---
CPU | Dual-core processor
Storage | 1+ GB available for installation
System RAM | 1+ GB available
Graphics RAM | 1+ GB available | 2+ GB available
Display | 800 x 600 | 1920 x 1080
OpenGL | OpenGL 4.3+

'Recommended' does not guarantee that it meets your particular needs

## Tested Workstation Hardware

The configurations listed below are those that Foundry have tested with Katana. Due to the constantly changing nature and wide variety of computer hardware available in the market, Foundry is unable to officially certify hardware. The list below can be used as a recommendation and does not guarantee that it meets your particular needs.

- NVIDIA Quadro M4000

- NVIDIA Quadro P4000

- NVIDIA Quadro K4000

- NVIDIA Quadro K6000

Please download and install the latest graphics driver from the NVIDIA website.

If you encounter any issues, please contact Customer Support directly through the Support Portal at the following address: https://support.foundry.com.

# New Features

## 3Delight Renderer

Katana now bundles 3Delight: a uni-directional path-tracer designed to withstand the high demands of production rendering. Workflow options for the 3Delight plug-in include:

- Fully interactive live rendering (add, subtract, modify lights, objects, materials and cameras)
- Simplified render pass management and sampling controls
- Interactive Light Mixing via the Multilight tools and the GafferThree node
- Fast atmosphere rendering for all light types with deep output
- Unified light sampling across all light types
- Support for Cryptomatte workflows
- Fully OSL shading engine

The Katana installer presents 3Delight as an optional component of the Katana installation. 3Delight can be used for free in preview and live renders. Disk and batch rendering requires a 3delight_r license to remove watermarks; please contact sales@foundry.com for further information. Katana's example projects now use 3Delight where a renderer if required.

Note: Katana continues to support other renderers via the renderer-agnostic Renderer Plug-in API.

## Hydra-Powered Viewer

Katana 3.0 includes a new 3D scene viewer tab that is substantially more interactive and scalable than the existing Viewer tab.

The new viewer is powered by Hydra, a modern, scalable OpenGL rendering architecture that was developed at Pixar Animation Studios as a key component of the open source Universal Scene Description (USD) project.

The Viewer (Hydra) tab is implemented using Katana's Viewer API, which has been revised and expanded from Katana 2.6.

# Performance Improvements

## Application Start-up

- TP 81173 / BZ 39462 - Katana no longer attempts to access files in /workspace and /shots on start-up.

- TP 234052 - Katana no longer attempts to access files in /net on start-up. These attempts could trigger automounting behaviour, causing delays to Katana startup.

- TP 279489 - Improved start-up time by reducing the time taken to generate the Katana Python module.

## Node Graph

- Improved performance of the node graph through better management of the node namespace.

- Improved performance of node graph event handling and Op tree synchronisation.

- Improved performance of automatic renaming of parameter expressions in the node graph.

## Scene Graph

- TP 311882 - Improved drawing performance of the Scene Graph tab when large numbers of locations are pinned.

  A locationHasPinnedDescendants() method has been added to the ScenegraphManager.Scenegraph class.

- TP 340612 - Improved drawing performance of the SceneGraphView widget, which powers the Scene Graph tab and GafferThree's table of objects.

## GafferThree

- TP 311323 - The UI performance of GafferThree nodes and other PackageSuperToolAPI-based nodes has been improved.

## Rendering

- TP 303663 - Deleting a Catalog item for a completed Interactive Render now frees the associated image memory immediately.

- TP 303768 - Improved memory handling in Katana's display driver, where the message queue size was not limited by default. The display driver now respects the environment variable KATANA_PIPE_MAX_QUEUE_SIZE. If not set, it will default to 16384.

- Improved performance of the render log mechanism during batch renders when renders produce a lot of log output.

- TP 312192 - Improved performance of the Monitor tab's handling of image updates from the renderer.

- TP 327156 - It is now possible to configure pixel data sent to Katana via the Display Driver API as either RGBA or ARGB. RGBA is the internal pixel format used by Katana and using this pixel format ensures Katana does not have to do a channel swizzle to re-order the alpha channel. The following example demonstrates how enable this channel pixel format:

      NewChannelMessage_v2Ptr newChannelMessage_v2(
          new FnKat::NewChannelMessage_v2(*newFrameMessage));
      // Setup NewChannelMessage_v2
      newChannelMessage_v2->setChannelID(/* Channel ID */);
      newChannelMessage_v2->setChannelOrigin(0, 0);
      newChannelMessage_v2->setChannelDimensions(1000, 1000);
      newChannelMessage_v2->setSampleRate(sampleRate);
      newChannelMessage_v2->setDataSize(4 * sizeof(float));
      newChannelMessage_v2->setPixelLayout(FnKat::NewChannelMessagev2::PixelLayout::RGBA);
      newChannelMessage_v2->setChannelName(legacyChannelName);

- Improved performance of Katana's display driver API, including reduced memory allocation and message transmission overhead.

  A new 'zero copy' option for DataMessage types has been introduced. This allows display driver authors to transfer ownership of a pixel buffer to the display driver API, which significantly reduces pixel copy and memory allocation overhead. For example:

      // Pixel buffer clean-up callback.
      void ImageDataDeleter(void* data)
      {
          char* dataArray = reinterpret_cast<char*>(data);
          delete[] dataArray;
      }

      // Sending pixel buffers back to Katana...
      FnKat::DataMessage dataMsg(/* ... */);
      // Configure coordinates/dimensions unchanged...

      // Allocate pixel buffer...
      char *dataArray = new char[blockSize];

      // NEW: Pass pixel data clean-up callback to setData() and the Display Driver
      // API will take ownership of the pixel buffer.
      dataMsg.setData(dataArray, blockSize, ImageDataDeleter);

      // Send to Katana via Katana Pipe interface
      pipe->send(dataMsg);

## Asset Plug-ins

- The default File Sequence plug-in which ships with Katana has been re-implemented in C++ to replace the Python implementation. The use of Python-based File Sequence plug-ins is not recommended, and support will be removed for these plug-ins in a future release of Katana. (See Deprecations section below.)

## CEL Matching

- Improved performance of CEL matching.

- Addressed inconsistencies and improved performance of CEL Value Expressions. These are the expressions that appear in curly braces and make assertions about the path being matched. For example, the CEL expression /root/world/*{ @type == "camera" } tests children of /root/world using the value expression @type=="camera".

  Indexing of multi-value attributes now works consistently. The expressions /foo/bar{attr("myAttr", 1)} and /foo/bar{@myAttr[1]} continue to be identical -- they index the second element of "myAttr" at /foo/bar (which must have at least two elements). Previously negative indices were only allowed using the 'attr()' syntax, so /foo/bar{attr("myAttr", -1)} was allowed but /foo/bar{@myAttr[-1]} was not. Both syntaxes now accept negative indices, which have the same semantics as Python: they index from the end of the array, with the index -1 referring to the last element.

  These changes may cause behaviour changes to some pathological CEL expressions, but should not affect standard usage. If you find this is not the case, please report issues.

  NOTE: Arithmetic operations on mixed types now consistently evaluate to undefined ('not-a-value'). This was not always the case in the previous implementation, which could perform some surprising type conversions. This also affects behaviour of equality tests on attribute values where the attribute does not exist. For example, the following CEL expression will not select any locations in Katana 3.0 if myAttr does not exist: /root/world/geo/*{@myAttr == 0.0}. If the intent is for the assertion to succeed if myAttr is falsy (0.0, "", or null) then the following expression should be used: /root/world/geo/*{not @myAttr}.

- TP 336919 - A null constant has been added to the Collection Expression Language (CEL). The null value indicates an attribute is missing or is a NullAttribute.

  CEL expressions like @myAttr and attr("myAttr"), etc can be compared with the null constant to check for missing attributes and for NullAttribute values. For example, //*{attr("missingAttr") == null} matches any location which does not have an attribute named missingAttr or where it is a NullAttribute.

## Op Types

- Improved performance of the AlembicIn Op by making use of FnAttribute's ability to take ownership of user supplied data.

- Improved performance of the AttributeSet Op for the common case where a single set of attribute modifications are applied at a given location.

- TP 286382 - Improved performance of the ConstraintResolve Op. Specifically:

  - Improved performance where the globals.constraintList attribute at /root/world has a large number of paths.
  - Improved performance of the FnGeolib::Path::IsAncestor, FnGeolib::Path::IsAncestorOrEqual functions (C++) and PathUtils.IsAncestor, PathUtils.IsAncestorOrEqual functions (OpScript)
  - Introduced FnGeolib::Path::Compare function (C++) and PathUtils.Compare function (OpScript) to compare normalized scene graph location paths. This function can be used to implement a comparator for std::sort (C++) or table.sort (Lua).

- Improved performance of the LookFileResolve Op and the FnLookFile methods of FnGeolibServices.

- Improved performance of the OpScript Op.

- OpScript nodes have been upgraded to use LuaJIT 2.1.0 as their Lua interpreter, which should result in general performance improvements as well as laying the foundation for future improvements. The change should be generally transparent, however the previous OpScript implementation based on Lua 5.1 is still available should you encounter issues with the LuaJIT-based one. This implementation can be selected by setting the environment variable KATANA_OPSCRIPT_INTERPRETER to Lua_5_1.

  LuaJIT follows the Lua 5.1 language standard more strictly, and some Lua 5.0 constructs that were grandfathered into Lua 5.1 are not available in LuaJIT. These are:

  - the `math.mod()` function; use `math.fmod()` or the `%` operator instead.
  - the implicit `arg` parameter for old-style vararg functions; use Lua 5.1 vararg expressions (`...`) instead
  - the `string.gfind()` function; use `string.gmatch()` instead

  Note that we build LuaJIT 2.1 in "GC64" mode so that OpScript is not subject to the address-space limitations of earlier LuaJIT releases.

  For further information, see:

  - Lua 5.1 reference manual
  - Lua 5.2 extensions backported to LuaJIT

- TP 282745 - The scalability of the OpScript Op in concurrent renders has been improved by reducing lock contention. This also resolves an issue where flushing caches would not flush an internal cache in the OpScript Op.

## FnAttribute

- The implementation of FnAttribute has been made more performant:

  - Static attributes: certain attributes (such as integers [0, 256], floats 0.0f and 1.0f, doubles 0.0 and 1.0, the empty string and the empty group) are now created only once and then reused subsequently. That means their reference counts don't have to be incremented and decremented.
  - Move constructor and operators: these new operators (C++11) have been implemented in FnAttribute. If a new compiler is used, it will detect when an object can be moved, meaning that its reference count won't have to be incremented and decremented.

  Note: Katana 3.0v1 uses a different algorithm to calculate attribute hashes, and so attribute hashes will differ from those in Katana 2.x.

- TP 309635 - The behaviour of DataAttribute's getNearestSample() method has changed, and in some cases this will require code changes in order to build C++ plug-ins against the Katana 3.0 APIs.

  In previous releases of Katana it was possible to obtain a raw pointer to a sample buffer by calling getNearestSample(time).data(). For performance reasons, as of Katana 3.0 this idiom is disallowed, and results in a compile-time error. FnAttribute now requires that the ConstVector object returned by getNearestSample() is assigned to a local variable before calling its data() method. Some examples follow:

      // Works with both Katana 2 and Katana 3. `p` is valid until either of `sample`
      // or `myIntAttr` are destructed.
      auto sample = myIntAttr.getNearestSample(.0f);
      const int* p = sample.data();

      // Results in a compile-time error in Katana 3.
      const int* p = myIntAttr.getNearestSample(.0f).data();

  To facilitate getting raw pointers to sample buffers of multi-sampled DataAttribute objects, Katana 3.0 introduces a new C++ API in the form of the getSamples() method. Some examples follow:

      for (const auto& sample : myIntAttr.getSamples())
      {
          ProcessSample(sample.getSampleTime(), sample.data(), sample.size());
      }

      // Assign the result of `getSamples` to a local variable if you want pointers to
      // remain valid for longer. Here, the raw pointers stored in `vec` remain valid
      // until either the `myIntAttr` or `samples` objects are destructed.
      auto samples = myIntAttr.getSamples();
      vector<tuple<float /*time*/, const int* /*data*/, size_t /*size*/>> vec;
      for (const auto& sample : samples)
      {
          vec.emplace_back(sample.getSampleTime(), sample.data(), sample.size());
      }

  Additionally, a new getValuesAs() function has been added that returns a C++ object constructed with a fixed number of values from the attribute's primary time sample. For example, if you have a FloatAttribute representing a 4x4 matrix, you can convert it to an Imath matrix object using code similar to:

      auto m44f = myFloatAttr.getValuesAs<Imath::M44f, 16>();

- FnAttributes are now able to take ownership of the data buffers they are constructed with. This can help reduce peak memory usage and reduce overall render times as the data does not need to be copied into the FnAttribute's internal buffers.

  For an FnAttribute to take ownership of the data buffer callers must pass a deleter function and non-null data pointer (context) to the FnAttribute's constructor. This will result in the following:

  1. The FnAttribute will take copies of the values of the sample times i.e. {-0.5, 0.0, 0.5}.
  2. It will copy the value of the pointers for each time sample buffer (the pointer, not what it points to).
  3. On destruction, the attribute will call the user-supplied function, passing the user-supplied context to it; see below for example use cases.
  4. The sample buffers and user-supplied context (they can be different) must remain valid for the lifetime of the FnAttribute which has taken ownership of the data.

  Example Usage:

      // -----------------------------------------------------------------------------
      // Create an IntAttribute with a single time sample of 10 values.

      int64_t tupleSize = 1;
      int64_t valueCount = 10;

      // Create a buffer to store our data -- this must live on the heap, as the
      // attribute we create stores pointers into this memory block.
      unique_ptr<int[]> buf(new int[valueCount]);

      // Fill `buf` with data.
      // ...

      FnAttribute::IntAttribute myIntAttr(buf.get(), valueCount, tupleSize, buf.get(),
                                          [](void* context) {
                                            delete[] static_cast<int*>(context);
                                          });
      // myIntAttr now owns the buffer.
      buf.release();

      // -----------------------------------------------------------------------------
      // Create a FloatAttribute with three time samples of 64 values.

      int64_t tupleSize = 4;
      int64_t valueCount = 64;

      int64_t sampleCount = 3;

      // Create a buffer to store our data -- this must live on the heap, as the
      // attribute we create stores pointers into this memory block.
      unique_ptr<float[]> buf(new float[valueCount * sampleCount]);

      // Fill `buf` with data.
      // ...

      // FnAttribute copies these buffers into internal storage; they need not live on
      // the heap.
      const float* samples[] = {&buf[valueCount * 0],
                                &buf[valueCount * 1],
                                &buf[valueCount * 2]};
      float sampleTimes[] = {-0.5f, 0.0f, 0.5f};

      FnAttribute::FloatAttribute myFloatAttr(sampleTimes, sampleCount, samples,
                                              valueCount, tupleSize, buf.get(),
                                              [](void* context) {
                                                delete[] static_cast<float*>(context);
                                              });
      // myFloatAttr now owns the buffer.
      buf.release();

## Geolib3 Runtime

- The computation and memory overhead for 'no-op' scene graph locations has been greatly reduced. This can significantly improve scene cook time (and hence render time) and memory usage for recipes in which many Ops with well-defined scope operate on a large input scene.

- An experimental feature has been added which disables Geolib3's normal behavior when handling requests for scene graph location data within an Op which has not yet been cooked (or is not present in Geolib3's cache). Normally Geolib3 would abort the current cook operation and cook the requested location, in cases where the Op had already completed computationally expensive tasks these would be lost. When this feature is enabled, when Geolib3 encounters missing location data it will instead recursively cook that data and then return to the original Op at the point the location data was requested. This feature can be enabled by setting the following environment variable: KATANA_ENABLE_RECURSIVE_COOKS=1.

- A core component of the Geolib Runtime responsible for manipulation and storage of scene graph location paths has been rewritten. The changes are part of an incremental process of under-the-hood changes to facilitate future performance improvements. These changes do not affect scene processing and are intended to be performance-neutral for the most part -- however customers may notice improved performance of some methods provided by the Geolib Cook Interface that accept or return scene graph location paths.

- The signatures of a number of API functions in FnGeolib and FnAttribute have been updated to avoid taking string parameters by const std::string& and instead take them as lightweight "string view" objects. This change is designed to be source-compatible with existing plug-ins, and is part of an ongoing effort to reduce the number of temporary memory allocations made by Katana.

- TP 251955 - Fixed a rare issue introduced in Katana 2.0v4, in which Geolib's internal cache of cook results could behave unpredictably, leading to poor performance during scene cook. This issue did not affect scene correctness.

- TP 232097 - Improved performance of the cook interface's getOpType() function.

- Improved performance of the FnGeolibOp::GetGlobalAttr() (C++) and Interface.GetGlobalAttr() (Lua) functions.

  C++ plug-in code using the lower-level FnGeolibServices::getGlobalAttrGeneric() function will need to be updated: the previous FnGeolibServices::BaseGlobalAttributeProvider abstract base class has been renamed to BaseGlobalAttributeProviderLegacy and is considered deprecated. Plug-in code using this class should migrate to the revised BaseGlobalAttributeProvider interface.

- Improved performance of the FnGeolibUtil::Path::FnMatch() (C++) and PathUtils.FnMatch() (Lua) functions.

- TP 327987 - Slightly improved performance of execOp().

- TP 329845 - Slightly improved performance of getAttr() when called inside an Op invoked by execOp().

- Slightly improved performance of GeolibCookInterface methods.

# Feature Enhancements

## Revised UI Theme

The Katana UI theme and color palette have been updated to achieve an overall flatter appearance that is more consistent with modern Foundry applications.

Notable changes are:

- Thicker 3D bevels have been replaced by single-pixel outlines.
- The titles of tabs that are not selected are shown in the darker color of splitters between panes, as in Nuke.
- Parameter editing widgets in an editable state are shown with a background color that's darker compared to the normal background color of Parameters tabs, instead of brighter. They are still shown with a brighter background color when in a read-only state.
- The command area at the bottom of the Python tab is also shown with a darker background color, to emphasise that users can enter Python commands there, with results of code evaluation being shown in the read-only, brighter area at the top.
- Menu items and selected text are now highlighted with black text on a yellow background. This also applies to titles of open menus, to emphasise menu item hierarchy.
- Locations that are selected in the Scene Graph tab or in the Parameters tab are highlighted with white text on a gray background color.
- Splitters between panes, highlighted parameters, attributes, and project settings, as well as possible drop targets during drag & drop operations, are now highlighted in the same yellow color that is used for highlighting menu items and selected text.
- Selected nodes, their ports, and connections between nodes are now highlighted in the same yellow color that is used for highlighting menu items and selected text.
- The subtle gradient of vertical dividers has been replaced with single-pixel solid lines.

A small number of cases where wrong palette colors are used (for example text that appears in black) remain to be fixed. We also plan to make further refinements to the color palette in order to improve contrast ratios for better readability.

## Tabs and Layouts

- TP 248121 - A new getMenuBar() function was added to the UI4.App.MainWindow.MainWindow class and to the UI4.Tabs.BaseTab.BaseTab class, and was implemented for all built-in types of tabs that provide a menu bar:

  - Node Graph tab
  - Monitor tab
  - Catalog tab
  - Viewer (Hydra) tab
  - UV Viewer tab
  - Viewer tab
  - Python tab
  - Messages tab

  The new API functions allow developers of customization code to access the menu bar of Katana's main window and the menu bars of tabs that provide a menu bar in a public, consistent way, without having to rely on private member variables of tab classes.

- TP 279781 - Custom tabs can now be nested in hierarchies of submenus within Katana's Tabs main menu, by specifying the name of the plug-in using slashes, e.g.:

      PluginRegistry = [("KatanaPanel", 2.0, "Company/Show/Custom", CustomTab)]

- The listing of types of tabs in Katana's Tabs main menu has been reorganized, and the display of tab titles has been refined:

  - Tabs are now organized in separate sections by tab plug-in search path. The titles of separators can be customized by placing a file named separatorTitle.txt in a Tabs folder within a KATANA_RESOURCES directory. The first line of text from those files is used as a separator title.
  - The CEL Scratch Pad tab has been moved from being a Core tab plug-in to being a built-in type of tab.
  - The text of the menu command for showing parameters of selected nodes in floating panes that is available for overrides when editing the parameters of LookFileManager nodes has been updated for consistency:
    - Old text: Tear-off Parameters of Override...
    - New text: Show Parameters in Floating Pane
  - The appearance of titles of tabs and of window titles of floating tabs has been modified to remove the names of menus in which those tabs are nested, e.g. Hide/, and Debug/.
  - The Example Projects tab has been renamed to use a "Hide/" prefix in order to hide it from the Tabs menu. Layouts that are loaded that previously contained a tab of that type will show an error instead now.

- TP 281102 - Additional functions for accessing components of specific types of tabs have been exposed in the public API of tab classes:

  - Node Graph tab: NodegraphPanel.getNodeGraphWidget() -- returns the tab's node graph widget that implements the drawing of nodes.
  - Monitor tab: MonitorPanel.getEmbeddedCatalogTab() -- returns the Catalog tab that is embedded inside of the Monitor tab, which can be switched to by pressing the Tab key.

  The above functions can be used to customize the appearance of tabs of the above types, for example from Katana startup scripts that contain a callback of type onTabCreated:

      from Katana import Callbacks

      def onTabCreated(objectHash, tab):
          pass  # ...

      Callbacks.addCallback(Callbacks.Type.onTabCreated, onTabCreated)

- TP 282368 - A new callback type named onTabCreated has been added. Callbacks that are added for that type will be called whenever a tab is created in Katana's UI, with the tab object passed as a keyword argument named tab.

- The default layouts in Katana's Layouts menu have been updated.

## User Interface

- TP 63442 / BZ 33772 - The appearance of checkbox widgets, radio button widgets, and toggled menu items has been updated:

  - Exclusive and non-exclusive toggled menu items now appear in different styles, consistent with the Nuke family of products:
    - Exclusive toggled menu items appear in a radio button style.
    - Non-exclusive toggled menu items appear in a checkbox style.
  - Toggled menu items that are not checked now appear with empty indicator shapes, so that such toggled menu items appear visually different from menu commands.

- TP 81710 / BZ 39744 - When hovering over a parameter, attribute, project setting, or preference, a tooltip now appears (after a short delay), which may include the full name, help text, and attribute type of the respective item.

  When holding down the Ctrl key before hovering over a parameter, attribute, project setting, or preference, the tooltip that appears will also show all widget hints of the respective item, which can help in building and debugging custom parameter interfaces.

  As part of this feature enhancement, the behavior of clicking the label of a multi parameter, e.g. the label of the screenWindow parameter of CameraCreate nodes, has been changed: Previously, when clicking the label to expand the multi parameter, its label text was aligned roughly in the center of the Parameters tab, making it harder to collapse the parameter again. Now, the label text is aligned to the left, just like the text of group parameter widgets, making it possible to quickly expand and collapse multi parameters.

- TP 170062 - When browsing for a Look File using the Advanced > Add Look File using Browser menu command in the context menu of the Look Files item view of a LookFileManager node that is edited in a Parameters tab, the Add as Look File Globals checkbox is now turned off by default.

  A boolean preference has been added to control the state of the Add as Look File Globals checkbox in the Add Look File using Browser asset browser dialog: nodes/lookFileManager/addAsLookFileGlobalsDefault

- TP 263340 - The following two preferences have been added to the color category of preferences:

  - enableDisplayTransformDefault -- Controls whether the Enable Display Transform checkbox in color picker dialogs is turned on by default.
  - restrictRGBAComponentsDefault -- Controls whether the Restrict RGBA Components checkbox in color picker dialogs is turned on by default.

  As part of this work, the following additional changes have been made:

  - The effect of the Enable Display Transform checkbox is now immediately applied to the color thumbnail of the edited color parameter in the Parameters tab, in addition to affecting the appearance of the chosen color in the color picker dialog itself.
  - The Restrict RGBA Components checkbox is now only made available when an edited color parameter or preference provides an alpha component. For edited colors that only provide RGB components, the checkbox is made unavailable, as it does not apply in that context.

- TP 324312 - When clicking one of the following tool buttons for finding things after previously entering text to filter the respective listing by, the entered filter text is now selected when opening the popup, so that a new filter text can be entered without having to manually select the filter text:

  - Node Graph tab: Find Nodes
  - Parameters tab: Find Parameters
  - Scene Graph tab: Find Scene Graph Locations
  - Attributes tab: Find Attributes
  - Project Settings tab: Find Parameters

- The PrimitiveCreate node type's type parameter and the Material node type's materialPath parameter now use a drop-down menu widget with item text filtering.

- Controls that have the input focus are now shown with a focus rectangle, making it easier to identify them, and making pressing the arrow keys while an item view has the input focus easier to predict.

## Node Graph and Parameters

- TP 82828 / BZ 40170 - The wording regarding disk-rendering of dependencies in the Node Graph node context menu has been tweaked for clarity: the section title changed from Disk Render Dependencies Before to Disk Render Dependencies, while the menu items are renamed from Preview Renders and Disk Renders to Before Preview Renders and Before Disk Renders.

- TP 264677 - Attribute History is now available from the context menu of attribute-associated parameters in the Parameters tab. Attribute History/Inheritance pop-ups now display the attribute name and scene graph location. With multiple Attributes tab instances, opening an Attribute History/Inheritance pop-up no longer results in superimposed pop-ups being opened for each tab instance.

- TP 283931 - The Fit Backdrop Node to Selected Nodes command available in the Edit menu of Node Graph tabs can now be used when only one node is selected.

## Scene Graph and Attributes

- TP 17505 / BZ 19641 - An API function for customizing the location types at which to stop expanding or collapsing branches in the Scene Graph tab has been added:

  - SetStopAtLocationTypes(*locationTypes):
    - Sets the types of locations at which to stop expanding or collapsing the scene graph when using the Expand Branches To or Collapse Branches To menu commands, or when double-clicking a group location in the Scene Graph tab.
    - locationTypes: A sequence of names of types of locations at which to stop expanding or collapsing the scene graph.

  For example, the function can be used in startup scripts to set the types of locations at which to stop to include custom location types in addition to standard location types:

  - UI4.Widgets.SceneGraphView.SetStopAtLocationTypes('assembly', 'component', 'myCustomLocationType')

  As part of this feature enhancement, the location type icons in the context menu have been modified to scale with the application font size preference.

  Furthermore, the context menu now shows all types of locations at which expanding and collapsing the scene graph stops by default, including locations of the following types, which were previously in effect, but were not shown in the context menu:

  - camera
  - light
  - lookfile

  If you would like expanding and collapsing not to stop at those types of locations, you can use the above API function to provide a set of location types that does not include them.

- TP 312851 - An icon for scene graph locations of type "instance array" has been added (Triple-I).

## Rendering

- TP 81898 / BZ 39827 - The "renderStarted" Katana event type has been extended to include information about the name and type of the render method that was chosen, and the name of the renderer as stored in the renderSettings.renderer attribute at /root in the scene graph that is produced by the node from which the render was started.

  Custom event handlers that are registered for the "renderStarted" event type must be modified to accept the following keyword arguments in addition to the already existing node argument:

  - renderer: The name of the renderer that is used for rendering, as obtained from the renderSettings.renderer attribute at /root.
  - renderMethodType: The type of render that was started, e.g. 'previewRender'.
  - renderMethodName: The name of the render method that was chosen, e.g. 'previewRenderLowRes'.

- TP 82143 / BZ 39951 - Normally, logs in the Render Log tab are automatically scrolled to their end whenever new text is appended to the respective log, and whenever switching between catalog items. This could make it hard to compare the render logs between catalog items.

  Now, when scrolling a log in the Render Log tab up, automatic vertical scrolling is turned off, and a Scroll Lock tool button is shown at the top right of the tab's nested tab widget as active to indicate this. When switching to a different catalog item, the scroll position of the previously viewed render log is stored in a cache, and is restored when viewing the same render log again later. This allows users to more easily compare the render logs of two different catalog items.

- TP 89616 / BZ 42804 - Messages from renderer plug-ins are now logged to the RenderLog logger in batch mode. Previously they used the MainBatch logger.

- TP 107885 / BZ 48022 - The color of the progress bar of catalog items for Live Renders has been changed from blue to green, to allow users to more easily differentiate Live Renders from Preview Renders and Disk Renders. The blue color used for Preview Renders and Disk Renders has been slightly altered to better complement the green color of Live Renders.

  As part of this feature enhancement, the type of render method used for a render is now stored as a property on catalog items. The getRenderMethodType() and setRenderMethodType() functions have been added to the CatalogItem class, to allow retrieving and storing the value of the new property. The render method type is also stored for persistent catalog items as part of a Katana project, so it can be retrieved after opening the same project later.

- TP 247619 - Katana can now be configured to send complete live render updates for newly-created locations to the renderer plug-in. This behaviour is enabled by setting the liveRenderSettings.sendFullUpdateForNewLocations integer attribute to 1; renderer plug-ins that support full updates may register a terminal Op to set this attribute.

- TP 264194 - An optional parameter named includeBypassed has been added to the FarmAPI.GetSortedDependencies() function:

  - FarmAPI.GetSortedDependencies(nodeOrNodes=None, includeBypassed=False):
    - Returns a list of the render passes and their dependencies based on a list of input nodes.
    - nodeOrNodes: The input node or nodes which define the search scope for available render passes. If a node list is not supplied then a default list is used based on the current node scope.
    - includeBypassed: An optional flag that controls whether to include nodes that are bypassed.

- TP 282669 - The following OpenEXR compression types have been added as options to choose from in RenderOutputDefine nodes:

  - B44 -- lossy 4-by-4 pixel block compression, fixed compression rate.
  - B44A -- lossy 4-by-4 pixel block compression, flat fields are compressed more.
  - DWAA -- lossy DCT based compression, in blocks of 32 scanlines. More efficient for partial buffer access.
  - DWAB -- lossy DCT based compression, in blocks of 256 scanlines. More efficient space-wise and faster to decode full frames than DWAA compression.

## Other Feature Enhancements

- TP 281615 - Support has been added for versioning up LiveGroups via an Asset Management System.

- TP 305871 - OpScript nodes now support syntax highlighting of Lua scripts.

- Pressing Tab or Shift+Tab while editing an OpScript node's script.lua parameter indents or dedents text respectively.

- The C++ FnPluginManager::PluginManager::getSearchPaths() function that lists the set of paths in which Katana searches for plug-ins has been exposed to Python in the form of PluginSystemAPI.PluginCache.GetSearchPath(). Note that for historical reasons, the PluginCache Python module has long used 'Path' (singular) to refer to a list of paths.

- TP 330476 - Creators of PackageSuperToolAPI-based SuperTools and Packages can customise how their packages are presented in the Add menu of the SuperTool's Parameters tab UI.

  - If a package provides an ADD_MENU_GROUP_NAME class variable, this will be used to group the packages into a sub-menu named "Add %s"
  - If a SuperTool implements the getDefaultAddMenuGroupName() method on its Editor module, then the result of this call will be used to name the sub-menu for any ungrouped packages.

- TP 332593 - The ScenegraphManager.getSelectedLocations() method now returns a list of selected locations sorted by selection order.

- TP 337170 - A new environment variable KATANA_ARCHIVE_AND_COMPRESS_LIVEGROUPS has been defined to allow users to archive and compress LiveGroup files on saving (by default, these files are published as plain text).

  NodegraphAPI.WriteKatanaFile(..., compress=True, archive=True, ...) no longer evaluates the KATANA_NEVER_ARCHIVE_SCENE_FILE and KATANA_NEVER_COMPRESS_SCENE_FILE environment variables internally. It will now honour the arguments passed for the compress and archive parameters, which was previously not the case.

- TP 339216 - The AlembicIn Op now exports a curve's basis as the integer attribute geometry.basis. Values correspond to the Alembic library's BasisType enumeration.

- A hasLocationEvents() method has been added to the FnGeolib.GeolibRuntime.Client class. This method determines whether the Geolib3 Client holds pending location events, which represent the results of cooking scene graph locations, without committing to processing those events (as getLocationEvents() does).

# Documentation Improvements

## Online Help

- The Katana Online Help now includes documentation of the Hydra Viewer.

- The Katana Online Help has been updated such that examples of using renderers discuss using the 3Delight plug-in, rather than the RenderMan 17 and Arnold 4.2 plug-ins that were removed in Katana 2.5.

- The Katana Online Help has been re-organised and given a new theme.

## Developer Guide

- Documentation of Katana's attribute conventions has been added to the Katana Developer Guide. This will replace the Standard Attributes topic in the Katana Online Help.

- TP 307509 - The Katana Developer Guide has been updated with a section on External Software, which provides a list of third-party libraries and tools used by Katana, including those libraries that are part of the VFX Reference Platform CY2017. In general, there are no restrictions on the toolchain or library versions Katana plug-ins may use, however in some important cases (e.g. Python, PyQt, Qt) it is impractical for customer plug-ins to use a version other than what is shipped with Katana, and the documentation now calls out these cases.

- The Default Attribute Producer (DAP) section in the Katana Developer Guide has been expanded to include background information on DAPs, how to invoke them and attribute conventions to be used writing DAPs that integrate with the Katana UI.

- The Widgets and Hints section in the Katana Developer Guide now describes the Python environment available within script button scripts.

- TP 174459 - The Katana Developer Guide's documentation for FnDefaultAttributeProducerPlugin.h gave the wrong signature for the example cook() method.

- TP 310720 - The Katana Developer Guide no longer documents private C++ constructs.

- TP 346540 - Documentation of variables that are available in the context of Python parameter expressions was incorrect: the katanaVersion variable was described as if it were katanaRelease, and the katanaRelease variable was not documented.

## Doxygen

- TP 245236 - In response to customer feedback, Katana once again ships with Doxygen-generated API documentation in addition to the Sphinx-based Katana Developer Guide. The Doxygen-style documentation can be found in the docs/dev_guide/doxygen/ folder within the Katana installation directory.

  Foundry is committed to improving the Katana Developer Guide. We're providing the Doxygen-style documentation as a stop-gap measure for customers who prefer its concise presentation, for example of class members in table form at the top of pages.

# Bug Fixes

## Stability and Thread-safety

- TP 198362 - GeolibCookInterface::execOp() now supports passing private, user-defined data (a.k.a. "private data") to the executed Op. This also resolves an issue where the caller's private data would be inherited by the callee. In the revised behavior, if the caller of execOp() does not specify any private data then getPrivateData() will return NULL in the callee. Ops that are built against the 2.5 or 2.6 SDK retain the ability to leak private data into an Op executed by execOp(). However, we recommend re-building against the 3.0 SDK and using the privateData parameter of execOp() instead. There have been no change to OpScript, which does not support private data.

- TP 199161 - Katana crashed when launched with a --script command-line option but no script argument.

- TP 310702 - Katana crashed when the + (plus) and - (minus) numpad keys were used in the Scene Graph tab.

- TP 331515 - Katana crashed when an ill-formed regular expression was used in the pattern parameter of a Rename node.

- TP 221551 - Katana could crash when switching the active asset or file-sequence plug-in in a UI session. The AssetAPI.ReleaseManager() Python function is now a no-op, and should not be used.

- TP 325791 - Katana could crash when flushing caches repeatedly while proxies were being displayed in a viewer.

- TP 285039 - Katana could crash when concurrently evaluating OpScripts that used Imath.

- TP 304082 - Katana could crash if an OpScript Lua script returned a value.

- TP 313773 - The FnRender API's IdSenderInterface is now thread-safe. Additionally, the system call and network overhead involved in sending the ID Pass to Katana has been reduced.

- TP 221569 - The LookFileResolve Op, as well as the FnLookFile::getPassNamesForLookFileAsset() and FnLookFIle::getSafePath() methods, were not thread-safe.

- TP 330564 - In rare cases, Geolib Ops marked as ThreadModeGlobalUnsafe could nevertheless be invoked concurrently.

- TP 266401 - Any program or script that spawned a Katana process and attempted to wait for Katana's standard output or standard error handles to close could deadlock if the Katana project made use of AttributeScript or Python-based asset plug-ins.

## User Interface

- TP 54517 / BZ 27028 - Checkmarks of checked, but disabled menu items did not appear correctly.

- TP 315925 - An additional small line was shown at the top of the Select the filmlook visualization to apply to image menu In the Monitor tab.

- TP 320395 - Partially checked checkboxes and view items did not appear correctly.

- TP 56259 / BZ 28347 - The continuation arrow for hidden menus in menu bars (») was drawn in black, making it very hard to see. It also did not scale with the application/fontSize preference.

- TP 207434 - Check indicators in checkboxes and radio buttons did not scale with the application/fontSize preference.

- TP 314056 - When using large values for the application/fontSize preference, the contents of menus were truncated on the right-hand side.

- TP 325217 - Color thumbnails (/swatches/drop widgets) did not scale well with the application/fontSize preference. Those types of widgets have been given a larger size now, and scale with the value of the font size preference.

- TP 323626 - Tab characters were handled incorrect in the Python tab. Katana's handling of tab characters has been revised as follows:

  1. Pressing the Tab key now inserts spaces up to the next tab-stop.
  2. Pressing the Delete or Backspace keys deletes spaces up to the next tab-stop.
  3. Pasted tab characters are converted to 4 spaces.

- TP 335902 - In certain system configurations, and with certain plug-ins present, OpenGL was not initialized correctly, leading to OpenGL-based tabs not working correctly. In order to address this issue, we revised how OpenGL is initialized for the OpenSceneGraph-based Viewer tab. As a result of our changes to address this issue, the ViewerAPILegacy Python module, which contained the implementation of the old Viewer, can no longer be imported from the "virtual" Katana module.

- TP 335903 - When launching Katana in a configuration with plug-ins that prevent OpenGL from being initialized correctly, an error dialog was shown with a message that wrongly stated that three GL extensions were missing.

- TP 341876 - Links in help popups appeared in blue, which made them difficult to read against the dark background.

- TP 347686 - When right-clicking the top of tab title and dismissing the context menu, Katana entered panel-resizing mode.

## Node Graph and Parameters

- TP 114817 / BZ 49357 - Parameter widgets with an int hint were not fully restricted to an integer value.

  After this fix, the result of any simple mathematical expression entered will be clamped to an integer value.

- TP 129057 / BZ 51742 - After renaming a node to a name that doesn't contain the same number of characters, the Find Parameters popup in the Parameters tab listed parameters of the node with parts of the old node name as a prefix, or with parts of parameter names missing. When clicking such a parameter in the popup, instead of the clicked parameter being highlighted, nothing happened.

- TP 168240 - When opening a Katana project from the command line by passing its filename as a command-line argument, the pan position of nodes in the Node Graph tab was not restored correctly.

- TP 280693 - When changing the nodeType parameter on a shading node, port connections became corrupt if the first output port appears in a different position amongst preserved output ports in the new shader.

- TP 304333 - Under certain circumstances, widget hint dictionaries were shared between multiple instances of parameter policies, meaning hint changes in one of the policies erroneously affected others.

- TP 304519 - When calling the _getIncomingSceneOpAndLocation() function on a RendererProceduralArgs instance representing a RendererProceduralArgs node whose action parameter is set to define overrides or remove overrides, an exception was raised due to an unbound local variable.

- TP 309961 - When attempting to pass a boolean value as the fourth argument to the Nodes2DAPI.GetFileOutFilename() function, an exception was raised.

- TP 313685 - Text of menu categories for the Node Graph tab in the Edit Menu Categories dialog could not be clicked to toggle their state.

- TP 324056 - When using the Collapse Selected Nodes to Group command in Node Graph tab (keyboard shortcut: G) to group selected nodes by parenting them to a new Group node, the created Group node was not created in the same position, but rather slightly shifted down by 6 units. This resulted in Group nodes gradually moving down when using the command repeatedly without changing the selection of nodes.

- TP 326381 - The Reset to Defaults button for the image.channelMap group parameter of ImageRead nodes had no effect.

- TP 330272 - The forceArray hint that was available for string parameters in GenericAssign XML documents has been modified to support various forms of true values, and can now also be used for number parameters. Documentation for forceArray has been added to the Katana Developer Guide.

- TP 331907 - The progress dialog for copying nodes in the Node Graph tab was shown even for operations that took very little time.

- TP 332133 - The Auto Calc menu command in the Action menu of the timing parameter of ImageRead nodes had no effect. As part of fixing this, the text of the command has been changed to Auto Calculate In/Out.

## Scene Graph and Attributes

- TP 231922 - When choosing the Select Assigned Material or Select Instance Source commands from the context menu of a location in the Scene Graph tab, exceptions were raised.

- TP 252227 - When expanding the contents of items in a tree of shading nodes that is shown for the material.nodes attribute of a material location that defines a Network Material, the tree widget's scrollbar did not always appear reliably.

- TP 277925 - A context menu with custom menu items provided for SceneGraphView widgets via setContextMenuEventCallback(callback)​ did not open when right-clicking items.

- TP 303909 - When the Scene Graph tab showed a location with an empty type, exceptions were printed to console.

- TP 307854 - Using Ctrl+Left mouse button to deselect locations in the Scene Graph tab behaved unpredictably.

## Rendering

- TP 226255 - Rendering with dependencies logged a depreciation warning to the console.

  GetSortedDependencyList() is now deprecated on the FarmAPI and FarmManager. Developers should use GetSortedDependencies() instead.

- TP 248541 - Deleting an attribute during a Live Render did not send a Live Render update to the renderer plug-in.

- TP 263827 - Deleting and re-creating an ancestor of a monitored scene graph location during a Live Render did not send a Live Render update to the renderer plug-in.

- TP 325810 - When executing a disk render with file format set to tif, an error message was printed in the render log and the image was not displayed in the Monitor tab.

- TP 332318 - The PyUtilModule.RenderManager.RenderCore.GetRendererAndSettings() function, which is meant to initialize settings of a given RenderingSettings object with values of properties of a render method obtained from the RenderingAPI, incorrectly initialized boolean settings of the given RenderingSettings object as integer values 1 or 0 instead of boolean values True or False.

## Other Bug Fixes

- TP 49568 / BZ 23445 - The UV Viewer tab did not update when changing scene graph selection, or when the selected location's attributes changed.

- TP 59762 / BZ 31154 - Project files were saved with an octal umask of 220. Katana no longer sets a umask when saving such files.

- TP 87441 / BZ 42223 - Katana wrote debug information to standard output whenever a new Geolib3 runtime was instantiated.

- TP 120846 / BZ 50470 - The Viewer tab could be initialized with the incorrect Viewer Visibility working set state when shown for the first time, or when being shown after being hidden.

- TP 218267 - MaterialResolve nodes incorrectly resolved filenames containing frame padding (e.g. "file.####.ext") to frame 1, rather than to the current Katana frame.

- TP 231675 - The original behavior of the console_print() function in the context of shelf item scripts has been restored:

  - console_print(message, raiseTab=False):
    - Prints the given message to the result area of the largest available Python tab.
    - If raiseTab is passed as True, the tab will be raised to the front in its pane.
    - If no Python tab exists, prints the message to the shell.

  In addition, a new console_clear() function has been added:

  - console_clear(raiseTab=False):
    - Clears the result area of the largest available Python tab.
    - If raiseTab is passed as True, the tab will be raised to the front in its pane.

  The two functions can be used in combination in shelf item scripts in order to clear and fill the result area of the largest available Python tab in subsequent runs, as a way to quickly debug scripts without having to switch between Katana and a terminal from which Katana was launched.

  For backwards compatibility of shelf item scripts with older releases of Katana, which do not provide the console_clear() function yet, consider wrapping calls of console_clear() in try statements:

      try:
          console_clear(True)
      except:
          pass

- TP 235179 - The following code raised an exception due to an invalid entry in __all__:

      from RenderingAPI.RenderPlugins import *

- TP 323635 - The following code raised an exception due to an invalid entry in __all__:

      from PyUtilModule.FarmAPI import *

- TP 328832 - The following code raised an exception due to an invalid entry in __all__:

      from UI4.Tabs.History import *

- TP 281416 - It was not possible to create attributes via DataBuilder<T>::update()

- TP 284064 - Geolib Runtime Clients in 'all open' mode did not add locations to their open set on calling setLocationsOpen(). The open set is now fully maintained while in 'all open' mode.

- TP 284084 - Locations explicitly opened using setLocationsOpenRecursive(), but whose opening is cancelled prior to being cooked, still reported as being open when calling isLocationOpen().

- TP 327999 - Runtime Cook Interface functions with an opType parameter would wrongly assume that the string was a NUL-terminated C string. If this assumption was violated, Katana could crash.

- TP 323453 - The Instancing example project's Part C did not function with multi-threaded scene translation, and has been removed.

- TP 325075 - When calling the execColorPicker() function from the ColorFormWidget class for a KatanaColorFormWidget instance, an exception was raised.

- TP 326532 - References to an obsolete KATANA_USE_INTERNAL_ZLIB environment variable have been removed from the Katana launcher script on Linux.

- TP 332478 - An exception was raised when registering a keyboard shortcut via the KeyboardShortcutManager which was already in use.

- TP 336043 - Not-equal-to operators (!=) of FnAttribute::StringAttribute were not marked as const.

- TP 346534 - When attempting to build plug-ins that depend on the IlmImf or IlmThread libraries using Katana's CMake utilities in the plugins/Src/ directory, the build failed due to linker errors due to undefined IlmImf references due to typos in the plugins/Src/cmake/FindOpenEXR.cmake file.

- TP 347193 - When attempting to initialize an Op tree from an exported Geolib3 Op tree file that doesn't exist, an erroneous error message was logged that didn't specify the actual error of the file not being found.

# Changed, Deprecated and Removed Features

- TP 107744 / BZ 47997 - The color/useSingleComponentRGB preference, which was not used in commercial Katana, has been deprecated.

- The DiskRenderOutputProcess::setRenderAction() method's renderAction parameter's type has changed from std::auto_ptr<RenderAction> to FnPlatform::internal::UniquePtr (a.k.a. std::unique_ptr). As std::unique_ptr is not copyable, FnPlatform::internal::UniquePtr::move (a.k.a. std::unique_ptr::move) needs to be invoked explicitly in order to move the internal pointer from one container to another.

- API headers and sources that were deprecated in Katana 2.5 have been removed. These headers are:

  - FnGeolib: util/Mutex.h, util/Platform.h, util/PowerNap.h, util/Semaphore.h, util/ThreadException.h, util/Timer.h

  - FnRender: plugin/SocketConnection.h, plugin/CommandLineTools.h

- The C++ class FnLogging::FnLogQueue has been deprecated and will be removed in a future release. This class has never been functional, and logged warnings if you attempted to instantiated it.

- The classic Gaffer node type, which was superseded by GafferThree in Katana 2.0v1, is now hidden from node creation menus in the Node Graph tab.

- Usage of Katana's FnAttribute library from external applications (via the FnAttribute::Bootstrap() function) now consistently requires a katana_r license.

- The following little-used 2D nodes have been hidden from menus in the Node Graph tab: ImageAddMix, ImageAtop, ImageAverage, ImageBlack, ImageDifference, ImageDistort, ImageDivide, ImageExclusion, ImageFrom, ImageGeometric, ImageHypot, ImageMatte, ImageMatteMix, ImageMax, ImageMin, ImageMinus, ImageMix, ImageMultiply, ImageOver, ImagePlus, ImageScreen, ImageUnder, ImageWhite. These node types can still be created through scripting. Nodes in existing projects continue to function as before.

- The AttributeScript node type has been deprecated, and hidden from node creation menus of Node Graph tabs. AttributeScript nodes in existing Katana projects still work, and AttributeScript nodes can still be created via NodegraphAPI scripting, but for new projects, we advise using OpScript nodes and Lua instead. Support for AttributeScript nodes will be removed in a future release.

- Python-based AssetAPI plug-ins have been deprecated, and support for them will be removed in a future release. Moving forward, for performance and stability reasons, AssetAPI plug-ins should be written in C++.

# Third-party Software Changes

The table below summarizes changes to versions of third-party software shipped with Katana.

| Version in Katana 2.6 | Version in Katana 3.0
--- | --- | ---
3Delight | Not shipped | 13.3.14
Alembic | 1.5.3 | 1.6.1
LuaJIT | Not shipped | 2.1.0
Numpy | 1.5.1 (Linux only) | Not shipped
Python | 2.7.3 | 2.7.13
RLM | 9.3 | 12.2
TBB | 4.4.6 | 2017 Update 8
USD | Not shipped | 0.8.0
PyQt | 4.10.4 | 4.11.4
ZeroMQ | 3.2.5 | 4.2.1
PyZeroMQ | 13.0.2 | 16.0.2
VS CRT | 2010 (Windows only) | Not shipped

# Compiler Changes

Katana 3.0 is compiled with GCC 4.8 on Linux, and Visual Studio 2015 on Windows.

Katana 2.5 and Katana 2.6 were built with GCC 4.1 on Linux, and Visual Studio 2010 on Windows.

The change in compilers should not affect most customers. For compatibility reasons, Katana has long separated its APIs into a set of C++ headers and sources compiled directly into customer plug-in libraries and a stable, compiler-agnostic C-based API that's wrapped by the C++ layer. Plug-in authors writing Geolib Ops, for example, are still free to build their plug-ins with their choice of toolchain.

This compatibility note does not apply for Windows plug-in authors building plug-ins that link against Python or Qt: customers are required to re-build these plug-ins using Visual Studio 2015.

Note: The standard Windows compiler for building Python 2.7 C extensions is Visual Studio 2008, but this compiler must not be used for building Python C extensions for Katana. Customers may find it necessary to override distutils/setuptools' choice of compiler in order to build native Python extensions that are compatible with Katana. See https://docs.python.org/2.7/distutils/apiref.html#module-distutils.msvccompiler for instructions.

# API Changes

Katana 3.0's APIs continue to build with older compilers that do not support the C++11 standard. Support for C++98 compilers will be removed in a future release of Katana.

Katana C++ plug-ins built against Katana 2.5 or later should be binary compatible with Katana 3.0 (with the exception of Windows plug-ins that link to Python or Qt, and plug-ins using the in-development Viewer API).

Katana C++ plug-ins built against Katana 2.5 or later should be source compatible with the Katana 3.0 APIs, with a few exceptions:

- Example Plug-ins: Katana's example plug-ins are being progressively migrated to C++11, and are no longer guaranteed to build in older compilers that do not support the C++11 standard.

- Viewer API: The Viewer API was developed in parallel with the Hydra Viewer, and has diverged substantially from the version found in Katana 2.6v4. Information on the Viewer API in Katana 3.0 can be found in the Katana Developer Guide.

- FnAttribute: Changes discussed in the Performance Improvements > FnAttribute section above.

- Display Driver API: Changes discussed in the Performance Improvements > Rendering section above.

- GeolibCookInterface: Changes to execOp(), discussed in the Bug Fixes > Stability and Thread-safety section above.

- DiskRenderOutputProcess: Changes to setRenderAction(), discussed in the Changed, Deprecated and Removed Features section above.

- OpScript: Removal of the legacy API, discussed in the Changed, Deprecated and Removed Features section above.

# Common Plug-ins Compatibility

## USD

USD binaries compiled against Katana 2.6 are compatible with Katana 3.0.

The USD source code can be compiled against Katana 3.0 as of USD version 0.8.2.

Support for USD/Katana plug-ins on Windows remains unavailable.

## RenderMan

RenderMan for Katana binaries compiled against Katana 2.6 are compatible with Katana 3.0.

## Arnold

Arnold for Katana binaries compiled against Katana 2.6 are compatible with Katana 3.0.

# Known Issues

## Hydra Viewer

- TP 344940 - The Hydra Viewer does not update when implicit resolvers are toggled.

- TP 342503 - Changes to the viewerHydra/antiAliasing preference do not effect Viewer (Hydra) tabs that are already open.

- TP 340524 - In certain system configurations, and with certain plug-ins present, OpenGL fails to initialize and Katana presents an "Error initializing OpenGL" error dialog on startup.

- TP 316771 - The Hydra Viewer does not observe light linking.

- TP 297401 - The Hydra Viewer does not observe light muting/soloing.

## Live Groups

- TP 84020 / BZ 40598 - Reverting a LiveGroup node does not revert its user parameters.

- TP 84019 / BZ 40599 - Parameters that are added to LiveGroup nodes are wrongly discarded when performing a reload from source, leading to loss of data.

- 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.

## Materials

- TP 269449 - Choosing Edit Shader Parameters from the main wrench menu of Material nodes does not show wrench buttons next to shader parameters. This can be worked around by toggling the edit flag on the 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 workflows of V-Ray for Maya.

## Node Graph

- 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 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.

## Parameter Expressions

- TP 188533 - Expressions linked to non-local parameters on not previously edited Material nodes can't be evaluated.

- TP 105434 / BZ 47520 - Reference Expressions may not refer to dynamic parameters such as shader parameters.

- 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.

## Rendering

- TP 344118 - (Windows only) When installing Katana and opting to install the bundled version of 3Delight, the installation of 3Delight is made by modifying system-wide environment variables such as KATANA_RESOURCES. Thereafter, launching any version of Katana will pick up this installation of 3Delight, which may be incompatible with the version of Katana being launched.

  NOTE: This does not affect Linux, where a bundled 3Delight installation is tied to its corresponding Katana installation.

- TP 208802 - Closing the Histogram tab after use leaves the Monitor tab unable to display rendered images.

- TP 176598 - Use of nodes that modify Graph State Variables in Interactive Render Filters is not currently supported.

- 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 94052 / BZ 44199 - The Repeat Previous Render menu command only works on renders started from a 3D node's context menu.

- 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.

- TP 65242 / BZ 34870 - Katana doesn't support render output directory creation for shadow, merge and script output types.

- 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.

## Widgets

- 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 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.

## Miscellaneous

- TP 337653 - Katana logs deprecation warnings when loading the 'PyMockAsset', 'PyMultiMockAsset' and 'PyMockFileSeq' shipping example Asset API plug-ins.

- 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 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 unavailable as of Katana 2.0v1.

- 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 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 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.