1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
/*!
\page Usd_Page_Datatypes Basic Datatypes for Scene Description Provided by Sdf
\section Usd_Datatypes Attribute value types
USD supports a variety of data types for attribute values.
These types are encoded in an SdfValueTypeName object that corresponds to an
underlying C++ type and is what a user would receive from a call to
UsdAttribute::GetTypeName. Methods for looking up these objects are provided
by \c SdfSchema and they're enumerated in the
object \c SdfValueTypeNames -- \sa SdfSchema
For example, to create a custom, Matrix4d-valued attribute on prim \em foo:
\code
if (UsdAttribute mat = foo.CreateAttribute(TfToken("myMatrix"), SdfValueTypeNames->Matrix4d)){
mat.Set(GfMatrix4d(1)); // Assign identity matrix
} else {
// error creating the attribute
}
\endcode
In python:
\code{.py}
mat = foo.CreateAttribute("myMatrix", Sdf.ValueTypeNames.Matrix4d)
if mat:
mat.Set(Gf.Matrix4d(1)) # Assign identity matrix
else:
# error creating the attribute
\endcode
\section Usd_Basic_Datatypes Basic data types
This table lists the fundamental data types supported by USD.
| Value type token | C++ type | Description |
|:-----------------|:--------------|:-------------------------------------------------|
| bool | bool | |
| uchar | uint8_t | 8 bit unsigned integer |
| int | int32_t | 32 bit signed integer |
| uint | uint32_t | 32 bit unsigned integer |
| int64 | int64_t | 64 bit signed integer |
| uint64 | uint64_t | 64 bit unsigned integer |
| half | half | 16 bit floating point (imath half) |
| float | float | 32 bit floating point |
| double | double | 64 bit floating point |
| string | std::string | stl string |
| token | TfToken | interned string with fast comparison and hashing |
| asset | SdfAssetPath | represents a resolvable path to another asset |
| matrix2d | GfMatrix2d | 2x2 matrix of doubles |
| matrix3d | GfMatrix3d | 3x3 matrix of doubles |
| matrix4d | GfMatrix4d | 4x4 matrix of doubles |
| quatd | GfQuatd | double-precision quaternion |
| quatf | GfQuatf | single-precision quaternion |
| quath | GfQuath | half-precision quaternion |
| double2 | GfVec2d | vector of 2 doubles |
| float2 | GfVec2f | vector of 2 floats |
| half2 | GfVec2h | vector of 2 half's |
| int2 | GfVec2i | vector of 2 ints |
| double3 | GfVec3d | vector of 3 doubles |
| float3 | GfVec3f | vector of 3 floats |
| half3 | GfVec3h | vector of 3 half's |
| int3 | GfVec3i | vector of 3 ints |
| double4 | GfVec4d | vector of 4 doubles |
| float4 | GfVec4f | vector of 4 floats |
| half4 | GfVec4h | vector of 4 half's |
| int4 | GfVec4i | vector of 4 ints |
\section Usd_Roles Roles
Value types may also be specified by one of a set of special type names.
These names correspond to the basic data types listed above but provide
extra semantics about how the data should be interpreted. For instance,
a value of type "frame4d" is a GfMatrix4d, but represents a coordinate frame.
These type names are grouped by a "role" name, such that all types with the
same role have the same semantics. All of these "semantic types"
are also provided in SdfValueTypeNames
| Value type token | Underlying type | Role name | Role Meaning |
|:------------------|:----------------|:-----------|:----------------------------------------------------|
| point3d | Vec3d | Point | transform as a position |
| point3f | Vec3f | Point | transform as a position |
| point3h | Vec3h | Point | transform as a position |
| normal3d | Vec3d | Normal | transform as a normal |
| normal3f | Vec3f | Normal | transform as a normal |
| normal3h | Vec3h | Normal | transform as a normal |
| vector3d | Vec3d | Vector | transform as a direction |
| vector3f | Vec3f | Vector | transform as a direction |
| vector3h | Vec3h | Vector | transform as a direction |
| color3d | Vec3d | Color | energy-linear RGB |
| color3f | Vec3f | Color | energy-linear RGB |
| color3h | Vec3h | Color | energy-linear RGB |
| color4d | Vec4d | Color | energy-linear RGBA, <b>not</b> pre-alpha multiplied |
| color4f | Vec4f | Color | energy-linear RGBA, <b>not</b> pre-alpha multiplied |
| color4h | Vec4h | Color | energy-linear RGBA, <b>not</b> pre-alpha multiplied |
| frame4d | Matrix4d | Frame | defines a coordinate frame |
The following exist for historical/internal reasons,
but we expect to eliminate them prior to open-sourcing.
| Value type token | Underlying type | Role name |
|:------------------|:----------------|:-----------|
| Transform | Matrix4d | Transform |
| PointIndex | int | PointIndex |
| EdgeIndex | Vec2i | EdgeIndex |
| FaceIndex | int | FaceIndex |
\section Usd_Array_Datatypes Array data types
USD also supports arrays of the above data types. The value type
name for these arrays is simply the name of the underlying value type
and "[]", e.g. "bool[]", "float[]", etc., and are also provided by
SdfValueTypeNames with a "Array" suffix on the basic datatype
(e.g. SdfValueTypeNames->FloatArray provides "float[]").
The corresponding C++ type is VtArray, e.g. VtArray<bool>, VtArray<float>, etc.
\section Usd_Dictionary_Type Dictionary-valued Metadata
Metadata in USD (See \ref Usd_OM_Metadata) can take on several other datatypes.
Most of these are highly-specialized, pertaining to composition,
like SdfListOp<SdfReference>, but we also provide one very versatile
datatype <b>dictionary</b> <em>that can only be assumed by metadata</em>,
such as \ref UsdObject::GetCustomData() "customData". A dictionary's entries
are keyed by string, and can take on any other scene description value type,
\em including dictionary, allowing for nested dictionaries.
Dictionaries have special value-resolution semantics, in that each field
resolves independently of all others, allowing dictionaries to be sparsely
described and overridden in many layers. This behavior, which we have
found highly desirable, also makes dictionaries more expensive to fully
compose than all other value types (except those that
are \ref Usd_OM_ListOps "list-edited"). It is for this reason that we
disallow dictionary as a value type for attributes: it would eliminate
the extremely important performance characteristic of attribute
value resolution that "strongest opinion wins".
You can use the builtin customData for your truly ad-hoc user-data needs,
but you can also add new dictionary-valued metadata by defining it in a
module plugInfo.json file -
see \ref Usd_Extending_Metadata for details on how to do so.
*/
|