HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
attributeSpec.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_SDF_ATTRIBUTE_SPEC_H
25 #define PXR_USD_SDF_ATTRIBUTE_SPEC_H
26 
27 /// \file sdf/attributeSpec.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
32 #include "pxr/usd/sdf/path.h"
34 #include "pxr/usd/sdf/types.h"
35 #include "pxr/base/tf/enum.h"
36 
38 
39 /// \class SdfAttributeSpec
40 ///
41 /// A subclass of SdfPropertySpec that holds typed data.
42 ///
43 /// Attributes are typed data containers that can optionally hold any
44 /// and all of the following:
45 /// \li A single default value.
46 /// \li An array of knot values describing how the value varies over time.
47 /// \li A dictionary of posed values, indexed by name.
48 ///
49 /// The values contained in an attribute must all be of the same type. In the
50 /// Python API the \c typeName property holds the attribute type. In the C++
51 /// API, you can get the attribute type using the GetTypeName() method. In
52 /// addition, all values, including all knot values, must be the same shape.
53 /// For information on shapes, see the VtShape class reference in the C++
54 /// documentation.
55 ///
57 {
58  SDF_DECLARE_SPEC(SdfAttributeSpec, SdfPropertySpec);
59 
60 public:
63 
64  ///
65  /// \name Spec construction
66  /// @{
67 
68  /// Constructs a new prim attribute instance.
69  ///
70  /// Creates and returns a new attribute for the given prim.
71  /// The \p owner will own the newly created attribute.
72  SDF_API
73  static SdfAttributeSpecHandle
74  New(const SdfPrimSpecHandle& owner,
75  const std::string& name, const SdfValueTypeName& typeName,
77  bool custom = false);
78 
79  /// @}
80 
81  /// \name Connections
82  /// @{
83 
84  /// Returns a proxy for editing the attribute's connection paths.
85  ///
86  /// The returned proxy, which is an SdfListEditorProxy, modifies the
87  /// SdfListOp that represents this attribute's connections.
88  SDF_API
90 
91  /// Returns \c true if any connection paths are set on this attribute.
92  SDF_API
93  bool HasConnectionPaths() const;
94 
95  /// Clears the connection paths for this attribute.
96  SDF_API
97  void ClearConnectionPaths();
98 
99  /// @}
100  /// \name Attribute value API
101  /// @{
102 
103  /// Returns the allowed tokens metadata for this attribute.
104  /// Consumers may use this metadata to define a set of predefined
105  /// options for this attribute's value. However, this metadata is
106  /// purely advisory. It is up to the consumer to perform any
107  /// validation against this set of tokens, if desired.
108  SDF_API
109  VtTokenArray GetAllowedTokens() const;
110 
111  /// Sets the allowed tokens metadata for this attribute.
112  SDF_API
113  void SetAllowedTokens(const VtTokenArray& allowedTokens);
114 
115  /// Returns true if allowed tokens metadata is set for this attribute.
116  SDF_API
117  bool HasAllowedTokens() const;
118 
119  /// Clears the allowed tokens metadata for this attribute.
120  SDF_API
121  void ClearAllowedTokens();
122 
123  /// Returns the display unit of the attribute.
124  SDF_API
125  TfEnum GetDisplayUnit() const;
126 
127  /// Sets the display unit of the attribute.
128  SDF_API
129  void SetDisplayUnit(const TfEnum& displayUnit);
130 
131  /// Returns true if a display unit is set for this attribute.
132  SDF_API
133  bool HasDisplayUnit() const;
134 
135  /// Clears the display unit of the attribute.
136  SDF_API
137  void ClearDisplayUnit();
138 
139  /// Returns the color-space in which a color or texture valued attribute
140  /// is authored.
141  SDF_API
142  TfToken GetColorSpace() const;
143 
144  /// Sets the color-space in which a color or texture valued attribute is
145  /// authored.
146  SDF_API
147  void SetColorSpace(const TfToken &colorSpace);
148 
149  /// Returns true if this attribute has a colorSpace value authored.
150  SDF_API
151  bool HasColorSpace() const;
152 
153  /// Clears the colorSpace metadata value set on this attribute.
154  SDF_API
155  void ClearColorSpace();
156 
157  /// @}
158  /// \name Spec properties
159  /// @{
160 
161  /// Returns the roleName for this attribute's typeName.
162  ///
163  /// If the typeName has no roleName, return empty token.
164  SDF_API
165  TfToken GetRoleName() const;
166 
167  /// @}
168 };
169 
170 /// Convenience function to create an attributeSpec on a primSpec at the given
171 /// path, and any necessary parent primSpecs, in the given layer.
172 ///
173 /// If an attributeSpec already exists at the given path, just author typeName,
174 /// variability, and custom according to passed arguments and return true.
175 ///
176 /// Any newly created prim specs have SdfSpecifierOver and an empty type (as if
177 /// created by SdfJustCreatePrimInLayer()). attrPath must be a valid prim
178 /// property path (see SdfPath::IsPrimPropertyPath()). Return false and issue
179 /// an error if we fail to author the required scene description.
180 SDF_API
181 bool
183  const SdfLayerHandle &layer,
184  const SdfPath &attrPath,
185  const SdfValueTypeName &typeName,
187  bool isCustom = false);
188 
190 
191 #endif // PXR_USD_SDF_ATTRIBUTE_SPEC_H
SDF_API SdfConnectionsProxy GetConnectionPathList() const
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
static SDF_API SdfAttributeSpecHandle New(const SdfPrimSpecHandle &owner, const std::string &name, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying, bool custom=false)
SdfAttributeSpec This
Definition: attributeSpec.h:61
SDF_API bool HasConnectionPaths() const
Returns true if any connection paths are set on this attribute.
Definition: enum.h:136
SdfPropertySpec Parent
Definition: attributeSpec.h:62
SDF_API VtTokenArray GetAllowedTokens() const
SDF_API void ClearAllowedTokens()
Clears the allowed tokens metadata for this attribute.
SDF_API void ClearColorSpace()
Clears the colorSpace metadata value set on this attribute.
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
Definition: token.h:87
SDF_API bool SdfJustCreatePrimAttributeInLayer(const SdfLayerHandle &layer, const SdfPath &attrPath, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying, bool isCustom=false)
SDF_API bool HasColorSpace() const
Returns true if this attribute has a colorSpace value authored.
SDF_API bool HasAllowedTokens() const
Returns true if allowed tokens metadata is set for this attribute.
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:290
SDF_API void ClearDisplayUnit()
Clears the display unit of the attribute.
SdfVariability
Definition: types.h:173
#define SDF_API
Definition: api.h:40
SDF_API void SetDisplayUnit(const TfEnum &displayUnit)
Sets the display unit of the attribute.
SDF_API void SetColorSpace(const TfToken &colorSpace)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
SDF_API void ClearConnectionPaths()
Clears the connection paths for this attribute.
SDF_API TfToken GetColorSpace() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDF_API TfToken GetRoleName() const
SDF_API bool HasDisplayUnit() const
Returns true if a display unit is set for this attribute.
SDF_API TfEnum GetDisplayUnit() const
Returns the display unit of the attribute.
SDF_API void SetAllowedTokens(const VtTokenArray &allowedTokens)
Sets the allowed tokens metadata for this attribute.