HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
volume.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 USDVOL_GENERATED_VOLUME_H
25 #define USDVOL_GENERATED_VOLUME_H
26 
27 /// \file usdVol/volume.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdVol/api.h"
31 #include "pxr/usd/usdGeom/gprim.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 
45 
46 class SdfAssetPath;
47 
48 // -------------------------------------------------------------------------- //
49 // VOLUME //
50 // -------------------------------------------------------------------------- //
51 
52 /// \class UsdVolVolume
53 ///
54 /// A renderable volume primitive. A volume is made up of any number
55 /// of FieldBase primitives bound together in this volume. Each
56 /// FieldBase primitive is specified as a relationship with a
57 /// namespace prefix of "field".
58 ///
59 /// The relationship name is used by the renderer to associate
60 /// individual fields with the named input parameters on the volume
61 /// shader. Using this indirect approach to connecting fields to
62 /// shader parameters (rather than using the field prim's name)
63 /// allows a single field to be reused for different shader inputs, or
64 /// to be used as different shader parameters when rendering different
65 /// Volumes. This means that the name of the field prim is not
66 /// relevant to its contribution to the volume prims which refer to
67 /// it. Nor does the field prim's location in the scene graph have
68 /// any relevance, and Volumes may refer to fields anywhere in the
69 /// scene graph. **However**, unless Field prims need to be shared
70 /// by multiple Volumes, a Volume's Field prims should be located
71 /// under the Volume in namespace, for enhanced organization.
72 ///
73 class UsdVolVolume : public UsdGeomGprim
74 {
75 public:
76  /// Compile time constant representing what kind of schema this class is.
77  ///
78  /// \sa UsdSchemaKind
80 
81  /// Construct a UsdVolVolume on UsdPrim \p prim .
82  /// Equivalent to UsdVolVolume::Get(prim.GetStage(), prim.GetPath())
83  /// for a \em valid \p prim, but will not immediately throw an error for
84  /// an invalid \p prim
85  explicit UsdVolVolume(const UsdPrim& prim=UsdPrim())
86  : UsdGeomGprim(prim)
87  {
88  }
89 
90  /// Construct a UsdVolVolume on the prim held by \p schemaObj .
91  /// Should be preferred over UsdVolVolume(schemaObj.GetPrim()),
92  /// as it preserves SchemaBase state.
93  explicit UsdVolVolume(const UsdSchemaBase& schemaObj)
94  : UsdGeomGprim(schemaObj)
95  {
96  }
97 
98  /// Destructor.
100  virtual ~UsdVolVolume();
101 
102  /// Return a vector of names of all pre-declared attributes for this schema
103  /// class and all its ancestor classes. Does not include attributes that
104  /// may be authored by custom/extended methods of the schemas involved.
105  USDVOL_API
106  static const TfTokenVector &
107  GetSchemaAttributeNames(bool includeInherited=true);
108 
109  /// Return a UsdVolVolume holding the prim adhering to this
110  /// schema at \p path on \p stage. If no prim exists at \p path on
111  /// \p stage, or if the prim at that path does not adhere to this schema,
112  /// return an invalid schema object. This is shorthand for the following:
113  ///
114  /// \code
115  /// UsdVolVolume(stage->GetPrimAtPath(path));
116  /// \endcode
117  ///
118  USDVOL_API
119  static UsdVolVolume
120  Get(const UsdStagePtr &stage, const SdfPath &path);
121 
122  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
123  /// is defined (according to UsdPrim::IsDefined()) on this stage.
124  ///
125  /// If a prim adhering to this schema at \p path is already defined on this
126  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
127  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
128  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
129  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
130  /// current EditTarget for any nonexistent, or existing but not \a Defined
131  /// ancestors.
132  ///
133  /// The given \a path must be an absolute prim path that does not contain
134  /// any variant selections.
135  ///
136  /// If it is impossible to author any of the necessary PrimSpecs, (for
137  /// example, in case \a path cannot map to the current UsdEditTarget's
138  /// namespace) issue an error and return an invalid \a UsdPrim.
139  ///
140  /// Note that this method may return a defined prim whose typeName does not
141  /// specify this schema class, in case a stronger typeName opinion overrides
142  /// the opinion at the current EditTarget.
143  ///
144  USDVOL_API
145  static UsdVolVolume
146  Define(const UsdStagePtr &stage, const SdfPath &path);
147 
148 protected:
149  /// Returns the kind of schema this class belongs to.
150  ///
151  /// \sa UsdSchemaKind
152  USDVOL_API
153  UsdSchemaKind _GetSchemaKind() const override;
154 
155 private:
156  // needs to invoke _GetStaticTfType.
157  friend class UsdSchemaRegistry;
158  USDVOL_API
159  static const TfType &_GetStaticTfType();
160 
161  static bool _IsTypedSchema();
162 
163  // override SchemaBase virtuals.
164  USDVOL_API
165  const TfType &_GetTfType() const override;
166 
167 public:
168  // ===================================================================== //
169  // Feel free to add custom code below this line, it will be preserved by
170  // the code generator.
171  //
172  // Just remember to:
173  // - Close the class declaration with };
174  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
175  // - Close the include guard with #endif
176  // ===================================================================== //
177  // --(BEGIN CUSTOM CODE)--
178 
179  // --------------------------------------------------------------------- //
180  /// \name Field Attachment and Inspection
181  /// @{
182  // --------------------------------------------------------------------- //
183 
184  typedef std::map<TfToken, SdfPath> FieldMap;
185 
186  /// Return a map of field relationship names to the fields themselves,
187  /// represented as prim paths. This map provides all the information
188  /// that should be needed to tie fields to shader parameters and render
189  /// this volume.
190  ///
191  /// The field relationship names that server as the map keys will have
192  /// the field namespace stripped from them.
193  USDVOL_API
194  FieldMap GetFieldPaths() const;
195 
196  /// Checks if there is an existing field relationship with a given name.
197  /// This query will return \c true even for a field relationship that
198  /// has been blocked and therefore will not contribute to the map
199  /// returned by GetFieldRelationships()
200  ///
201  /// The name lookup automatically applies the field relationship
202  /// namespacing, if it isn't specified in the name token.
203  USDVOL_API
204  bool HasFieldRelationship(const TfToken &name) const;
205 
206  /// Checks if there is an existing field relationship with a given name,
207  /// and if so, returns the path to the Field prim it targets, or else
208  /// the empty path.
209  ///
210  /// The name lookup automatically applies the field relationship
211  /// namespacing, if it isn't specified in the name token.
212  USDVOL_API
213  SdfPath GetFieldPath(const TfToken &name) const;
214 
215  /// Creates a relationship on this volume that targets the specified field.
216  /// If an existing relationship exists with the same name, it is replaced
217  /// (since only one target is allowed for each named relationship).
218  ///
219  /// Returns \c true if the relationship was successfully created and set -
220  /// it is legal to call this method for a field relationship that already
221  /// "exists", i.e. already posesses scene description, as this is the
222  /// only method we provide for setting a field relatioonship's value, to help
223  /// enforce that field relationships can have only a single (or no) target.
224  ///
225  /// \param fieldPath - can be a prim path, or the path of another
226  /// relationship, to effect \ref usd_relationship_forwarding
227  ///
228  /// The name lookup automatically applies the field relationship
229  /// namespacing, if it isn't specified in the name token.
230  USDVOL_API
232  const SdfPath &fieldPath) const;
233 
234  /// Blocks an existing field relationship on this volume, ensuring it
235  /// will not be enumerated by GetFieldPaths().
236  ///
237  /// Returns true if the relationship existed, false if it did not. In other
238  /// words the return value indicates whether the volume prim was changed.
239  ///
240  /// The name lookup automatically applies the field relationship
241  /// namespacing, if it isn't specified in the name token.
242  USDVOL_API
243  bool BlockFieldRelationship(const TfToken &name) const;
244 
245 private:
246  /// Return \p name prepended with the field namespace, if it isn't
247  /// already prefixed.
248  ///
249  /// Does not validate name as a legal relationship identifier.
250  static TfToken _MakeNamespaced(const TfToken& name);
251 };
252 
254 
255 #endif
static USDVOL_API UsdVolVolume Get(const UsdStagePtr &stage, const SdfPath &path)
static const UsdSchemaKind schemaKind
Definition: volume.h:79
USDVOL_API FieldMap GetFieldPaths() const
virtual USDVOL_API ~UsdVolVolume()
Destructor.
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDVOL_API bool HasFieldRelationship(const TfToken &name) const
UsdVolVolume(const UsdPrim &prim=UsdPrim())
Definition: volume.h:85
Definition: token.h:87
Represents a concrete typed schema.
UsdVolVolume(const UsdSchemaBase &schemaObj)
Definition: volume.h:93
Definition: prim.h:135
static USDVOL_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:291
USDVOL_API bool BlockFieldRelationship(const TfToken &name) const
USDVOL_API SdfPath GetFieldPath(const TfToken &name) const
UsdSchemaKind
Definition: common.h:127
USDVOL_API bool CreateFieldRelationship(const TfToken &name, const SdfPath &fieldPath) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
USDVOL_API UsdSchemaKind _GetSchemaKind() const override
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
#define USDVOL_API
Definition: api.h:40
std::map< TfToken, SdfPath > FieldMap
Definition: volume.h:184
static USDVOL_API UsdVolVolume Define(const UsdStagePtr &stage, const SdfPath &path)