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

# What's New in Katana 8.5

This document describes notable changes introduced in Katana 8.5.

# UsdSuperLayer

- The UsdSuperLayer node is a new base SuperTool node type, which provides direct access to a USD Layer at the Node Graph level. The UsdSuperLayer node is designed to show the incoming stage data and allow for editing or creating Prims upon its authoring layer, which feeds back into the already present USD Native Katana workflows. The purpose of this node is to provide a basis for future specialised and custom tools built around the USD native context and is designed with scalability and flexibility in mind. An example of a tool derived from the UsdSuperLayer is the UsdGaffer node, which focuses on the prims and tools in the UI specifically required within the lighting stages. More information on the UsdGaffer can be found below.

  The UsdSuperLayer node (and all nodes derived from it) can be interacted with and edited directly via Katana’s Python API, giving full flexibility and treating USD as the source of truth for all properties serving as UI elements. Additionally, the UsdSuperLayer node can be used to create context-specific tools, to incorporate custom behaviour tailored to the task at hand.

- Within the UsdSuperLayer node Parameters tab, the target primPath indicates the path the node will create or edit prims on. This path can be changed and if so, any prims created or any of the edits made are transferred to the new path. The primPath also assists in performance by masking composition of the input stage to that primPath. Therefore, it can be important to utilise this to scope the scene to as minimal a section as possible to attain the best performance. By default, the path’s primSpecifier will be set to Define, to allow prims to be created on new paths. A specifier dropdown allows users to set their preferred specified on the path, other options include Override and Class specifiers.
  The “ + ” icon displays a dropdown list of actions which can be performed on the layer, including prims which can be created on the layer; the same dropdown is available in the tree view as a right click context menu. This menu is fully customisable with custom Context Menu Plug-ins written in Python. More documentation on writing custom Context Menu Plug-ins can be found in the documentation under USD PROCESSING ENGINE > UsdSuperLayer > UsdSuperLayer > Plug-ins > Context Menu Plug-ins. In the initial release of this node, the following menus and their functionality will be released:
  - Add <Category> Light
    - Lists the available lights to create. When selected, a new light is created under the currently selected prims within the parameter editors tree view.
    - These lights are discovered by searching the SdrRegistry for anything with “light” as its context. We can then discover any schemas these lights auto apply to via the `apiSchemaAutoApplyTo` metadata, and create the relevant prim based on the data from the SdrRegistry. This allows Katana to remain nimble and up to date based on renderer specific choices and treats USD as the universal source of truth for registered Prim data.
    - API Schemas (such as MeshLightAPI and VolumeLightAPI) are automatically applied to the selected prim upon creation.
    - If the light shader returns a “Category”, a custom menu will be created with all the registered lights matching that category. Having these lights in a separate menu allows for better customization for renderers to organise light creation menus without having to build their own custom context menus.
    - By default, this menu will only appear on the UsdSuperLayer or UsdGaffer node types.
  - Add Lightfilter
    - Lists the available light filters to create. When selected, a new light filter is created as a child of the selected light prim, and the relationship is set automatically. If the parent is unsuitable, the filter will be created at the same level in the hierarchy, and no automatic relationship will be created.
    - Light filters can be inherited from upstream UsdGaffer/UsdSuperLayer nodes.
    - If a light filter is deleted, it will only automatically remove the references from its immediate ancestors. Note a relationship to a deleted filter will still exist on a light outside of the filter’s hierarchy.
  - Add Rig (Xform) | Scope | Material
    - Adds a prim with the type set to Xform, Scope, or Material respectively under the selected prims.
  - Rename Prim
    - Renames the current prim via a dialog menu, also possible by double clicking on the name or pressing the F2 shortcut.
    - The Rename option will only be available for prims that were created locally to the node being edited.
  - Delete
    - Removes the current prim or the overrides. A downstream UsdSuperLayer node cannot fully remove a prim which was created upstream, it may only remove its own opinions onto the stage. For locally created prims, they will be removed completely when deleted.
- The parameter panel is automatically populated based on the currently selected prim in the UsdSuperLayer’s tree view. This currently supports a single selection and will show the first selected item if multiple prims are selected. These parameters, as with the Context Menu Plug-ins are completely customisable via Parameter Handler Plug-ins. More documentation on how to write your own Parameter Handler Plug-ins can be found in the developer guide under USD PROCESSING ENGINE > UsdSuperLayer > UsdSuperLayer > Plug-ins > Parameter Handler Plug-ins. These plug-ins are in charge of creating their own parameters and handling which data to read from the layer/stage to display the parameter values and states to the end user.
  In this version of Katana, we will be shipping with the following plug-ins:
  - Properties Parameters Handler
    - Displayed as properties, this reads all of the API and Typed schemas on the prim and displays all of the properties related to these including locally authored or upstream authored property values utilising the Stage Parameter Policy.
    - This group will also display any locally authored attributes even if they are not part of the current schemas.
  - Metadata Parameters Handler
    - Displayed as metadata, similarly to the Properties Parameter Handler, this group will provide the parameters for editing upstream or local metadata values at the prim level.
  - Shader Parameters Handler
    - Displayed as shader, this group will only appear if we detect a shader:id property. If that is found, we will search the SdrRegistry for the aforementioned shader, and if found present all the properties related to that shader.
- For downstream editing, the showIncomingScene toggle will show prims that have been created upstream, giving complete flexibility on what can be edited in a USD scene. The UsdSuperLayer node follows the same visual designs as seen in the Scene Explorer tab, for displaying over and abstract prims, as well as visibility and active states. On top of this, a column has been introduced to visualise the state of the prims that are seen in the tree view. This includes:
  - Unchanged prims are indicated by a grey U icon
  - Edited prims are indicated by a yellow E icon
  - Locally created prims are indicated by a green N icon
  This gives a top-level representation of the changes made at the node level, making it easier for debugging and visibility.
  There are two methods which can handle the filtering of a specific UsdSuperLayer node `setFilteredConcreteSchemas` and `setFilteredApiSchemas` these methods set a pair of parameters on the node, which if defined will filter the tree views model to only prims which match either of these filters. If the filters are empty, all prims are accepted.

- Additionally, right next to showIncomingScene toggle, a SyncSelection toggle can be found. Similarly to its GafferThree twin, the following three options are available:

  • off: Selections are independent.

  • out: Selections in the node are synced to the Scene Explorer, but selection in the Scene Explorer is not synced to the node.

  • in/out: Selections are synchronized both ways in the node and the Scene Explorer.

- Transformations can be applied by selecting an Xformable prim in the tree view and moving its manipulators in the Viewer.

  Transformations make use of a new “SubEngine” feature for the LayerEngine utilised by the UsdSuperLayer and its derivatives. The SubEngine feature utilises attributes stored on the Prim which are defined by using the new FnSubEngineAPI multi-apply schema. This schema is included with the FnUsdShim, and has C++ utilities to assist in creating attributes and Python bindings via the `usg.FnSubEngineAPI` class. SubEngines allow a procedural on-demand approach. The SubEngine has access to interpret and react to the incoming stage upon each traversal. The Engine system is already extensible, similar to the Geolib Op system, and you can find more information about that, and how to find the existing engines and their arguments in the Developer Guide > Usd Processing Engine > Engines.

  - In order to transform incoming prims, MakeInteractive would need to be set to Yes. To facilitate this, there is an option available in the right-click menu to change this value on multiple selected prims.
  - Locally created Light prims will have MakeInteractive set to Yes by default, allowing interactive transformation upon creation
- A visibility column is available in the tree view. Similar to GafferThree’s “muting”, this sets USD’s visibility property on the respective prim by either using the toggle in the tree view or changing the visibility parameter. Both will update its icon when set, and this can be done whilst selecting multiple prims to modify the visibility of all selected at once. There are four states: incoming, local visible, local invisible and inherited invisible, but toggling it in the tree view will only swap between the following three: incoming, local invisible and local visible. This is to make sure it can be used efficiently.
- The UsdSuperLayer and its derived nodes have the ability to copy and paste prims. This can be done within the same node or across different ones. In order to avoid name clashes, the name of the copied prim will be enumerated if a prim of the same name is already present on the node. When copying an edited prim, only the edits will be copied across.
- Finally, a tab system has been introduced to the parameters of the UsdSuperLayer and its derived nodes. Each tab represents a ParametersHandlerPlugin under the hood, where its label and priority in ranking can be adjusted.

Note: Learn more - UsdSuperLayer Framework, Using UsdSuperLayer, Customizing UsdSuperLayer, UsdSuperLayer.

# UsdGaffer

- UsdGaffer is our first specialized node derived from the UsdSuperLayer. It is specifically designed with lighting in mind and brings the performance, adaptability and customisability of the UsdSuperLayer to Katana’s lighting workflows. While its core look and functionality is reminiscent of the UsdSuperLayer, there are some notable differences and adjustments to cater to the lighter’s needs.
  The primPath parameter defaults to /lights causing new light prims to be created under a /lights Scope prim, e.g. a new USD DistantLight path would be under /lights/distantlight1.
  The tree view in UsdGaffer has two filters applied for the API and Typed schemas such that it only shows prims which utilise any of the schemas below or any schemas which inherit from these:
  - Typed Schemas:
    - UsdLuxBoundableLightBase
    - UsdLuxLightFilter
    - UsdGeomXform
    - UsdLuxNonboundableLightBase
    - UsdLuxPluginLight
    - Scope
  - API schemas:
    - UsdLuxLightAPI
    - UsdLuxVolumeLightAPI
    - UsdMeshLightAPI
  Similarly, the ' +' button and the right-click menu inherit their options directly from the UsdSuperLayer but have a filter applied to show custom options relative to lighters and core functionality such as Delete and Rename. Below are some of these custom options:
  - Add <Category> Light
    - Lists the available lights to create. When clicked, a new light is created under the currently selected prims within the parameter editors tree view.
    - These lights are discovered by searching the SdrRegistry for anything with “light” as its context. We can then discover any schemas these lights auto apply to via the `apiSchemaAutoApplyTo` metadata, and create the relevant prim based on the data from the SdrRegistry. This allows Katana to remain nimble and up to date based on renderer specific choices and treats USD as the universal source of truth for registered Prim data.
    - API Schemas (such as MeshLightAPI and VolumeLightAPI) are automatically applied to the selected prim upon creation.
    - If the light shader returns a “Category”, a custom menu will be created with all the registered lights matching that category. Having these lights in a separate menu allows for better customization for renderers to organise light creation menus without having to build their own custom context menus.
    - By default this menu will only appear on the UsdSuperLayer and UsdGaffer node types.
  - Add Lightfilter
    - Lists the available light filters to create. When selected, a new light filter is created as a child of the selected light prim, and the relationship is set automatically. If the parent is unsuitable, the filter will be created at the same level in the hierarchy, and no automatic relationship will be created.
    - Light filters can be inherited from upstream UsdGaffer/UsdSuperLayer nodes.
    - If a light filter is deleted, it will only automatically remove the references from its immediate ancestors. Note a relationship to a deleted filter will still exist on a light outside of the filter’s hierarchy.
  - Add Rig (Xform)
    - Adds a prim with the type set to Xform under the selected prims. Additionally, pressing R in the tree view will create a Rig.
  - Add Scope
    - Adds a prim with the type set to Scope under the selected prims.

  - Within UsdGaffer’s properties, a linking tab was introduced for the creation and editing of light and shadow linking relationships. The UsdGaffer supports setting these relationships within this tab, as well as showing any incoming light and shadow linking properties that may be set upstream.

    In USD’s defaults, the includeRoot property within the light/shadow linking collections is set to active. Similarly to collections in USD, prims can be added through either relationship or membership expressions. Since light and shadow linking properties are Collections, they can then be found in the Scene Explorer tab through the Activate Collections view tab option, after selecting the light’s Collections working set.

    Note that the membershipExpression mode will be ignored when either includeRoot is enabled or includes/excludes paths are specified.

  Note: Learn more - Using UsdGaffer, Lighting Setups with UsdGaffer, Light Linking and Shadow Linking, Transforming Lights, Customizing UsdGaffer, UsdGaffer.

# UsdMaterial

- The new UsdMaterial node type offers three modes, which are available under the action parameter:
  - create - This creates a single-shader material under the designated prim path set in the materialPrimPath parameter.
  - edit shader - Expects to be targeted to an existing Shader Prim, as defined within the shaderPrimPath parameter. The incomingShaderNode parameter will be populated, as well as the properties defined within the USD SdrRegistry.
  - edit interface - Expects to be targeted to an existing Material Prim, on which its contained shader properties have been promoted to its public interface.
  Please note that this is not a substitute for a future look-development toolset in the USD native space, and is purely designed as a lightweight tool to easily create single-shader materials and edit existing Material setups on an individual prim basis.

  Note: Learn more - Using UsdMaterial, UsdMaterial.

# Hydra 2.0 Rendering

- This release will showcase the first glimpse into rendering through Hydra 2.0, the latest version of Hydra, and will highlight a taster into what an end-to-end Hydra Rendering solution could look like in Katana; from rendering in the viewport to final-frame image.

  For this reason, this workflow can be found behind an environment variable, by setting KATANA_ENABLE_HYDRA2 to 1. Once enabled, you will have access to two new features, the Hydra 2.0 Viewer tab and the Hydra Scene Browser tab.

# Hydra 2.0 Viewer

- The Hydra 2.0 Viewer tab is a new feature that is different from Katana’s existing Viewer tab in that it only renders Hydra 2.0 data in this viewport. In this iteration, the Hydra 2.0 viewport can be used as a quality check to ensure that the rendered image is similar to the Hydra 1 viewport. It’s important to note that in this iteration that USD stages will render in the Hydra 2.0 viewport but not through expansion based loading, while some Geolib attributes will also be rendered in the Hydra 2.0 viewport but it is not in parity with Hydra 1.0 at this time. As we continue to develop in this space, more functionality and user interface workflows will be added in later versions.

  The building blocks for rendering Geolib data in the new Hydra 2.0 Viewer tab were derived from FnHdBridge2.0; an internal library that will not be publicly available. Once a piece of geometry is placed, users can experiment with rendering an image in the viewport by adding USD lights and materials shipped with Katana today. Note, the Hydra 2.0 Viewer tab does not have default lighting but does include default materials and will be overwritten by any assigned materials. To check the rendered images in both viewerports, specifically when rendering with Geolib attributes, the Hydra 1 viewport lighting and default materials toggles must be disabled (Viewer tab > Display > Basic Material & Default Lighting). However this does not apply for USD data, where you will need to place a GafferThree in your scene to see basic materials being rendered.

  Surrounding this, we’ve also implemented a shim layer which will allow customers to write their own SceneIndexFilters. This will require studios to build Katana’s FnUsdShim against your own version of USD so that you can create or port your own custom tools to support rendering through Hydra 2.0. The steps to do this can be found at this location <KATANA_ROOT>/plugins/Src/FnUsdShim/Readme.md. It is highly recommended for users who have their own custom render delegates to start this process at this time; the steps for this will be outlined below.

# Hydra Scene Browser

- Accompanying the Hydra 2.0 Viewer tab, we’re also introducing an experimental feature called the Hydra Scene Browser tab.

  This feature is similar to the scene graph navigation and introspective tools in usdview in that it only displays the unflattened Hydra scene. The major difference and added benefit with the Hydra Scene Browser tab is that it shows Geolib data being fed into Hydra; with the intention that it would be used to help debug your scenes prior to sending it off for final-frame rendering. It is important to note, that in this iteration the Hydra Scene Browser tab will not show USD data being into Hydra, however this will be updated in later iterations.

  Once the Hydra Scene Browser tab is added to your Katana layout, there are 3 window panels. These can be best compared to existing features in Katana and can be described as the following;

  - Left pane: Displays all available Hydra prims within the selected terminal scene index and displays them in a tree view format. This is comparable to the scene trees in the Scene Graph or Scene Explorer whereby as you navigate through each Hydra prim, its data source and property values will appear in the next panel.
  - Middle pane: This panel is similar to the Attributes tab in Katana, in that it will show all Hydra prim data sources associated with the selected Hydra prim. Double-clicking on each data source will expand to the next leaf.
  - Right pane: Once a Hydra prim data source is selected, its source values will display in this panel.

  Additional buttons are also included in this tab to help further debug your Hydra scene. These following are included and can be located above the window panes;

  - Choose Scene Index: Allows selection of which terminal scene index or render index to view the Hydra Scene from. Note, each Hydra Viewer in Katana has its own terminal index and will display together in this menu.
  - Inputs: Allows selection of a particular upstream scene index from the index selection above. This can be compared to changing which node in the Katana node graph has the viewed flag.
  - Show Notice Logger: Records dirtied, added, removed or renamed events and logs these changes in the popup window.
  - Write to file: Writes out the scene in a .txt file. The location of this text file will be noted in your Katana terminal.

# VFX Reference Platform CY2024

- As part of this release, this line will follow the same VFX Reference Platform as Katana 8.0; VFX Reference Platform 2024. Some highlights of the specific versions are included below. For a complete list, please refer to the Developer Guide.

  | VFX Reference Platform 2024 | Katana 8.5
  --- | --- | ---
  GCC | 11.2.1 | 11.2.1
  glibc | 2.28 | 2.28
  Windows Toolset | Visual Studio 2022 | Visual Studio 2022
  Windows SDK | 10.0.20348 | 10.0.22621
  Python | 3.11.x | 3.11.7
  Qt | 6.5.x | 6.5.3 (modified)
  PySide | 6.5.x | 6.5.3
  OpenEXR | 3.2.x | 3.2.1
  OpenSubdiv | 3.6.x | 3.6.0
  Alembic | 1.8.x | 1.8.6
  OpenColorIO | 2.3.x | 2.3.1
  Boost | 1.82 | 1.82.0
  Intel TBB | 2020 Update 3 | 2020 Update 3
  OpenVDB | 11.x | 11.0.0
  NumPy | 1.24.x | 1.24.x

  Outside of the VFX Reference Platform, we have updated to USD 25.08.