.. _ogn_tutorial_roleData:


Tutorial 7 - Role-Based Data Node
=================================

The role-based data node creates one input attribute and one output attribute of each of the role-based type. A
role-based type is defined as data with an underlying simple data type, with an interpretation of that simple
data, called a "role".

Examples of roles are **color**, **quat**, and **timecode**. For consistency the tuple counts for each of the
roles are included in the declaration so that the "shape" of the underlying data is more obvious.

OgnTutorialRoleData.ogn
-----------------------
The *ogn* file shows the implementation of a node named "omni.graph.tutorials.RoleData", which has one
input and one output attribute of each Role type.

.. literalinclude:: ../../../../../source/extensions/omni.graph.tutorials/tutorials/tutorial7/OgnTutorialRoleData.ogn
    :linenos:
    :language: json

OgnTutorialRoleData.cpp
-----------------------
The *cpp* file contains the implementation of the compute method, which modifies
each of the inputs by adding 1.0 to all components to create outputs that have different, testable, values.

.. literalinclude:: ../../../../../source/extensions/omni.graph.tutorials/tutorials/tutorial7/OgnTutorialRoleData.cpp
    :linenos:
    :language: c++

Role-Based Attribute Access
---------------------------
Here is a subset of the generated role-based attributes from the database. It contains color attributes, a matrix
attribute, and a timecode attribute. Notice how the underlying data types of the attributes are provided, again
with the ability to cast to different interface classes with the same memory layout.

+----------------------+-------------------+
| Database Function    | Returned Type     |
+======================+===================+
| inputs.a_color3d()   | const GfVec3d&    |
+----------------------+-------------------+
| inputs.a_color4f()   | const GfVec4f&    |
+----------------------+-------------------+
| inputs.a_frame()     | const GfMatrix4d& |
+----------------------+-------------------+
| inputs.a_timecode()  | const double&     |
+----------------------+-------------------+
| outputs.a_color3d()  | GfVec3d&          |
+----------------------+-------------------+
| outputs.a_color4f()  | GfVec4f&          |
+----------------------+-------------------+
| outputs.a_frame()    | GfMatrix4d&       |
+----------------------+-------------------+
| outputs.a_timecode() | double&           |
+----------------------+-------------------+

The full set of corresponding data types can be found in :ref:`ogn_attribute_roles`.

This role information is available on all attribute interfaces through the ``role()`` method. For example you can
find that the first attribute is a color by making this check:

.. code-block:: c++

    static bool compute(OgnTutorialRoleDataDatabase& db)
    {
        if (db.inputs.a_color3d.role == eColor )
        {
            processValueAsAColor( db.inputs.a_color3d() );
        }
    }
