Supporting Local Graph State in Parameter Evaluation
====================================================

|sparkles| **New in Katana 4.5v1**

In order for Local Graph State to be queried in Parameter Expressions, Graph State must be placed on the Local Graph
State stack prior to Parameter evaluation. This must be done while translating nodes to Ops (and may be done in any
context in which Local Graph State is well-defined).

Custom node types built using :ref:`nodetypebuilder`, and using a standard interface, already perform this task. Where a
custom node type directly extends from :kat:node:`Nodes3DAPI.Node3D` (or its base classes), and outside of the standard
node interface, it is the node type author's responsibility to stack the Local Graph State where necessary.

For example, if ``Node3D_geolib3.NodeGeolib3._getOp(self, port, graphState, visitedState, transaction)`` or
``NodegraphAPI.PythonNode.getInputPortAndGraphState(self, outputPort, graphState)`` are overridden, and parameters are
queried in these overrides, the Local Graph State (the ``graphState`` argument) needs to be *stacked* before parameter
values can be interrogated.

See the following functions as examples of functions that depend on the Local Graph State:

* `getVar() <../../../ParameterExpressions/PythonExpressions.html#getVar>`_
* `getFrameTime() <../../../ParameterExpressions/PythonExpressions.html#getFrameTime>`_
* `matchGraphStateVariable() <../../../ParameterExpressions/PythonExpressions.html#matchGraphStateVariable>`_

These functions source the Local Graph State from a global stack, and custom node types are required to maintain this
stack themselves.

The Local Graph State can be pushed to the global stack using the
`NodegraphAPI.StackedLocalGraphState(graphState) <../../WorkingWithProjects.html#NodegraphAPI.StackedLocalGraphState>`_
context manager along with the ``with`` statement in Python.

Example of usage:

.. literalinclude:: CustomVariableSetNode.py
  :caption: :download:`CustomVariableSetNode.py`
  :language: python

If the ``Node3D_geolib3.NodeGeolib3.ParamDependencyTracker`` context manager, defined in the standard interface, is
already employed, ``NodegraphAPI.StackedLocalGraphState`` is not needed.


.. |sparkles| unicode:: U+2728