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.
1{
2 "omni.tutorials.TupleData" : {
3 "version": 1,
4 "categories": "tutorials",
5 "scheduling": ["threadsafe"],
6 "description": [
7 "This is a tutorial node. It creates both an input and output attribute of some of the supported ",
8 "tuple types. The values are modified in a simple way so that the compute can be tested."
9 ],
10 "metadata":
11 {
12 "uiName": "Tutorial Node: Tuple Attributes"
13 },
14 "tags": ["tuple", "tutorial", "internal"],
15 "inputs": {
16 "a_double2": {
17 "type": "double[2]",
18 "description": "This is an attribute with two double values",
19 "default": [1.1, 2.2]
20 },
21 "a_float2": {
22 "type": "float[2]",
23 "description": "This is an attribute with two float values",
24 "default": [4.4, 5.5]
25 },
26 "a_half2": {
27 "type": "half[2]",
28 "description": "This is an attribute with two 16-bit float values",
29 "default": [7.0, 8.0]
30 },
31 "a_int2": {
32 "type": "int[2]",
33 "description": "This is an attribute with two 32-bit integer values",
34 "default": [10, 11]
35 },
36 "a_float3": {
37 "type": "float[3]",
38 "description": "This is an attribute with three float values",
39 "default": [6.6, 7.7, 8.8]
40 },
41 "a_double3": {
42 "type": "double[3]",
43 "description": "This is an attribute with three double values",
44 "default": [1.1, 2.2, 3.3]
45 }
46 },
47 "outputs": {
48 "a_double2": {
49 "type": "double[2]",
50 "description": "This is a computed attribute with two double values"
51 },
52 "a_float2": {
53 "type": "float[2]",
54 "description": "This is a computed attribute with two float values"
55 },
56 "a_half2": {
57 "type": "half[2]",
58 "description": "This is a computed attribute with two 16-bit float values"
59 },
60 "a_int2": {
61 "type": "int[2]",
62 "description": "This is a computed attribute with two 32-bit integer values"
63 },
64 "a_float3": {
65 "type": "float[3]",
66 "description": "This is a computed attribute with three float values"
67 },
68 "a_double3": {
69 "type": "double[3]",
70 "description": "This is a computed attribute with three double values"
71 }
72 },
73 "tests": [
74 {
75 "description": "Verification that proper outputs are computed when inputs are all defaults.",
76 "outputs:a_double2": [2.1, 3.2],
77 "outputs:a_float2": [5.4, 6.5],
78 "outputs:a_half2": [8.0, 9.0],
79 "outputs:a_int2": [11, 12],
80 "outputs:a_float3": [7.6, 8.7, 9.8],
81 "outputs:a_double3": [2.1, 3.2, 4.3]
82 },
83 {
84 "description": "Check computation of all outputs using non-default input values",
85 "inputs:a_double2": [2.1, 3.2],
86 "outputs:a_double2": [3.1, 4.2],
87 "inputs:a_float2": [5.1, 6.2],
88 "outputs:a_float2": [6.1, 7.2],
89 "inputs:a_half2": [8.0, 9.0],
90 "outputs:a_half2": [9.0, 10.0],
91 "inputs:a_int2": [11, 12],
92 "outputs:a_int2": [12, 13],
93 "inputs:a_float3": [7.1, 8.2, 9.3],
94 "outputs:a_float3": [8.1, 9.2, 10.3],
95 "inputs:a_double3": [10.1, 11.2, 12.3],
96 "outputs:a_double3": [11.1, 12.2, 13.3]
97 }
98 ]
99 }
100}
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 behavior
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.
1// SPDX-FileCopyrightText: Copyright (c) 2020-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
3//
4// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
5// property and proprietary rights in and to this material, related
6// documentation and any modifications thereto. Any use, reproduction,
7// disclosure or distribution of this material and related documentation
8// without an express license agreement from NVIDIA CORPORATION or
9// its affiliates is strictly prohibited.
10#include <OgnTutorialTupleDataDatabase.h>
11#include <algorithm>
12#include <iostream>
13
14// This class exercises access to the DataModel through the generated database class for supported data types
15// with element counts greater than 1.
16
17class OgnTutorialTupleData
18{
19public:
20 static bool compute(OgnTutorialTupleDataDatabase& db)
21 {
22 // For each piece of data apply a transforming operation so that compute does something testable.
23 // The transformation adds 1 to the input to compute the matching output. Notice how the recognized
24 // USD types can make use of the built-in manipulation functions while the generic types have to
25 // manually apply the algorithm.
26 db.outputs.a_double2() = db.inputs.a_double2() + GfVec2d(1.0, 1.0);
27 db.outputs.a_double3() = db.inputs.a_double3() + GfVec3d(1.0, 1.0, 1.0);
28 db.outputs.a_float2() = db.inputs.a_float2() + GfVec2f(1.0f, 1.0f);
29 db.outputs.a_half2() = db.inputs.a_half2() + GfVec2h(1.0, 1.0);
30 db.outputs.a_int2() = db.inputs.a_int2() + GfVec2i(1, 1);
31
32 // If you have your own data types which are memory-layout-compatible with the defaults provided
33 // you can use a simple cast operation to force a specific data type. Be careful not to cast away
34 // the "const" on inputs or your data could get out of sync.
35 const carb::Float3& inFloat3 = reinterpret_cast<const carb::Float3&>(db.inputs.a_float3());
36 carb::Float3& outFloat3 = reinterpret_cast<carb::Float3&>(db.outputs.a_float3());
37 outFloat3.x = inFloat3.x + 1.0f;
38 outFloat3.y = inFloat3.y + 1.0f;
39 outFloat3.z = inFloat3.z + 1.0f;
40
41 return true;
42 }
43};
44
45REGISTER_OGN_NODE()
Note how by default some of the attribute value types are USD types and some are generic ogn::tuple types. See omni.graph.docs.ogn_attribute_types for the full set of type definitions.
Tuple Attribute Access
The attribute access is as described in Tutorial 2 - Simple Data Node 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.