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