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 USDRI_GENERATED_SPLINEAPI_H 25 #define USDRI_GENERATED_SPLINEAPI_H 26 27 /// \file usdRi/splineAPI.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/usdRi/api.h" 31 #include "pxr/usd/usd/apiSchemaBase.h" 32 #include "pxr/usd/usd/prim.h" 33 #include "pxr/usd/usd/stage.h" 34 35 #include "pxr/base/vt/value.h" 36 37 #include "pxr/base/gf/vec3d.h" 38 #include "pxr/base/gf/vec3f.h" 39 #include "pxr/base/gf/matrix4d.h" 40 41 #include "pxr/base/tf/token.h" 42 #include "pxr/base/tf/type.h" 43 44 PXR_NAMESPACE_OPEN_SCOPE 45 46 class SdfAssetPath; 47 48 // -------------------------------------------------------------------------- // 49 // RISPLINEAPI // 50 // -------------------------------------------------------------------------- // 51 52 /// \class UsdRiSplineAPI 53 /// 54 /// 55 /// \deprecated This API schema will be removed in a future release. 56 /// 57 /// RiSplineAPI is a general purpose API schema used to describe 58 /// a named spline stored as a set of attributes on a prim. 59 /// 60 /// It is an add-on schema that can be applied many times to a prim with 61 /// different spline names. All the attributes authored by the schema 62 /// are namespaced under "$NAME:spline:", with the name of the 63 /// spline providing a namespace for the attributes. 64 /// 65 /// The spline describes a 2D piecewise cubic curve with a position and 66 /// value for each knot. This is chosen to give straightforward artistic 67 /// control over the shape. The supported basis types are: 68 /// 69 /// - linear (UsdRiTokens->linear) 70 /// - bspline (UsdRiTokens->bspline) 71 /// - Catmull-Rom (UsdRiTokens->catmullRom) 72 /// 73 /// 74 class UsdRiSplineAPI : public UsdAPISchemaBase 75 { 76 public: 77 /// Compile time constant representing what kind of schema this class is. 78 /// 79 /// \sa UsdSchemaKind 80 static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI; 81 82 /// Construct a UsdRiSplineAPI on UsdPrim \p prim . 83 /// Equivalent to UsdRiSplineAPI::Get(prim.GetStage(), prim.GetPath()) 84 /// for a \em valid \p prim, but will not immediately throw an error for 85 /// an invalid \p prim 86 explicit UsdRiSplineAPI(const UsdPrim& prim=UsdPrim()) UsdAPISchemaBase(prim)87 : UsdAPISchemaBase(prim) 88 { 89 } 90 91 /// Construct a UsdRiSplineAPI on the prim held by \p schemaObj . 92 /// Should be preferred over UsdRiSplineAPI(schemaObj.GetPrim()), 93 /// as it preserves SchemaBase state. UsdRiSplineAPI(const UsdSchemaBase & schemaObj)94 explicit UsdRiSplineAPI(const UsdSchemaBase& schemaObj) 95 : UsdAPISchemaBase(schemaObj) 96 { 97 } 98 99 /// Destructor. 100 USDRI_API 101 virtual ~UsdRiSplineAPI(); 102 103 /// Return a vector of names of all pre-declared attributes for this schema 104 /// class and all its ancestor classes. Does not include attributes that 105 /// may be authored by custom/extended methods of the schemas involved. 106 USDRI_API 107 static const TfTokenVector & 108 GetSchemaAttributeNames(bool includeInherited=true); 109 110 /// Return a UsdRiSplineAPI holding the prim adhering to this 111 /// schema at \p path on \p stage. If no prim exists at \p path on 112 /// \p stage, or if the prim at that path does not adhere to this schema, 113 /// return an invalid schema object. This is shorthand for the following: 114 /// 115 /// \code 116 /// UsdRiSplineAPI(stage->GetPrimAtPath(path)); 117 /// \endcode 118 /// 119 USDRI_API 120 static UsdRiSplineAPI 121 Get(const UsdStagePtr &stage, const SdfPath &path); 122 123 124 /// Returns true if this <b>single-apply</b> API schema can be applied to 125 /// the given \p prim. If this schema can not be a applied to the prim, 126 /// this returns false and, if provided, populates \p whyNot with the 127 /// reason it can not be applied. 128 /// 129 /// Note that if CanApply returns false, that does not necessarily imply 130 /// that calling Apply will fail. Callers are expected to call CanApply 131 /// before calling Apply if they want to ensure that it is valid to 132 /// apply a schema. 133 /// 134 /// \sa UsdPrim::GetAppliedSchemas() 135 /// \sa UsdPrim::HasAPI() 136 /// \sa UsdPrim::CanApplyAPI() 137 /// \sa UsdPrim::ApplyAPI() 138 /// \sa UsdPrim::RemoveAPI() 139 /// 140 USDRI_API 141 static bool 142 CanApply(const UsdPrim &prim, std::string *whyNot=nullptr); 143 144 /// Applies this <b>single-apply</b> API schema to the given \p prim. 145 /// This information is stored by adding "RiSplineAPI" to the 146 /// token-valued, listOp metadata \em apiSchemas on the prim. 147 /// 148 /// \return A valid UsdRiSplineAPI object is returned upon success. 149 /// An invalid (or empty) UsdRiSplineAPI object is returned upon 150 /// failure. See \ref UsdPrim::ApplyAPI() for conditions 151 /// resulting in failure. 152 /// 153 /// \sa UsdPrim::GetAppliedSchemas() 154 /// \sa UsdPrim::HasAPI() 155 /// \sa UsdPrim::CanApplyAPI() 156 /// \sa UsdPrim::ApplyAPI() 157 /// \sa UsdPrim::RemoveAPI() 158 /// 159 USDRI_API 160 static UsdRiSplineAPI 161 Apply(const UsdPrim &prim); 162 163 protected: 164 /// Returns the kind of schema this class belongs to. 165 /// 166 /// \sa UsdSchemaKind 167 USDRI_API 168 UsdSchemaKind _GetSchemaKind() const override; 169 170 private: 171 // needs to invoke _GetStaticTfType. 172 friend class UsdSchemaRegistry; 173 USDRI_API 174 static const TfType &_GetStaticTfType(); 175 176 static bool _IsTypedSchema(); 177 178 // override SchemaBase virtuals. 179 USDRI_API 180 const TfType &_GetTfType() const override; 181 182 public: 183 // ===================================================================== // 184 // Feel free to add custom code below this line, it will be preserved by 185 // the code generator. 186 // 187 // Just remember to: 188 // - Close the class declaration with }; 189 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 190 // - Close the include guard with #endif 191 // ===================================================================== // 192 // --(BEGIN CUSTOM CODE)-- 193 194 /// Construct a UsdRiSplineAPI with the given \p splineName on 195 /// the UsdPrim \p prim . UsdRiSplineAPI(const UsdPrim & prim,const TfToken & splineName,const SdfValueTypeName & valuesTypeName,bool doesDuplicateBSplineEndpoints)196 explicit UsdRiSplineAPI(const UsdPrim& prim, const TfToken &splineName, 197 const SdfValueTypeName &valuesTypeName, 198 bool doesDuplicateBSplineEndpoints) 199 : UsdAPISchemaBase(prim) 200 , _splineName(splineName) 201 , _valuesTypeName(valuesTypeName) 202 , _duplicateBSplineEndpoints(doesDuplicateBSplineEndpoints) 203 { 204 } 205 206 /// Construct a UsdRiSplineAPI with the given \p splineName on 207 /// the prim held by \p schemaObj . UsdRiSplineAPI(const UsdSchemaBase & schemaObj,const TfToken & splineName,const SdfValueTypeName & valuesTypeName,bool doesDuplicateBSplineEndpoints)208 explicit UsdRiSplineAPI(const UsdSchemaBase& schemaObj, 209 const TfToken &splineName, 210 const SdfValueTypeName &valuesTypeName, 211 bool doesDuplicateBSplineEndpoints) 212 : UsdAPISchemaBase(schemaObj.GetPrim()) 213 , _splineName(splineName) 214 , _valuesTypeName(valuesTypeName) 215 , _duplicateBSplineEndpoints(doesDuplicateBSplineEndpoints) 216 { 217 } 218 219 /// Returns true if this UsdRiSplineAPI is configured to ensure 220 /// the endpoints are duplicated when using a bspline basis. 221 /// 222 /// Duplicating the endpoints ensures that the spline reaches 223 /// those points at either end of the parameter range. 224 USDRI_API DoesDuplicateBSplineEndpoints()225 bool DoesDuplicateBSplineEndpoints() const { 226 return _duplicateBSplineEndpoints; 227 } 228 229 /// Returns the intended typename of the values attribute of the spline. 230 USDRI_API GetValuesTypeName()231 SdfValueTypeName GetValuesTypeName() const { 232 return _valuesTypeName; 233 } 234 235 // --------------------------------------------------------------------- // 236 // INTERPOLATION 237 // --------------------------------------------------------------------- // 238 /// Interpolation method for the spline. 239 /// 240 /// \n C++ Type: TfToken 241 /// \n Usd Type: SdfValueTypeNames->Token 242 /// \n Variability: SdfVariabilityUniform 243 /// \n Fallback Value: linear 244 /// \n \ref UsdRiTokens "Allowed Values": [linear, constant, bspline, catmullRom] 245 USDRI_API 246 UsdAttribute GetInterpolationAttr() const; 247 248 /// See GetInterpolationAttr(), and also 249 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 250 /// If specified, author \p defaultValue as the attribute's default, 251 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 252 /// the default for \p writeSparsely is \c false. 253 USDRI_API 254 UsdAttribute CreateInterpolationAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 255 256 // --------------------------------------------------------------------- // 257 // POSITIONS 258 // --------------------------------------------------------------------- // 259 /// Positions of the knots. 260 /// 261 /// \n C++ Type: VtArray<float> 262 /// \n Usd Type: SdfValueTypeNames->FloatArray 263 /// \n Variability: SdfVariabilityUniform 264 /// \n Fallback Value: No Fallback 265 USDRI_API 266 UsdAttribute GetPositionsAttr() const; 267 268 /// See GetPositionsAttr(), and also 269 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 270 /// If specified, author \p defaultValue as the attribute's default, 271 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 272 /// the default for \p writeSparsely is \c false. 273 USDRI_API 274 UsdAttribute CreatePositionsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 275 276 // --------------------------------------------------------------------- // 277 // VALUES 278 // --------------------------------------------------------------------- // 279 /// Values of the knots. 280 /// 281 /// \n C++ Type: See GetValuesTypeName() 282 /// \n Usd Type: See GetValuesTypeName() 283 /// \n Variability: SdfVariabilityUniform 284 /// \n Fallback Value: No Fallback 285 USDRI_API 286 UsdAttribute GetValuesAttr() const; 287 288 /// See GetValuesAttr(), and also 289 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 290 /// If specified, author \p defaultValue as the attribute's default, 291 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 292 /// the default for \p writeSparsely is \c false. 293 USDRI_API 294 UsdAttribute CreateValuesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 295 296 /// \anchor UsdRiSplineAPI_Validation 297 /// \name Spline Validation API 298 /// 299 /// API for validating the properties of a spline. 300 /// 301 /// @{ 302 303 /// Validates the attribute values belonging to the spline. Returns true 304 /// if the spline has all valid attribute values. Returns false and 305 /// populates the \p reason output argument if the spline has invalid 306 /// attribute values. 307 /// 308 /// Here's the list of validations performed by this method: 309 /// \li the SplineAPI must be fully initialized 310 /// \li interpolation attribute must exist and use an allowed value 311 /// \li the positions array must be a float array 312 /// \li the positions array must be sorted by increasing value 313 /// \li the values array must use the correct value type 314 /// \li the positions and values array must have the same size 315 /// 316 USDRI_API 317 bool Validate(std::string *reason) const; 318 319 /// @} 320 321 private: 322 /// Returns the properly-scoped form of the given property name, 323 /// accounting for the spline name. 324 TfToken _GetScopedPropertyName(const TfToken &baseName) const; 325 326 private: 327 const TfToken _splineName; 328 const SdfValueTypeName _valuesTypeName; 329 bool _duplicateBSplineEndpoints; 330 }; 331 332 PXR_NAMESPACE_CLOSE_SCOPE 333 334 #endif 335