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