XUSD_AttributeUtils.h

Go to the documentation of this file.

/*
 * Copyright 2019 Side Effects Software Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

#ifndef __XUSD_AttributeUtils_h__
#define __XUSD_AttributeUtils_h__

#include "HUSD_API.h"
#include <SYS/SYS_Deprecated.h>
#include <SYS/SYS_Types.h>
#include <UT/UT_UniquePtr.h>
#include <pxr/pxr.h>
#include <pxr/usd/sdf/attributeSpec.h>

class VOP_Node;
class VOP_TypeInfo;
class PI_EditScriptedParm;
class PRM_Parm;
class HUSD_TimeCode;
class HUSD_AutoAnyLock;

PXR_NAMESPACE_OPEN_SCOPE
class UsdObject;
class UsdAttribute;
class UsdRelationship;
class UsdTimeCode;
class UsdShadeInput;
class UsdShadeOutput;
struct UsdShadeConnectionSourceInfo;

/// Returns the SdfValueTypeName string best corresponding to the UT type.
template<typename UT_VALUE_TYPE>
HUSD_API const char *
HUSDgetSdfTypeName();

/// Sets the given @p attribute to the given @p value.
template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDsetAttribute(const UsdAttribute &attribute,
        const UT_VALUE_TYPE &value,
        const UsdTimeCode &timecode,
        bool clear_existing = true);

/// Sets the given @p attribute to the value of a given @p parm.
/// @note HUSD_TimeCode allows evaluating a parameter at a given frame
///       while authoring an attribute value at the default time code.
HUSD_API bool
HUSDsetAttribute(const UsdAttribute &attribute,
        const PRM_Parm &parm, 
        const HUSD_TimeCode &timecode);

/// The lock_to_release is freed before calling setValue on the parm. This
/// may be necessary because PRM_Parm::setValue evaluates the PRM_Parm first.
/// This may execute expression functions which involve cooking the LOP
/// Network in a way this might invalidate the lock. So in this function we
/// will free the lock object before calling setValue.
HUSD_API bool
HUSDsetNodeParm(PRM_Parm &parm,
        const UsdAttribute &attribute, 
        const UsdTimeCode &timecode,
        bool save_for_undo = false,
        UT_UniquePtr<HUSD_AutoAnyLock> *lock_to_release = nullptr);

/// The lock_to_release is freed before calling setValue on the parm. This
/// may be necessary because PRM_Parm::setValue evaluates the PRM_Parm first.
/// This may execute expression functions which involve cooking the LOP
/// Network in a way this might invalidate the lock. So in this function we
/// will free the lock object before calling setValue.
HUSD_API bool
HUSDsetRelationshipNodeParm(PRM_Parm &parm,
        const SdfPathVector &rel_targets,
        bool save_for_undo = false,
        UT_UniquePtr<HUSD_AutoAnyLock> *lock_to_release = nullptr);

/// Sets the parameter to specify the given source for a connection.
HUSD_API bool
HUSDsetConnectionNodeParm(PRM_Parm &parm,
        const UsdShadeConnectionSourceInfo &src_info,
        bool save_for_undo = false,
        UT_UniquePtr<HUSD_AutoAnyLock> *lock_to_release = nullptr);

/// Gets the @p value of the given @p attribute at specified @p timecode.
template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDgetAttribute(const UsdAttribute &attribute, UT_VALUE_TYPE &value,
        const UsdTimeCode &timecode);

/// Obtains the source the given destination attribute is connected to.
HUSD_API bool
HUSDgetFirstConnectedSrc( const UsdAttribute &attribute, 
        UsdShadeConnectionSourceInfo &src_info_value );
HUSD_API bool
HUSDgetFirstConnectedSrc( const UsdShadeInput &shade_input, 
        UsdShadeConnectionSourceInfo &src_info_value );
HUSD_API bool
HUSDgetFirstConnectedSrc( const UsdShadeOutput &shade_output, 
        UsdShadeConnectionSourceInfo &src_info_value );


template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDgetAttributeSpecDefault(const SdfAttributeSpec &spec,
        UT_VALUE_TYPE &value);

/// Gets obj's metadata given its name (eg, "active" or  "customData:foo:bar").
template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDsetMetadata(const UsdObject &object, const TfToken &name,
        const UT_VALUE_TYPE &value);

/// Gets obj's metadata given its name (eg, "active" or  "customData:foo:bar").
template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDgetMetadata(const UsdObject &object, const TfToken &name,
        UT_VALUE_TYPE &value);

HUSD_API bool
HUSDclearMetadata(const UsdObject &object, const TfToken &name);

/// Metadata utilities
HUSD_API bool HUSDhasMetadata(const UsdObject &object, const TfToken &name);
HUSD_API bool HUSDisArrayMetadata(const UsdObject &object, const TfToken &name);
HUSD_API exint  HUSDgetMetadataLength(const UsdObject &object, 
        const TfToken &name);

/// Fetch custom data.
template<typename UT_VALUE_TYPE>
HUSD_API bool HUSDgetCustomData(const UsdObject &object, const TfToken &name,
        UT_VALUE_TYPE &value);

/// Fetch asset info.
template<typename UT_VALUE_TYPE>
HUSD_API bool HUSDgetAssetInfo(const UsdObject &object, const TfToken &name,
        UT_VALUE_TYPE &value);

/// Conversion function between VtValue and UT_* value objects.
template<typename UT_VALUE_TYPE>
HUSD_API bool
HUSDgetValue( const VtValue &vt_value, UT_VALUE_TYPE &ut_value );

/// Conversion function between from UT_* value objects and a VtValue with
/// a matching GfValue inside.
template<typename UT_VALUE_TYPE>
HUSD_API VtValue
HUSDgetVtValue( const UT_VALUE_TYPE &ut_value );


/// Returns the best suited Usd attribute type given the Houdini parameter.
HUSD_API SdfValueTypeName   HUSDgetAttribSdfTypeName( 
        const PI_EditScriptedParm &parm );

/// Returns the value of the best suited Usd type given the Houdini parameter.
HUSD_API VtValue
HUSDgetShaderParmValue( const PRM_Parm &parm, const HUSD_TimeCode &timecode); 
HUSD_API VtValue
HUSDgetShaderParmDefaultValue( const PRM_Parm &parm );

/// Returns the type of a shader input attribute given the VOP node input.
HUSD_API SdfValueTypeName   HUSDgetShaderAttribSdfTypeName( 
        const PRM_Parm &parm );
HUSD_API SdfValueTypeName   HUSDgetShaderInputSdfTypeName(
        const VOP_Node &vop, int input_idx, 
        const PRM_Parm *parm_hint = nullptr );
HUSD_API SdfValueTypeName   HUSDgetShaderOutputSdfTypeName(
        const VOP_Node &vop, int output_idx, 
        const PRM_Parm *parm_hint = nullptr );
HUSD_API VOP_TypeInfo       HUSDgetVopTypeInfo(SdfValueTypeName sdf_type_name);


PXR_NAMESPACE_CLOSE_SCOPE

#endif