← Back to branch summary

~popey/+junk/usd

« back to all changes in this revision

Viewing changes to USD/pxr/usd/lib/usd/doxygen/datatypes.dox

  • Committer: Alan Pope
  • Date: 2016-09-29 12:05:28 UTC
  • Revision ID: alan@popey.com-20160929120528-32j3uk1x0dgaorip
Initial attempt to snap

Show diffs side-by-side

added added

removed removed

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