The Content Layer
*****************

|sparkles| **New in Katana 8.5**

Introduction
============

The Content Layer is a ``usg.Layer`` that acts as the source of truth for the
:kat:node:`UsdSuperLayer` and its derived node types. The Content Layer can be interacted with and
edited directly via Katana's Python API, or via the Parameter UI of the
:kat:node:`UsdSuperLayer`-derived node types.

When a change occurs in the Content Layer via Python, it is not automatically reflected in the UI
and it is necessary to manually sync the changes to the node's parameters to ensure that the UI
reflects the contents of the Content Layer and that parity between the two is maintained. This is
because when the Content Layer is edited, the mechanism that normally updates the node's parameters
is bypassed. This is in contrast to node types in the Geolib family, where changes to a node's
attributes are automatically synced with the UI and the node's parameters are updated accordingly.

Changes made in the UI of the :kat:node:`UsdSuperLayer`-derived node and its parameters are
automatically synced to the Content Layer, and do not require an additional sync.

If a change is present in the Content Layer, that change is treated as the source of truth
regardless of if a sync occurs. To validate changes, the values of attributes can be viewed via the
:kat:ui:`Attributes` tab, or by calling the value of a specified Attribute, Relationship or Metadata
type via the :kat:ui:`Python` tab and the data type's appropriate API calls.

Overview
^^^^^^^^

This section describes how to sync attributes between the Content Layer and the
:kat:node:`UsdSuperLayer`-derived node type.

To access the Content Layer, it is required to retrieve the StageSubtreeController. The
StageSubtreeController is the counterpart to the Scene Tree present on
:kat:node:`UsdSuperLayer`-derived nodes, and must be declared before the Content Layer can be
accessed and updated.

For more information on the StageSubtreeController, see :doc:`../APIUsage`.

Examples
^^^^^^^^

.. literalinclude:: ../../../PLUGINS/Resources/Examples/Plugins/UsdSuperLayerParameterSync.py
  :caption: :download:`UsdSuperLayerExampleParametersHandlerPlugin.py <../../../PLUGINS/Resources/Examples/Plugins/UsdSuperLayerParameterSync.py>`
  :language: python


API
^^^

.. automethod:: NodesUsdAPI.UsdSuperLayer.UsdLayerSuperTool.syncLayerAndParameters


.. |sparkles| unicode:: U+2728