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_STATEMENTSAPI_H 25 #define USDRI_GENERATED_STATEMENTSAPI_H 26 27 /// \file usdRi/statementsAPI.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/usd/usdGeom/primvarsAPI.h" 36 37 38 #include "pxr/base/vt/value.h" 39 40 #include "pxr/base/gf/vec3d.h" 41 #include "pxr/base/gf/vec3f.h" 42 #include "pxr/base/gf/matrix4d.h" 43 44 #include "pxr/base/tf/token.h" 45 #include "pxr/base/tf/type.h" 46 47 PXR_NAMESPACE_OPEN_SCOPE 48 49 class SdfAssetPath; 50 51 // -------------------------------------------------------------------------- // 52 // STATEMENTSAPI // 53 // -------------------------------------------------------------------------- // 54 55 /// \class UsdRiStatementsAPI 56 /// 57 /// Container namespace schema for all renderman statements. 58 /// 59 /// \note The longer term goal is for clients to go directly to primvar 60 /// or render-attribute API's, instead of using UsdRi StatementsAPI 61 /// for inherited attributes. Anticpating this, StatementsAPI 62 /// can smooth the way via a few environment variables: 63 /// 64 /// * USDRI_STATEMENTS_READ_OLD_ENCODING: Causes StatementsAPI to read 65 /// old-style attributes instead of primvars in the "ri:" 66 /// namespace. 67 /// 68 /// 69 class UsdRiStatementsAPI : public UsdAPISchemaBase 70 { 71 public: 72 /// Compile time constant representing what kind of schema this class is. 73 /// 74 /// \sa UsdSchemaKind 75 static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI; 76 77 /// Construct a UsdRiStatementsAPI on UsdPrim \p prim . 78 /// Equivalent to UsdRiStatementsAPI::Get(prim.GetStage(), prim.GetPath()) 79 /// for a \em valid \p prim, but will not immediately throw an error for 80 /// an invalid \p prim 81 explicit UsdRiStatementsAPI(const UsdPrim& prim=UsdPrim()) UsdAPISchemaBase(prim)82 : UsdAPISchemaBase(prim) 83 { 84 } 85 86 /// Construct a UsdRiStatementsAPI on the prim held by \p schemaObj . 87 /// Should be preferred over UsdRiStatementsAPI(schemaObj.GetPrim()), 88 /// as it preserves SchemaBase state. UsdRiStatementsAPI(const UsdSchemaBase & schemaObj)89 explicit UsdRiStatementsAPI(const UsdSchemaBase& schemaObj) 90 : UsdAPISchemaBase(schemaObj) 91 { 92 } 93 94 /// Destructor. 95 USDRI_API 96 virtual ~UsdRiStatementsAPI(); 97 98 /// Return a vector of names of all pre-declared attributes for this schema 99 /// class and all its ancestor classes. Does not include attributes that 100 /// may be authored by custom/extended methods of the schemas involved. 101 USDRI_API 102 static const TfTokenVector & 103 GetSchemaAttributeNames(bool includeInherited=true); 104 105 /// Return a UsdRiStatementsAPI holding the prim adhering to this 106 /// schema at \p path on \p stage. If no prim exists at \p path on 107 /// \p stage, or if the prim at that path does not adhere to this schema, 108 /// return an invalid schema object. This is shorthand for the following: 109 /// 110 /// \code 111 /// UsdRiStatementsAPI(stage->GetPrimAtPath(path)); 112 /// \endcode 113 /// 114 USDRI_API 115 static UsdRiStatementsAPI 116 Get(const UsdStagePtr &stage, const SdfPath &path); 117 118 119 /// Returns true if this <b>single-apply</b> API schema can be applied to 120 /// the given \p prim. If this schema can not be a applied to the prim, 121 /// this returns false and, if provided, populates \p whyNot with the 122 /// reason it can not be applied. 123 /// 124 /// Note that if CanApply returns false, that does not necessarily imply 125 /// that calling Apply will fail. Callers are expected to call CanApply 126 /// before calling Apply if they want to ensure that it is valid to 127 /// apply a schema. 128 /// 129 /// \sa UsdPrim::GetAppliedSchemas() 130 /// \sa UsdPrim::HasAPI() 131 /// \sa UsdPrim::CanApplyAPI() 132 /// \sa UsdPrim::ApplyAPI() 133 /// \sa UsdPrim::RemoveAPI() 134 /// 135 USDRI_API 136 static bool 137 CanApply(const UsdPrim &prim, std::string *whyNot=nullptr); 138 139 /// Applies this <b>single-apply</b> API schema to the given \p prim. 140 /// This information is stored by adding "StatementsAPI" to the 141 /// token-valued, listOp metadata \em apiSchemas on the prim. 142 /// 143 /// \return A valid UsdRiStatementsAPI object is returned upon success. 144 /// An invalid (or empty) UsdRiStatementsAPI object is returned upon 145 /// failure. See \ref UsdPrim::ApplyAPI() for conditions 146 /// resulting in failure. 147 /// 148 /// \sa UsdPrim::GetAppliedSchemas() 149 /// \sa UsdPrim::HasAPI() 150 /// \sa UsdPrim::CanApplyAPI() 151 /// \sa UsdPrim::ApplyAPI() 152 /// \sa UsdPrim::RemoveAPI() 153 /// 154 USDRI_API 155 static UsdRiStatementsAPI 156 Apply(const UsdPrim &prim); 157 158 protected: 159 /// Returns the kind of schema this class belongs to. 160 /// 161 /// \sa UsdSchemaKind 162 USDRI_API 163 UsdSchemaKind _GetSchemaKind() const override; 164 165 private: 166 // needs to invoke _GetStaticTfType. 167 friend class UsdSchemaRegistry; 168 USDRI_API 169 static const TfType &_GetStaticTfType(); 170 171 static bool _IsTypedSchema(); 172 173 // override SchemaBase virtuals. 174 USDRI_API 175 const TfType &_GetTfType() const override; 176 177 public: 178 // ===================================================================== // 179 // Feel free to add custom code below this line, it will be preserved by 180 // the code generator. 181 // 182 // Just remember to: 183 // - Close the class declaration with }; 184 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 185 // - Close the include guard with #endif 186 // ===================================================================== // 187 // --(BEGIN CUSTOM CODE)-- 188 189 // --------------------------------------------------------------------- // 190 // CreateRiAttribute 191 // --------------------------------------------------------------------- // 192 /// Create a rib attribute on the prim to which this schema is attached. 193 /// A rib attribute consists of an attribute \em "nameSpace" and an 194 /// attribute \em "name". For example, the namespace "cull" may define 195 /// attributes "backfacing" and "hidden", and user-defined attributes 196 /// belong to the namespace "user". 197 /// 198 /// This method makes no attempt to validate that the given \p nameSpace 199 /// and \em name are actually meaningful to prman or any other 200 /// renderer. 201 /// 202 /// \param riType should be a known RenderMan type definition, which 203 /// can be array-valued. For instance, both "color" and "float[3]" 204 /// are valid values for \p riType. 205 USDRI_API 206 UsdAttribute 207 CreateRiAttribute( 208 const TfToken &name, 209 const std::string &riType, 210 const std::string &nameSpace = "user"); 211 212 /// Creates an attribute of the given \p tfType. 213 /// \overload 214 USDRI_API 215 UsdAttribute 216 CreateRiAttribute( 217 const TfToken &name, 218 const TfType &tfType, 219 const std::string &nameSpace = "user"); 220 221 /// Return a UsdAttribute representing the Ri attribute with the 222 /// name \a name, in the namespace \a nameSpace. The attribute 223 /// returned may or may not \b actually exist so it must be 224 /// checked for validity. 225 USDRI_API 226 UsdAttribute 227 GetRiAttribute( 228 const TfToken &name, 229 const std::string &nameSpace = "user"); 230 231 // --------------------------------------------------------------------- // 232 // GetRiAttributes 233 // --------------------------------------------------------------------- // 234 /// Return all rib attributes on this prim, or under a specific 235 /// namespace (e.g.\ "user"). 236 /// 237 /// As noted above, rib attributes can be either UsdAttribute or 238 /// UsdRelationship, and like all UsdProperties, need not have a defined 239 /// value. 240 USDRI_API 241 std::vector<UsdProperty> 242 GetRiAttributes(const std::string &nameSpace = "") const; 243 // --------------------------------------------------------------------- // 244 // GetRiAttributeName 245 // --------------------------------------------------------------------- // 246 /// Return the base, most-specific name of the rib attribute. For example, 247 /// the \em name of the rib attribute "cull:backfacing" is "backfacing" GetRiAttributeName(const UsdProperty & prop)248 inline static TfToken GetRiAttributeName(const UsdProperty &prop) { 249 return prop.GetBaseName(); 250 } 251 252 // --------------------------------------------------------------------- // 253 // GetRiAttributeNameSpace 254 // --------------------------------------------------------------------- // 255 /// Return the containing namespace of the rib attribute (e.g.\ "user"). 256 /// 257 USDRI_API 258 static TfToken GetRiAttributeNameSpace(const UsdProperty &prop); 259 260 // --------------------------------------------------------------------- // 261 // IsRiAttribute 262 // --------------------------------------------------------------------- // 263 /// Return true if the property is in the "ri:attributes" namespace. 264 /// 265 USDRI_API 266 static bool IsRiAttribute(const UsdProperty &prop); 267 268 // --------------------------------------------------------------------- // 269 // MakeRiAttributePropertyName 270 // --------------------------------------------------------------------- // 271 /// Returns the given \p attrName prefixed with the full Ri attribute 272 /// namespace, creating a name suitable for an RiAttribute UsdProperty. 273 /// This handles conversion of common separator characters used in 274 /// other packages, such as periods and underscores. 275 /// 276 /// Will return empty string if attrName is not a valid property 277 /// identifier; otherwise, will return a valid property name 278 /// that identifies the property as an RiAttribute, according to the 279 /// following rules: 280 /// \li If \p attrName is already a properly constructed RiAttribute 281 /// property name, return it unchanged. 282 /// \li If \p attrName contains two or more tokens separated by a \em colon, 283 /// consider the first to be the namespace, and the rest the name, 284 /// joined by underscores 285 /// \li If \p attrName contains two or more tokens separated by a \em period, 286 /// consider the first to be the namespace, and the rest the name, 287 /// joined by underscores 288 /// \li If \p attrName contains two or more tokens separated by an, 289 /// \em underscore consider the first to be the namespace, and the 290 /// rest the name, joined by underscores 291 /// \li else, assume \p attrName is the name, and "user" is the namespace 292 USDRI_API 293 static std::string MakeRiAttributePropertyName(const std::string &attrName); 294 295 // --------------------------------------------------------------------- // 296 // SetCoordinateSystem 297 // --------------------------------------------------------------------- // 298 /// Sets the "ri:coordinateSystem" attribute to the given string value, 299 /// creating the attribute if needed. That identifies this prim as providing 300 /// a coordinate system, which can be retrieved via 301 /// UsdGeomXformable::GetTransformAttr(). Also adds the owning prim to the 302 /// ri:modelCoordinateSystems relationship targets on its parent leaf model 303 /// prim, if it exists. If this prim is not under a leaf model, no 304 /// relationship targets will be authored. 305 /// 306 USDRI_API 307 void SetCoordinateSystem(const std::string &coordSysName); 308 309 // --------------------------------------------------------------------- // 310 // GetCoordinateSystem 311 // --------------------------------------------------------------------- // 312 /// Returns the value in the "ri:coordinateSystem" attribute if it exists. 313 /// 314 USDRI_API 315 std::string GetCoordinateSystem() const; 316 317 // --------------------------------------------------------------------- // 318 // HasCoordinateSystem 319 // --------------------------------------------------------------------- // 320 /// Returns true if the underlying prim has a ri:coordinateSystem opinion. 321 /// 322 USDRI_API 323 bool HasCoordinateSystem() const; 324 325 // --------------------------------------------------------------------- // 326 // SetScopedCoordinateSystem 327 // --------------------------------------------------------------------- // 328 /// Sets the "ri:scopedCoordinateSystem" attribute to the given string 329 /// value, creating the attribute if needed. That identifies this prim as 330 /// providing a coordinate system, which can be retrieved via 331 /// UsdGeomXformable::GetTransformAttr(). Such coordinate systems are 332 /// local to the RI attribute stack state, but does get updated properly 333 /// for instances when defined inside an object master. Also adds the 334 /// owning prim to the ri:modelScopedCoordinateSystems relationship 335 /// targets on its parent leaf model prim, if it exists. If this prim is 336 /// not under a leaf model, no relationship targets will be authored. 337 /// 338 USDRI_API 339 void SetScopedCoordinateSystem(const std::string &coordSysName); 340 341 // --------------------------------------------------------------------- // 342 // GetScopedCoordinateSystem 343 // --------------------------------------------------------------------- // 344 /// Returns the value in the "ri:scopedCoordinateSystem" attribute if it 345 /// exists. 346 /// 347 USDRI_API 348 std::string GetScopedCoordinateSystem() const; 349 350 // --------------------------------------------------------------------- // 351 // HasScopedCoordinateSystem 352 // --------------------------------------------------------------------- // 353 /// Returns true if the underlying prim has a ri:scopedCoordinateSystem 354 /// opinion. 355 /// 356 USDRI_API 357 bool HasScopedCoordinateSystem() const; 358 359 // --------------------------------------------------------------------- // 360 // GetModelCoordinateSystems 361 // --------------------------------------------------------------------- // 362 /// Populates the output \p targets with the authored 363 /// ri:modelCoordinateSystems, if any. Returns true if the query was 364 /// successful. 365 /// 366 USDRI_API 367 bool GetModelCoordinateSystems(SdfPathVector *targets) const; 368 369 // --------------------------------------------------------------------- // 370 // GetModelScopedCoordinateSystems 371 // --------------------------------------------------------------------- // 372 /// Populates the output \p targets with the authored 373 /// ri:modelScopedCoordinateSystems, if any. Returns true if the query was 374 /// successful. 375 /// 376 USDRI_API 377 bool GetModelScopedCoordinateSystems(SdfPathVector *targets) const; 378 379 }; 380 381 PXR_NAMESPACE_CLOSE_SCOPE 382 383 #endif 384