HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
HUSD_Utils.h
Go to the documentation of this file.
1 /*
2  * Copyright 2019 Side Effects Software Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  */
17 
18 #ifndef __HUSD_Utils_h__
19 #define __HUSD_Utils_h__
20 
21 #include "HUSD_API.h"
22 #include "HUSD_DataHandle.h"
23 #include "HUSD_Path.h"
24 #include <UT/UT_StringHolder.h>
25 #include <UT/UT_IntArray.h>
26 #include <UT/UT_Lock.h>
27 #include <UT/UT_Map.h>
28 
29 class HUSD_PathSet;
30 class HUSD_TimeCode;
31 class UT_Options;
32 class UT_String;
34 class PRM_Parm;
35 class OP_Node;
36 
43 
44  // This value is only used to create the scene graph tree through
45  // HUSD_PrimHandle. It should never be used to find prims to edit.
47 
48  // This places no limitations on which prims to return, but will not
49  // return instance proxies or prototype prims.
51 
52  // By default, place no demands on the traversal. This will even return
53  // pure "over" primitives, which may have incomplete definitions.
55 };
56 
57 // This enum specifies how a reference or sublayer or payload file reference
58 // is stored in the referring layer. The AUTO method stores paths specified
59 // as relative paths as relative paths, and paths specified as absolute paths
60 // as absolute paths. Paths specified as Search Paths (neither relative nor
61 // absolute) are always saved as-is.
63 {
67 };
68 
69 // This is the order of the viewport overrides layers. Note that they are
70 // ordered strongest to weakest, so the "solo" layers override the base layer,
71 // and the "custom" layer overrides the "solo" layers.
78 };
79 #define HUSD_OVERRIDES_NUM_LAYERS 5
80 
81 // Enum values that correspond to the SdfVariability values in the USD library.
85 };
86 
87 // Enum describing possible behaviors when layers are stripped off because of
88 // a layer break operation.
93 };
94 
95 // Enum describing the possible time sampling levels.
96 enum class HUSD_TimeSampling {
97  NONE, // no time samples; just the default value (not time varying)
98  SINGLE, // single time sample exists (value is not really time varying)
99  MULTIPLE // more than one time sample exists (value may be time varying)
100 };
101 
102 // Callback function to be defined in the LOP library that returns a locked
103 // stage pointer for a LOP node given an "op:" prefixed path.
105 
106 // A list of path strings that contain instance id numbers (possibly nested).
107 // Expressed with a typedef in case we decide to make this a more efficient
108 // data structure in the future.
110 
111 // Configures the USD library for use within Houdini. The primary purpose is to
112 // set the prefered ArResolver to be the Houdini resolver. This should be
113 // called as soon as possible after loading the HUSD library.
114 HUSD_API void
116 
117 // Set the callback function that is used by the HUSD library to resolve a
118 // LOP node path into an HUSD_LockedStagePtr. This callback is used to help
119 // populate the GusdStageCache for a USD packed primitive with a "file" path
120 // that points to a LOP node using an "op:" style path.
121 HUSD_API void
123 
124 // Calls the GusdStageCache::SplitLopStageIdentifier method, without having to
125 // inclde the stageCache.h header, which is not allowed in the LOP library.
126 HUSD_API bool
127 HUSDsplitLopStageIdentifier(const UT_StringRef &identifier,
128  OP_Node *&lop,
129  bool &split_layers,
130  fpreal &t,
131  UT_Options &opts);
132 
133 /// Returns true if name is a valid identifier (ie, valid component of a path).
134 HUSD_API bool
136 
137 // Modifies the passed in string to make sure it conforms to USD primitive
138 // naming restrictions. Illegal characters are replaced by underscores.
139 HUSD_API bool
140 HUSDmakeValidUsdName(UT_String &name, bool addwarnings);
141 
142 // Returns the name of the node passed through the HUSDmakeValidUsdName method.
143 // This saves several lines of code every time we use this pattern.
146 
147 // Modifies the passed in string to make sure it conforms to USD primitive
148 // naming restrictions. Illegal characters are replaced by underscores. Each
149 // path component is validated separately. The returned path will always be
150 // an absolute path, prefixing "/" to any passed in relative path.
151 HUSD_API bool
152 HUSDmakeValidUsdPath(UT_String &path, bool addwarnings);
153 
154 // As the above function, except it has the option of allowing the passed in
155 // and returned path to be a relative path.
156 HUSD_API bool
157 HUSDmakeValidUsdPath(UT_String &path, bool addwarnings, bool allow_relative);
158 
159 // Like the above method, but accepts "defaultPrim" as well.
160 HUSD_API bool
162 
163 // Ensures the given primitive path is unique and does not conflict
164 // with any existing primitives on the stage given by the lock.
165 // If suffix is given, if the given path is colliding, the new path
166 // will use it along with a digit to disambiguate it.
167 // Returns true if given path had to be changed; false otherwise.
168 HUSD_API bool
170  const UT_StringRef &suffix = UT_StringRef());
171 
172 // Returns the path of the node passed through the HUSDmakeValidUsdPath method.
173 // This saves several lines of code every time we use this pattern.
176 
177 // Modifies the passed in string to make sure it conforms to USD property
178 // naming restrictions. This includes allowing multiple nested namespaces
179 // in the name. Illegal characters are replaced by underscores.
180 HUSD_API bool
181 HUSDmakeValidUsdPropertyName(UT_String &name, bool addwarnings);
182 
183 // Modifies the passed in string to make sure it conforms to USD variant
184 // naming restrictions. Note that these are different from normal primitive
185 // naming conventions, as defined in SdfSchemaBase::IsValidVariantIdentifier:
186 // One or more letter, number, '_', '|', or '-', with an optional leading '.'
187 // Illegal characters are replaced by underscores.
188 HUSD_API bool
189 HUSDmakeValidVariantName(UT_String &name, bool addwarnings);
190 
191 // Modifies the passed in string to make sure it conforms to USD primitive
192 // naming restrictions. Leading slashes are thrown away. Illegal characters
193 // are considered an error and cause this function to return false.
194 HUSD_API bool
195 HUSDmakeValidDefaultPrim(UT_String &default_prim, bool addwarnings);
196 
197 // Returns primitive name, given the primitive path.
199 HUSDgetUsdName(const UT_StringRef &primpath);
200 
201 // Returns primitive's parent path, given the primitive path.
203 HUSDgetUsdParentPath(const UT_StringRef &primpath);
204 
205 // Modifies the provided path set so that if all the children of a prim are
206 // in the set, the children are removed, and the parent prim is put in the
207 // set instead. This procedure is applied recursively. This converts some
208 // parameters to USD types then calls the XUSD_Utils version of this method.
209 HUSD_API void
211  bool skip_point_instancers,
212  const HUSD_AutoAnyLock &lock,
214 
215 // Return the primary alias for the specified USD primitive type.
217 HUSDgetPrimTypeAlias(const UT_StringRef &primtype);
218 
219 // If layers are stripped during a flatten operation, this function handles
220 // the error creation based on the requested response. Returns true of the
221 // requested response is to generate an error, which usually means we should
222 // also stop processing.
223 HUSD_API bool
225 
226 /// Enum of USD transform operation types.
227 /// Note, they need to correspond to UsdGeomXformOp::Type enum.
228 enum class HUSD_XformType {
229  Invalid,
230  Translate,
231  Scale,
234  Orient,
235  Transform
236 };
237 
238 /// Enum of rotation axis.
239 enum class HUSD_XformAxis { X, Y, Z };
240 
241 /// Enum of rotation order.
242 enum class HUSD_XformAxisOrder { XYZ, XZY, YXZ, YZX, ZXY, ZYX };
243 
244 /// @{ Functions for obtaining transform name, suffix, and type.
246  UT_StringHolder &xform_namesuffix,
247  const UT_StringRef& xform_fullname);
251  const UT_StringRef &xform_namesuffix);
253  UT_StringHolder *xform_type = nullptr,
254  UT_StringHolder *xform_name = nullptr);
255 /// @}
256 
257 /// @{ Manipulate collection paths and components. The individual components
258 /// must be validated (see HUSDmakeValidName and HUSDmakeValidPath) before
259 /// calling these methods.
261  const UT_StringRef &collection_name);
263  UT_StringHolder &collection_name,
264  const UT_StringRef &collection_path);
266 /// @}
267 
268 /// @{ Create property paths from their components. The individual components
269 /// must be validated (see HUSDmakeValidName and HUSDmakeValidPath) before
270 /// calling these methods.
272  const UT_StringRef &property_name);
274  const UT_StringRef &attribute_name);
276  const UT_StringRef &relationship_name);
277 /// @}
278 
279 /// Returns the attribute name of the given primvar
281 
282 /// Returns the string name of the Usd Sdf type best suited for the parameter.
284 
285 /// Returns the time code at which to author an attribute value.
287  const HUSD_TimeCode &timecode,
288  HUSD_TimeSampling time_sampling);
289 
290 /// Returns true if there are more than one time samples.
291 HUSD_API bool HUSDisTimeVarying(HUSD_TimeSampling time_sampling);
292 
293 /// Returns true if there is at least one time sample.
294 HUSD_API bool HUSDisTimeSampled(HUSD_TimeSampling time_sampling);
295 
296 /// Set a parameter value from the value of a USD property.
298  const UT_StringRef &primpath,
299  const UT_StringRef &attribname,
300  const HUSD_TimeCode &tc,
301  PRM_Parm &parm,
302  HUSD_TimeSampling &timesampling);
303 
304 /// Split the found prims into shade and geo prims.
305 /// The parms control whether materials bound to geo prims are included
306 /// in the shade prims, and if so, whether to include material's surface
307 /// shader rather than material itself, if the material has no interface
308 /// input attributes (ie, is not particularly editable).
310  const HUSD_AutoAnyLock &anylock,
311  const HUSD_PathSet &primpaths,
312  UT_StringArray &shadeprimpaths,
313  UT_StringArray &geoprimpaths,
314  bool include_bound_materials = true,
315  bool use_shader_for_mat_with_no_inputs = true);
316 
317 /// Gets a list of primitives that are siblings or ancestors (or siblings
318 /// of ancestors) of any of the provided prims, and are also have any
319 /// of these prims as direct or indirect sources (via UsdConnectableAPI).
320 /// This method will work for materials, light filters, or any other
321 /// connectable prim type.
323  const HUSD_AutoAnyLock &anylock,
324  const UT_StringArray &modified_primpaths);
325 /// Bump metadata on a USD primitive to force a hydra update.
327  const HUSD_AutoWriteLock &writelock,
328  const UT_StringArray &bump_primpaths);
329 
330 /// Return a lock object that should be obtained by any code that is going
331 /// to call a USD method that reloads a layer, and by any code that needs to
332 /// be protected against layers being reloaded on another thread. This exists
333 /// primarily to protect background render delegate update threads from
334 /// reload calls happening while reading from the viewport stage.
336 
337 #endif
HUSD_API void HUSDgetMinimalPathsForInheritableProperty(bool skip_point_instancers, const HUSD_AutoAnyLock &lock, HUSD_PathSet &paths)
HUSD_API bool HUSDmakeValidDefaultPrim(UT_String &default_prim, bool addwarnings)
HUSD_API UT_StringHolder HUSDmakePropertyPath(const UT_StringRef &prim_path, const UT_StringRef &property_name)
HUSD_LockedStagePtr(* HUSD_LopStageResolver)(const UT_StringRef &path)
Definition: HUSD_Utils.h:104
HUSD_API void HUSDinitialize()
HUSD_API UT_StringHolder HUSDgetValidUsdPath(OP_Node &node)
HUSD_API bool HUSDisValidUsdName(const UT_StringRef &name)
Returns true if name is a valid identifier (ie, valid component of a path).
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
HUSD_API bool HUSDsetParmFromProperty(HUSD_AutoAnyLock &lock, const UT_StringRef &primpath, const UT_StringRef &attribname, const HUSD_TimeCode &tc, PRM_Parm &parm, HUSD_TimeSampling &timesampling)
Set a parameter value from the value of a USD property.
HUSD_API void HUSDsetLopStageResolver(HUSD_LopStageResolver resolver)
#define HUSD_API
Definition: HUSD_API.h:32
HUSD_API bool HUSDmakeValidUsdPropertyName(UT_String &name, bool addwarnings)
HUSD_API bool HUSDmakeValidUsdPath(UT_String &path, bool addwarnings)
GLuint const GLchar * name
Definition: glcorearb.h:786
HUSD_API UT_StringHolder HUSDgetUsdName(const UT_StringRef &primpath)
HUSD_PrimTraversalDemands
Definition: HUSD_Utils.h:37
GLdouble GLdouble t
Definition: glew.h:1403
HUSD_XformAxis
Enum of rotation axis.
Definition: HUSD_Utils.h:239
HUSD_OverridesLayerId
Definition: HUSD_Utils.h:72
HUSD_Variability
Definition: HUSD_Utils.h:82
UT_StringSet HUSD_InstanceSelection
Definition: HUSD_Utils.h:109
HUSD_API UT_Lock & HUSDgetLayerReloadLock()
HUSD_API UT_StringHolder HUSDmakeCollectionPath(const UT_StringRef &prim_path, const UT_StringRef &collection_name)
HUSD_API UT_StringHolder HUSDgetUsdParentPath(const UT_StringRef &primpath)
HUSD_XformType
Definition: HUSD_Utils.h:228
HUSD_API bool HUSDmakeValidUsdName(UT_String &name, bool addwarnings)
HUSD_TimeSampling
Definition: HUSD_Utils.h:96
HUSD_API UT_StringArray HUSDgetConnectedPrimsToBumpForHydra(const HUSD_AutoAnyLock &anylock, const UT_StringArray &modified_primpaths)
HUSD_API bool HUSDisValidCollectionPath(const UT_StringRef &path)
HUSD_API bool HUSDisXformAttribute(const UT_StringRef &attr, UT_StringHolder *xform_type=nullptr, UT_StringHolder *xform_name=nullptr)
Functions for obtaining transform name, suffix, and type.
HUSD_API UT_StringHolder HUSDmakeRelationshipPath(const UT_StringRef &prim_path, const UT_StringRef &relationship_name)
HUSD_API UT_StringHolder HUSDgetXformSuffix(const UT_StringRef &xform_fullname)
Functions for obtaining transform name, suffix, and type.
HUSD_API bool HUSDgetXformTypeAndSuffix(HUSD_XformType &xform_type, UT_StringHolder &xform_namesuffix, const UT_StringRef &xform_fullname)
Functions for obtaining transform name, suffix, and type.
HUSD_API bool HUSDsplitCollectionPath(UT_StringHolder &prim_path, UT_StringHolder &collection_name, const UT_StringRef &collection_path)
GLfloat GLfloat p
Definition: glew.h:16656
HUSD_StripLayerResponse
Definition: HUSD_Utils.h:89
HUSD_API HUSD_TimeCode HUSDgetEffectiveTimeCode(const HUSD_TimeCode &timecode, HUSD_TimeSampling time_sampling)
Returns the time code at which to author an attribute value.
HUSD_API bool HUSDisTimeVarying(HUSD_TimeSampling time_sampling)
Returns true if there are more than one time samples.
HUSD_API bool HUSDmakeValidUsdPathOrDefaultPrim(UT_String &path, bool addwarnings)
HUSD_API bool HUSDpartitionShadePrims(const HUSD_AutoAnyLock &anylock, const HUSD_PathSet &primpaths, UT_StringArray &shadeprimpaths, UT_StringArray &geoprimpaths, bool include_bound_materials=true, bool use_shader_for_mat_with_no_inputs=true)
A map of string to various well defined value types.
Definition: UT_Options.h:84
HUSD_API bool HUSDmakeValidVariantName(UT_String &name, bool addwarnings)
HUSD_API UT_StringHolder HUSDmakeAttributePath(const UT_StringRef &prim_path, const UT_StringRef &attribute_name)
HUSD_API bool HUSDsplitLopStageIdentifier(const UT_StringRef &identifier, OP_Node *&lop, bool &split_layers, fpreal &t, UT_Options &opts)
fpreal64 fpreal
Definition: SYS_Types.h:277
UT_SharedPtr< HUSD_LockedStage > HUSD_LockedStagePtr
const GLfloat * tc
Definition: glew.h:16639
HUSD_API UT_StringHolder HUSDgetXformName(HUSD_XformType xform_type, const UT_StringRef &xform_namesuffix)
Functions for obtaining transform name, suffix, and type.
HUSD_XformAxisOrder
Enum of rotation order.
Definition: HUSD_Utils.h:242
HUSD_PathSaveStyle
Definition: HUSD_Utils.h:62
HUSD_API UT_StringHolder HUSDgetPrimvarAttribName(const UT_StringRef &primvar)
Returns the attribute name of the given primvar.
HUSD_API bool HUSDapplyStripLayerResponse(HUSD_StripLayerResponse response)
HUSD_API HUSD_XformType HUSDgetXformType(const UT_StringRef &xform_fullname)
Functions for obtaining transform name, suffix, and type.
HUSD_API bool HUSDisTimeSampled(HUSD_TimeSampling time_sampling)
Returns true if there is at least one time sample.
HUSD_API UT_StringHolder HUSDgetPrimTypeAlias(const UT_StringRef &primtype)
HUSD_API bool HUSDmakeUniqueUsdPath(UT_String &path, const HUSD_AutoAnyLock &lock, const UT_StringRef &suffix=UT_StringRef())
HUSD_API bool HUSDbumpPrimsForHydra(const HUSD_AutoWriteLock &writelock, const UT_StringArray &bump_primpaths)
Bump metadata on a USD primitive to force a hydra update.
HUSD_API UT_StringHolder HUSDgetValidUsdName(OP_Node &node)
GLenum const void * paths
Definition: glew.h:13872
HUSD_API UT_StringHolder HUSDgetAttribTypeName(const PI_EditScriptedParm &p)
Returns the string name of the Usd Sdf type best suited for the parameter.