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_Function.h>
25 #include <UT/UT_IntArray.h>
26 #include <UT/UT_Lock.h>
27 #include <UT/UT_Map.h>
28 #include <UT/UT_StringHolder.h>
29 #include <SYS/SYS_Hash.h>
30 
31 class HUSD_PathSet;
32 class HUSD_TimeCode;
33 class UT_Options;
34 class UT_String;
36 class PRM_Parm;
37 class OP_Node;
38 
45 
46  // This value is only used to create the scene graph tree through
47  // HUSD_PrimHandle. It should never be used to find prims to edit.
49 
50  // This places no limitations on which prims to return, but will not
51  // return instance proxies or prototype prims.
53 
54  // By default, place no demands on the traversal. This will even return
55  // pure "over" primitives, which may have incomplete definitions.
58  // A combination of the default demands and support for instance proxies.
59  // This is a very common combination.
62 };
63 
64 // This enum specifies how a reference or sublayer or payload file reference
65 // is stored in the referring layer. The AUTO method stores paths specified
66 // as relative paths as relative paths, and paths specified as absolute paths
67 // as absolute paths. Paths specified as Search Paths (neither relative nor
68 // absolute) are always saved as-is.
70 {
74 };
75 
76 // This is the order of the viewport overrides layers. Note that they are
77 // ordered strongest to weakest, so the "solo" layers override the base layer,
78 // and the "custom" layer overrides the "solo" layers.
87 };
88 #define HUSD_OVERRIDES_NUM_LAYERS 7
89 
90 // Enum values that correspond to the SdfVariability values in the USD library.
94 };
95 
96 // Enum describing possible behaviors when layers are stripped off because of
97 // a layer break operation.
102 };
103 
104 // Enum describing the possible time sampling levels.
105 enum class HUSD_TimeSampling {
106  NONE, // no time samples; just the default value (not time varying)
107  SINGLE, // single time sample exists (value is not really time varying)
108  MULTIPLE // more than one time sample exists (value may be time varying)
109 };
110 
111 // Enum describing possible aspect ratio conformance policies.
113 {
114  INVALID = -1,
121 };
122 
123 // Describes the different ways of dealing with custom RenderProduct types:
124 // IGNORE: Do nothing, even if all products are custom types.
125 // ADD_AOVS: Request AOVs associated with custom products from the
126 // renderer. This is used for viewport renders.
127 // CREATE_DUMMY_RASTER: If all products are custom, create a dummy raster
128 // product to at least output a beauty image.
133 };
134 
135 // A "render key" which consists of the int values from the pickid and instid
136 // buffers generated by a render delegate.
138 {
139 public:
140  HUSD_RenderKey(int pick_id = -1, int inst_id = -1)
141  : myPickId(pick_id),
142  myInstId(inst_id)
143  { }
144 
145  bool operator==(const HUSD_RenderKey &other) const
146  {
147  return myPickId == other.myPickId &&
148  myInstId == other.myInstId;
149  }
150 
151  int myPickId;
152  int myInstId;
153 };
154 
155 // Hashing function for render keys.
156 inline size_t hash_value(const HUSD_RenderKey &key)
157 {
158  SYS_HashType hash = SYShash(key.myPickId);
159  SYShashCombine(hash, key.myInstId);
160 
161  return hash;
162 }
163 
164 // Map of render key to the scene graph path it corresponds to.
166 
167 // Callback function to be defined in the LOP library that returns a locked
168 // stage pointer for a LOP node given an "op:" prefixed path.
170 
171 // A list of path strings that contain instance id numbers (possibly nested).
172 // Expressed with a typedef in case we decide to make this a more efficient
173 // data structure in the future.
175 
176 // Configures the USD library for use within Houdini. The primary purpose is to
177 // set the prefered ArResolver to be the Houdini resolver. This should be
178 // called as soon as possible after loading the HUSD library.
179 HUSD_API void
181 
182 // Set the callback function that is used by the HUSD library to resolve a
183 // LOP node path into an HUSD_LockedStagePtr. This callback is used to help
184 // populate the GusdStageCache for a USD packed primitive with a "file" path
185 // that points to a LOP node using an "op:" style path.
186 HUSD_API void
188 
189 // Calls the GusdStageCache::SplitLopStageIdentifier method, without having to
190 // inclde the stageCache.h header, which is not allowed in the LOP library.
191 HUSD_API bool
192 HUSDsplitLopStageIdentifier(const UT_StringRef &identifier,
193  OP_Node *&lop,
194  int &output_index,
195  bool &split_layers,
196  fpreal &t,
197  UT_Options &opts);
198 
199 // Returns true if name is a valid identifier (ie, valid component of a path).
200 HUSD_API bool
202 
203 // Modifies the passed in string to make sure it conforms to USD primitive
204 // naming restrictions. Illegal characters are replaced by underscores.
205 HUSD_API bool
206 HUSDmakeValidUsdName(UT_String &name, bool addwarnings);
207 
208 // Returns the name of the node passed through the HUSDmakeValidUsdName method.
209 // This saves several lines of code every time we use this pattern.
212 
213 // Returns true if the given path is a syntactibally valid USD path.
214 HUSD_API bool
216 
217 // Modifies the passed in string to make sure it conforms to USD primitive
218 // naming restrictions. Illegal characters are replaced by underscores. Each
219 // path component is validated separately. The returned path will always be
220 // an absolute path, prefixing "/" to any passed in relative path.
221 HUSD_API bool
222 HUSDmakeValidUsdPath(UT_String &path, bool addwarnings);
223 
224 // As the above function, except it has the option of allowing the passed in
225 // and returned path to be a relative path.
226 HUSD_API bool
227 HUSDmakeValidUsdPath(UT_String &path, bool addwarnings, bool allow_relative);
228 
229 // Like the above method, but accepts "defaultPrim" as well.
230 HUSD_API bool
232 
233 // Ensures the given primitive path is unique and does not conflict
234 // with any existing primitives on the stage given by the lock.
235 // If suffix is given, if the given path is colliding, the new path
236 // will use it along with a digit to disambiguate it.
237 // Returns true if given path had to be changed; false otherwise.
238 HUSD_API bool
240  const UT_StringRef &suffix = UT_StringRef());
241 
242 // Returns the path of the node passed through the HUSDmakeValidUsdPath method.
243 // This saves several lines of code every time we use this pattern.
246 
247 // Modifies the passed in string to make sure it conforms to USD property
248 // naming restrictions. This includes allowing multiple nested namespaces
249 // in the name. Illegal characters are replaced by underscores.
250 HUSD_API bool
251 HUSDmakeValidUsdPropertyName(UT_String &name, bool addwarnings);
252 
253 // Modifies the passed in string to make sure it conforms to USD variant
254 // naming restrictions. Note that these are different from normal primitive
255 // naming conventions, as defined in SdfSchemaBase::IsValidVariantIdentifier:
256 // One or more letter, number, '_', '|', or '-', with an optional leading '.'
257 // Illegal characters are replaced by underscores.
258 HUSD_API bool
259 HUSDmakeValidVariantName(UT_String &name, bool allowexprs, bool addwarnings);
260 
261 // Modifies the passed in string to make sure it conforms to USD primitive
262 // naming restrictions. Leading slashes are thrown away. Illegal characters
263 // are replaced with underscores. Returns true (and adds a warning if
264 // addwarnings is true) if the string was modified.
265 HUSD_API bool
266 HUSDmakeValidDefaultPrim(UT_String &default_prim, bool addwarnings);
267 
268 // Returns primitive name, given the primitive path.
270 HUSDgetUsdName(const UT_StringRef &primpath);
271 
272 // Returns primitive's parent path, given the primitive path.
274 HUSDgetUsdParentPath(const UT_StringRef &primpath);
275 
276 // Returns the provided selection path with any instance id portion stripped
277 // off (e.g. /foo[6] -> /foo, but also /foo -> /foo).
279 HUSDremoveInstanceId(const UT_StringHolder &selectionpath);
280 
281 // Gives us a chance to fix problems in path expressions before passing them
282 // to USD. Many errors we can't fix, but simple ones like using spaces instead
283 // of \n or \t characters can be.
286 
287 // Modifies the provided path set so that if all the children of a prim are
288 // in the set, the children are removed, and the parent prim is put in the
289 // set instead. This procedure is applied recursively. This converts some
290 // parameters to USD types then calls the XUSD_Utils version of this method.
291 HUSD_API void
293  bool skip_point_instancers,
294  const HUSD_AutoAnyLock &lock,
295  HUSD_PathSet &paths);
296 
297 // Return the primary alias for the specified USD primitive type.
299 HUSDgetPrimTypeAlias(const UT_StringRef &primtype);
300 
301 // If layers are stripped during a flatten operation, this function handles
302 // the error creation based on the requested response. Returns true of the
303 // requested response is to generate an error, which usually means we should
304 // also stop processing.
305 HUSD_API bool
307 
308 /// Enum of USD transform operation types.
309 /// Note, they need to correspond to UsdGeomXformOp::Type enum.
310 enum class HUSD_XformType {
311  Invalid,
312  Translate,
313  Scale,
316  Orient,
317  Transform
318 };
319 
320 /// Enum of rotation axis.
321 enum class HUSD_XformAxis { X, Y, Z };
322 
323 /// Enum of rotation order.
324 enum class HUSD_XformAxisOrder { XYZ, XZY, YXZ, YZX, ZXY, ZYX };
325 
326 /// @{ Functions for obtaining transform name, suffix, and type.
328  UT_StringHolder &xform_namesuffix,
329  const UT_StringRef& xform_fullname);
333  const UT_StringRef &xform_namesuffix);
335  UT_StringHolder *xform_type = nullptr,
336  UT_StringHolder *xform_name = nullptr);
337 /// @}
338 
339 /// @{ Manipulate collection paths and components. The individual components
340 /// must be validated (see HUSDmakeValidName and HUSDmakeValidPath) before
341 /// calling these methods.
343  const UT_StringRef &collection_name);
345  UT_StringHolder &collection_name,
346  const UT_StringRef &collection_path);
348 /// @}
349 
350 /// @{ Create property paths from their components. The individual components
351 /// must be validated (see HUSDmakeValidName and HUSDmakeValidPath) before
352 /// calling these methods.
354  const UT_StringRef &property_name);
356  const UT_StringRef &attribute_name);
358  const UT_StringRef &relationship_name);
359 /// @}
360 
361 /// Returns the prim path and the property name, given the property path.
362 HUSD_API std::pair<UT_StringHolder, UT_StringHolder>
363 HUSDsplitPropertyPath(const UT_StringRef &property_path);
364 
365 /// Returns the attribute name of the given primvar
367 
368 /// Returns the string name of the Usd Sdf type best suited for the parameter.
370 
371 /// Returns the time code at which to author an attribute value.
373  const HUSD_TimeCode &timecode,
374  HUSD_TimeSampling time_sampling);
375 
376 /// Returns true if there are more than one time samples.
377 HUSD_API bool HUSDisTimeVarying(HUSD_TimeSampling time_sampling);
378 
379 /// Returns true if there is at least one time sample.
380 HUSD_API bool HUSDisTimeSampled(HUSD_TimeSampling time_sampling);
381 
382 /// Set a parameter value from the value of a USD property.
384  const UT_StringRef &primpath,
385  const UT_StringRef &attribname,
386  const HUSD_TimeCode &tc,
387  PRM_Parm &parm,
388  HUSD_TimeSampling &timesampling);
389 
390 /// Split the found prims into shade and geo prims.
391 /// The parms control whether materials bound to geo prims are included
392 /// in the shade prims, and if so, whether to include material's surface
393 /// shader rather than material itself, if the material has no interface
394 /// input attributes (ie, is not particularly editable).
396  const HUSD_AutoAnyLock &anylock,
397  const HUSD_PathSet &primpaths,
398  UT_StringArray &shadeprimpaths,
399  UT_StringArray &geoprimpaths,
400  bool include_bound_materials = true,
401  bool use_shader_for_mat_with_no_inputs = true);
402 
403 /// Gets a list of primitives that are siblings or ancestors (or siblings
404 /// of ancestors) of any of the provided prims, and are also have any
405 /// of these prims as direct or indirect sources (via UsdConnectableAPI).
406 /// This method will work for materials, light filters, or any other
407 /// connectable prim type.
409  const HUSD_AutoAnyLock &anylock,
410  const UT_StringArray &modified_primpaths);
411 /// Bump metadata on a USD primitive to force a hydra update.
413  const HUSD_AutoWriteLock &writelock,
414  const UT_StringArray &bump_primpaths);
415 
416 /// Return a lock object that should be obtained by any code that is going
417 /// to call a USD method that reloads a layer, and by any code that needs to
418 /// be protected against layers being reloaded on another thread. This exists
419 /// primarily to protect background render delegate update threads from
420 /// reload calls happening while reading from the viewport stage.
422 
423 /// Takes the root layer of the USD file at path and searches for all
424 /// referenced asset paths in that layer, replacing them with the
425 /// return value of modifyFn. The resulting layer is saved at the path
426 /// specified by dest. If path and dest are the same, it overwrites
427 /// the file at path.
428 HUSD_API void
430  const UT_Function<UT_StringHolder(UT_StringHolder)> &modifyFn,
431  const UT_StringHolder &dest);
432 
433 /// Return an array of layer ids that excludes the "expansion" layer. Most
434 /// layer operations should, by default, ignore the expansion layer as it is
435 /// controlled by the scene graph expansion state, not through direct user
436 /// interaction.
439 
440 HUSD_API bool
441 HUSDareLayersEqual(const UT_StringHolder &layerIdentifierA,
442  const UT_StringHolder &layerIdentifierB);
443 
444 
445 #endif
HUSD_API bool HUSDmakeValidVariantName(UT_String &name, bool allowexprs, bool addwarnings)
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)
constexpr size_t SYShash(const SYS_Flicks f)
Definition: SYS_Flicks.h:46
HUSD_RenderKey(int pick_id=-1, int inst_id=-1)
Definition: HUSD_Utils.h:140
HUSD_LockedStagePtr(* HUSD_LopStageResolver)(const UT_StringRef &path)
Definition: HUSD_Utils.h:169
HUSD_API void HUSDinitialize()
HUSD_API UT_StringHolder HUSDgetValidUsdPath(OP_Node &node)
HUSD_API bool HUSDisValidUsdName(const UT_StringRef &name)
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:31
std::size_t SYS_HashType
Define the type for hash values.
Definition: SYS_Hash.h:19
HUSD_API bool HUSDmakeValidUsdPropertyName(UT_String &name, bool addwarnings)
HUSD_API bool HUSDmakeValidUsdPath(UT_String &path, bool addwarnings)
HUSD_API UT_StringHolder HUSDgetUsdName(const UT_StringRef &primpath)
HUSD_PrimTraversalDemands
Definition: HUSD_Utils.h:39
HUSD_XformAxis
Enum of rotation axis.
Definition: HUSD_Utils.h:321
HUSD_OverridesLayerId
Definition: HUSD_Utils.h:79
HUSD_Variability
Definition: HUSD_Utils.h:91
UT_StringSet HUSD_InstanceSelection
Definition: HUSD_Utils.h:174
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:310
HUSD_API bool HUSDmakeValidUsdName(UT_String &name, bool addwarnings)
HUSD_TimeSampling
Definition: HUSD_Utils.h:105
HUSD_API UT_StringArray HUSDgetConnectedPrimsToBumpForHydra(const HUSD_AutoAnyLock &anylock, const UT_StringArray &modified_primpaths)
bool operator==(const HUSD_RenderKey &other) const
Definition: HUSD_Utils.h:145
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.
size_t hash_value(const HUSD_RenderKey &key)
Definition: HUSD_Utils.h:156
HUSD_API bool HUSDsplitCollectionPath(UT_StringHolder &prim_path, UT_StringHolder &collection_name, const UT_StringRef &collection_path)
HUSD_StripLayerResponse
Definition: HUSD_Utils.h:98
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.
GLuint const GLchar * name
Definition: glcorearb.h:786
HUSD_API std::pair< UT_StringHolder, UT_StringHolder > HUSDsplitPropertyPath(const UT_StringRef &property_path)
Returns the prim path and the property name, given the property path.
HUSD_API UT_StringHolder HUSDmakeValidPathExpression(const UT_StringHolder &path_expr)
std::function< T > UT_Function
Definition: UT_Function.h:37
HUSD_API bool HUSDmakeValidUsdPathOrDefaultPrim(UT_String &path, bool addwarnings)
HUSD_API bool HUSDisValidUsdPath(const UT_StringRef &path)
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)
GLdouble t
Definition: glad.h:2397
HUSD_API bool HUSDareLayersEqual(const UT_StringHolder &layerIdentifierA, const UT_StringHolder &layerIdentifierB)
A map of string to various well defined value types.
Definition: UT_Options.h:84
HUSD_API UT_StringHolder HUSDremoveInstanceId(const UT_StringHolder &selectionpath)
HUSD_API bool HUSDsplitLopStageIdentifier(const UT_StringRef &identifier, OP_Node *&lop, int &output_index, bool &split_layers, fpreal &t, UT_Options &opts)
HUSD_API UT_StringHolder HUSDmakeAttributePath(const UT_StringRef &prim_path, const UT_StringRef &attribute_name)
fpreal64 fpreal
Definition: SYS_Types.h:278
UT_SharedPtr< HUSD_LockedStage > HUSD_LockedStagePtr
HUSD_API UT_StringHolder HUSDgetXformName(HUSD_XformType xform_type, const UT_StringRef &xform_namesuffix)
Functions for obtaining transform name, suffix, and type.
HUSD_AspectConformPolicy
Definition: HUSD_Utils.h:112
HUSD_XformAxisOrder
Enum of rotation order.
Definition: HUSD_Utils.h:324
HUSD_API void HUSDmodifyAssetPaths(const UT_StringHolder &path, const UT_Function< UT_StringHolder(UT_StringHolder)> &modifyFn, const UT_StringHolder &dest)
HUSD_PathSaveStyle
Definition: HUSD_Utils.h:69
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.
UT_Map< HUSD_RenderKey, UT_StringHolder > HUSD_RenderKeyPathMap
Definition: HUSD_Utils.h:165
HUSD_API const UT_Array< HUSD_OverridesLayerId > & HUSDgetUserEditableOverrideLayerIds()
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)
HUSD_API UT_StringHolder HUSDgetAttribTypeName(const PI_EditScriptedParm &p)
Returns the string name of the Usd Sdf type best suited for the parameter.
HUSD_CustomProductAction
Definition: HUSD_Utils.h:129