.. _ogn_tutorial_tupleData:

Tutorial 4 - Tuple Data Node
============================

Tuple data, also referred to as fixed array data, consists of multiple elements of a simple type.
For example *float[3]* or *double[4]*. This node creates one input attribute and one output attribute
of each of the simple data types with an element count greater than 1.

OgnTutorialTupleData.ogn
------------------------
The *ogn* file shows the implementation of a node named
"omni.tutorials.TupleData", which has one input and one matching output attribute of each simple type with element counts
greater than one.

.. literalinclude:: ../../../../../source/extensions/omni.graph.tutorials/tutorials/tutorial4/OgnTutorialTupleData.ogn
    :linenos:
    :language: json
    :emphasize-lines: 2,12

New Concept - Tags
------------------
Often it is helpful to group nodes with common functionality together in some way in the UI. To help with this you
can specific values for the **tags** keyword. The values can either be a comma-separated string, or a list, that will
be rendered into a comma-separated string when added to the metadata.

New Concept - Namespaced Node Type Name
---------------------------------------
The standard naming convention uses a simple ``CamelCase`` name, with the extension of origin prepended onto the name
to ensure uniqueness. Sometimes you may wish to manage your own namespace, e.g. when you anticipate moving nodes
between extensions so the extension name will not be consistent. All you have to do to override the default behaviour
is to specify a namespace for the node type name (i.e. include a `.` separator in it).

.. warning::

    Once you have overridden the node type name with such an absolute value you are now responsible for ensuring
    uniqueness so be sure you have some scheme that will help you with that. The prefix **omni.** is reserved for
    NVIDIA nodes. Everything else is legal, so long as the entire name itself is legal.

OgnTutorialTupleData.cpp
------------------------
The *cpp* file contains the implementation of the compute method, which
modifies each of the inputs in a simple way to create outputs that have different values.

.. literalinclude:: ../../../../../source/extensions/omni.graph.tutorials/tutorials/tutorial4/OgnTutorialTupleData.cpp
    :linenos:
    :language: c++

Note how by default some of the attribute value types are USD types and some are generic *ogn::tuple* types.
See :ref:`ogn_attribute_types` for the full set of type definitions.

Tuple Attribute Access
----------------------
The attribute access is as described in :ref:`ogn_tutorial_simpleData` except that the exact return types
of the attributes are different in order to support tuple member access. In practice you would use
an *auto* declaration. The types are shown only for illustrative purposes.

The data types for tuples that correspond to existing USD types use the ``pxr::gf`` versions of those types,
so the database accessors in this node will return these types:

+---------------------+----------------+
| Database Function   | Returned Type  |
+=====================+================+
| inputs.a_double2()  | const GfVec2d& |
+---------------------+----------------+
| inputs.a_float2()   | const GfVec2f& |
+---------------------+----------------+
| inputs.a_half2()    | const GfVec2h& |
+---------------------+----------------+
| inputs.a_int2()     | const GfVec2i& |
+---------------------+----------------+
| inputs.a_float3()   | const GfVec3f& |
+---------------------+----------------+
| outputs.a_double2() | GfVec2d&       |
+---------------------+----------------+
| outputs.a_float2()  | GfVec2f&       |
+---------------------+----------------+
| outputs.a_half2()   | GfVec2h&       |
+---------------------+----------------+
| outputs.a_int2()    | GfVec2i&       |
+---------------------+----------------+
| outputs.a_float3()  | GfVec3f&       |
+---------------------+----------------+

Tuple Data Compute Validation
-----------------------------
As with simple data types the existence of the mandatory inputs is confirmed before proceeding to the compute
method.

Tuple Data Node Computation Tests
---------------------------------
In the *"tests"* section of the .ogn file there are some simple tests exercising the basic functionality of the
compute method. In practice it is a good idea to include more thorough tests which exercise different data values,
especially potential edge cases.
