HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
boundable.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 USDGEOM_GENERATED_BOUNDABLE_H
25 #define USDGEOM_GENERATED_BOUNDABLE_H
26 
27 /// \file usdGeom/boundable.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdGeom/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 #include "pxr/usd/usdGeom/tokens.h"
35 
36 #include "pxr/base/vt/value.h"
37 
38 #include "pxr/base/gf/vec3d.h"
39 #include "pxr/base/gf/vec3f.h"
40 #include "pxr/base/gf/matrix4d.h"
41 
42 #include "pxr/base/tf/token.h"
43 #include "pxr/base/tf/type.h"
44 
46 
47 class SdfAssetPath;
48 
49 // -------------------------------------------------------------------------- //
50 // BOUNDABLE //
51 // -------------------------------------------------------------------------- //
52 
53 /// \class UsdGeomBoundable
54 ///
55 /// Boundable introduces the ability for a prim to persistently
56 /// cache a rectilinear, local-space, extent.
57 ///
58 /// \section UsdGeom_Boundable_Extent Why Extent and not Bounds ?
59 /// Boundable introduces the notion of "extent", which is a cached computation
60 /// of a prim's local-space 3D range for its resolved attributes <b>at the
61 /// layer and time in which extent is authored</b>. We have found that with
62 /// composed scene description, attempting to cache pre-computed bounds at
63 /// interior prims in a scene graph is very fragile, given the ease with which
64 /// one can author a single attribute in a stronger layer that can invalidate
65 /// many authored caches - or with which a re-published, referenced asset can
66 /// do the same.
67 ///
68 /// Therefore, we limit to precomputing (generally) leaf-prim extent, which
69 /// avoids the need to read in large point arrays to compute bounds, and
70 /// provides UsdGeomBBoxCache the means to efficiently compute and
71 /// (session-only) cache intermediate bounds. You are free to compute and
72 /// author intermediate bounds into your scenes, of course, which may work
73 /// well if you have sufficient locks on your pipeline to guarantee that once
74 /// authored, the geometry and transforms upon which they are based will
75 /// remain unchanged, or if accuracy of the bounds is not an ironclad
76 /// requisite.
77 ///
78 /// When intermediate bounds are authored on Boundable parents, the child prims
79 /// will be pruned from BBox computation; the authored extent is expected to
80 /// incorporate all child bounds.
81 ///
83 {
84 public:
85  /// Compile time constant representing what kind of schema this class is.
86  ///
87  /// \sa UsdSchemaKind
89 
90  /// Construct a UsdGeomBoundable on UsdPrim \p prim .
91  /// Equivalent to UsdGeomBoundable::Get(prim.GetStage(), prim.GetPath())
92  /// for a \em valid \p prim, but will not immediately throw an error for
93  /// an invalid \p prim
94  explicit UsdGeomBoundable(const UsdPrim& prim=UsdPrim())
95  : UsdGeomXformable(prim)
96  {
97  }
98 
99  /// Construct a UsdGeomBoundable on the prim held by \p schemaObj .
100  /// Should be preferred over UsdGeomBoundable(schemaObj.GetPrim()),
101  /// as it preserves SchemaBase state.
102  explicit UsdGeomBoundable(const UsdSchemaBase& schemaObj)
103  : UsdGeomXformable(schemaObj)
104  {
105  }
106 
107  /// Destructor.
109  virtual ~UsdGeomBoundable();
110 
111  /// Return a vector of names of all pre-declared attributes for this schema
112  /// class and all its ancestor classes. Does not include attributes that
113  /// may be authored by custom/extended methods of the schemas involved.
115  static const TfTokenVector &
116  GetSchemaAttributeNames(bool includeInherited=true);
117 
118  /// Return a UsdGeomBoundable holding the prim adhering to this
119  /// schema at \p path on \p stage. If no prim exists at \p path on
120  /// \p stage, or if the prim at that path does not adhere to this schema,
121  /// return an invalid schema object. This is shorthand for the following:
122  ///
123  /// \code
124  /// UsdGeomBoundable(stage->GetPrimAtPath(path));
125  /// \endcode
126  ///
128  static UsdGeomBoundable
129  Get(const UsdStagePtr &stage, const SdfPath &path);
130 
131 
132 protected:
133  /// Returns the kind of schema this class belongs to.
134  ///
135  /// \sa UsdSchemaKind
137  UsdSchemaKind _GetSchemaKind() const override;
138 
139 private:
140  // needs to invoke _GetStaticTfType.
141  friend class UsdSchemaRegistry;
143  static const TfType &_GetStaticTfType();
144 
145  static bool _IsTypedSchema();
146 
147  // override SchemaBase virtuals.
149  const TfType &_GetTfType() const override;
150 
151 public:
152  // --------------------------------------------------------------------- //
153  // EXTENT
154  // --------------------------------------------------------------------- //
155  /// Extent is a three dimensional range measuring the geometric
156  /// extent of the authored gprim in its own local space (i.e. its own
157  /// transform not applied), \em without accounting for any shader-induced
158  /// displacement. If __any__ extent value has been authored for a given
159  /// Boundable, then it should be authored at every timeSample at which
160  /// geometry-affecting properties are authored, to ensure correct
161  /// evaluation via ComputeExtent(). If __no__ extent value has been
162  /// authored, then ComputeExtent() will call the Boundable's registered
163  /// ComputeExtentFunction(), which may be expensive, which is why we
164  /// strongly encourage proper authoring of extent.
165  /// \sa ComputeExtent()
166  /// \sa \ref UsdGeom_Boundable_Extent.
167  ///
168  /// An authored extent on a prim which has children is expected to include
169  /// the extent of all children, as they will be pruned from BBox computation
170  /// during traversal.
171  ///
172  /// | ||
173  /// | -- | -- |
174  /// | Declaration | `float3[] extent` |
175  /// | C++ Type | VtArray<GfVec3f> |
176  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float3Array |
178  UsdAttribute GetExtentAttr() const;
179 
180  /// See GetExtentAttr(), and also
181  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
182  /// If specified, author \p defaultValue as the attribute's default,
183  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
184  /// the default for \p writeSparsely is \c false.
186  UsdAttribute CreateExtentAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
187 
188 public:
189  // ===================================================================== //
190  // Feel free to add custom code below this line, it will be preserved by
191  // the code generator.
192  //
193  // Just remember to:
194  // - Close the class declaration with };
195  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
196  // - Close the include guard with #endif
197  // ===================================================================== //
198  // --(BEGIN CUSTOM CODE)--
199 
200  /// If an extent is authored on this boundable, it queries the \p extent
201  /// from the extent attribute, otherwise if ComputeExtentFunction is
202  /// registered for the boundable's type, it computes the \p extent at
203  /// \p time. Returns true when extent is successfully populated, false
204  /// otherwise.
205  ///
206  /// \sa ComputeExtentFromPlugins
207  /// \sa UsdGeomRegisterComputeExtentFunction
209  bool ComputeExtent(const UsdTimeCode &time, VtVec3fArray *extent);
210 
211  /// Compute the extent for the Boundable prim \p boundable at time
212  /// \p time. If successful, populates \p extent with the result and
213  /// returns \c true, otherwise returns \c false.
214  ///
215  /// The extent computation is based on the concrete type of the prim
216  /// represented by \p boundable. Plugins that provide a Boundable
217  /// prim type may implement and register an extent computation for that
218  /// type using #UsdGeomRegisterComputeExtentFunction.
219  /// ComputeExtentFromPlugins will use this function to compute extents
220  /// for all prims of that type. If no function has been registered for
221  /// a prim type, but a function has been registered for one of its
222  /// base types, that function will be used instead.
223  ///
224  /// \note This function may load plugins in order to access the extent
225  /// computation for a prim type.
227  static bool ComputeExtentFromPlugins(const UsdGeomBoundable &boundable,
228  const UsdTimeCode &time,
229  VtVec3fArray *extent);
230 
231  /// \overload
232  /// Computes the extent as if the matrix \p transform was first applied.
234  static bool ComputeExtentFromPlugins(const UsdGeomBoundable &boundable,
235  const UsdTimeCode &time,
236  const GfMatrix4d &transform,
237  VtVec3fArray *extent);
238 
239 };
240 
242 
243 #endif
GLint GLenum GLsizei GLsizei GLsizei GLsizei extent
Definition: glew.h:15877
USDGEOM_API UsdAttribute GetExtentAttr() const
GT_API const UT_StringHolder time
virtual USDGEOM_API ~UsdGeomBoundable()
Destructor.
USDGEOM_API UsdAttribute CreateExtentAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
USDGEOM_API bool ComputeExtent(const UsdTimeCode &time, VtVec3fArray *extent)
UsdGeomBoundable(const UsdSchemaBase &schemaObj)
Definition: boundable.h:102
UsdGeomBoundable(const UsdPrim &prim=UsdPrim())
Definition: boundable.h:94
GLuint GLenum GLenum transform
Definition: glew.h:15055
UsdSchemaKind
Definition: common.h:127
static const UsdSchemaKind schemaKind
Definition: boundable.h:88
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
static USDGEOM_API bool ComputeExtentFromPlugins(const UsdGeomBoundable &boundable, const UsdTimeCode &time, VtVec3fArray *extent)
Definition: path.h:290
static USDGEOM_API UsdGeomBoundable Get(const UsdStagePtr &stage, const SdfPath &path)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Represents a non-concrete typed schema.
Definition: type.h:64
#define USDGEOM_API
Definition: api.h:40
Definition: value.h:166