.. _ogn_omni_graph_instancing:

OmniGraph Instancing
####################

.. tabularcolumns:: |L|R|

.. csv-table::
   :width: 100%

   **Extension**: omni.graph.instancing,**Documentation Generated**: |today|

.. toctree::
   :maxdepth: 1

   CHANGELOG

What Is It?
===========

Instancing provides a mechanism to apply a single graph to multiple `UsdPrim` objects. Applying the 
`OmniGraph` component onto a `UsdPrim` will cause the graph to execute with the variable values stored on the 
`OmniGraph` component. Multiple Prims referencing the same graph will cause the graph to execute once for each Prim. 

The `GraphTarget` node exposes the path of the `UsdPrim` instance to the graph, allowing each execution to uniquely 
read or modify the primitive that initiated the execution. 

For more comprehensive documentation explaining the use of OmniGraph features in detail see
:ref:`ogn_user_guide`


Limitations
===========

At present, each execution of the graph occurs sequentially and nodes in the graph share state across all instances. 
Nodes that use event callbacks, or use internal state may not behave as anticipated when multiple instances exists. 
For example, using the `OnKeyboardInput` action graph node will only trigger the event on the first instance executed. 
Instead, it is recommended to use the ReadKeyboardInput node instead. Another example is the `Counter` node - it will 
increment for each instance executed. 

The following is a noncomprehensive list of nodes that may not be suitable for instanced graphs
* omni.graph.action.OgnCounter
* omni.graph.action.OgnDelay
* omni.graph.action.OgnForEach 
* omni.graph.action.OgnFlipFlop
* omni.graph.action.OgnForEach
* omni.graph.action.OgnGate
* omni.graph.action.OgnMultiGate
* omni.graph.action.OgnOnCustomEvent
* omni.graph.action.OgnOnGamepadInput
* omni.graph.action.OgnOnImpulseEvent
* omni.graph.action.OgnOnKeyboardInput
* omni.graph.action.OgnOnMouseInput
* omni.graph.action.OgnOnObjectChange
* omni.graph.action.OgnOnStageEvent
* omni.graph.action.OgnSendCustomEvent
* omni.graph.action.OgnSequence
* omni.graph.action.OgnSyncGate
