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" 31 #include "pxr/usd/sdf/declareSpec.h" 32 #include "pxr/usd/sdf/path.h" 33 #include "pxr/usd/sdf/propertySpec.h" 34 #include "pxr/usd/sdf/types.h" 35 #include "pxr/base/tf/enum.h" 36 37 PXR_NAMESPACE_OPEN_SCOPE 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 /// 56 class SdfAttributeSpec : public SdfPropertySpec 57 { 58 SDF_DECLARE_SPEC(SdfAttributeSpec, SdfPropertySpec); 59 60 public: 61 typedef SdfAttributeSpec This; 62 typedef SdfPropertySpec Parent; 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, 76 SdfVariability variability = SdfVariabilityVarying, 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 89 SdfConnectionsProxy GetConnectionPathList() const; 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 182 SdfJustCreatePrimAttributeInLayer( 183 const SdfLayerHandle &layer, 184 const SdfPath &attrPath, 185 const SdfValueTypeName &typeName, 186 SdfVariability variability = SdfVariabilityVarying, 187 bool isCustom = false); 188 189 PXR_NAMESPACE_CLOSE_SCOPE 190 191 #endif // PXR_USD_SDF_ATTRIBUTE_SPEC_H 192