AAX_CParameter.h

Go to the documentation of this file.

/*================================================================================================*/
/*
 *
 *  Copyright 2013 by Avid Technology, Inc.
 *  All rights reserved.
 *  
 *  CONFIDENTIAL: This document contains confidential information.  Do not 
 *  read or examine this document unless you are an Avid Technology employee
 *  or have signed a non-disclosure agreement with Avid Technology which protects
 *  the confidentiality of this document.  DO NOT DISCLOSE ANY INFORMATION 
 *  CONTAINED IN THIS DOCUMENT TO ANY THIRD-PARTY WITHOUT THE PRIOR WRITTEN CONSENT 
 *  OF Avid Technolgy, INC.
 *
 */

/*================================================================================================*/


#ifndef AAX_CPARAMETER_H
#define AAX_CPARAMETER_H

#include "AAX_Assert.h"
#include "AAX_IParameter.h"
#include "AAX_ITaperDelegate.h"
#include "AAX_IDisplayDelegate.h"
#include "AAX_IAutomationDelegate.h"
#include "AAX_CString.h"                    //concrete class required for name.

#include <list>
#include <map>

template <typename T>
class AAX_CParameter : public AAX_IParameter
{
public:
    
    enum Type {
        eParameterTypeUndefined = 0,
        eParameterTypeBool = 1,
        eParameterTypeInt32 = 2,
        eParameterTypeFloat = 3,
        eParameterTypeCustom = 4
    };
    
    enum Defaults {
        eParameterDefaultNumStepsDiscrete = 2,
        eParameterDefaultNumStepsContinuous = 128,
        eParemeterDefaultMaxIdentifierSize = 32,
        eParameterDefaultMaxIdentifierLength = eParemeterDefaultMaxIdentifierSize - 1 // NULL terminated
    };
    
    AAX_CParameter(AAX_CParamID identifier, const AAX_CString& name, T defaultValue, const AAX_ITaperDelegate<T>& taperDelegate, const AAX_IDisplayDelegate<T>& displayDelegate, bool automatable=false);
    
    virtual             ~AAX_CParameter();
        
    AAX_CParamID        Identifier() const;                                                 //AAX_IParameter                    
    void                SetName(const AAX_CString& name);                                   //AAX_IParameter        
    const AAX_CString&  Name() const;                                                       //AAX_IParameter
    void                AddShortenedName(const AAX_CString& name);                          //AAX_IParameter
    const AAX_CString&  ShortenedName(int32_t iNumCharacters) const;                        //AAX_IParameter
    void                ClearShortenedNames();                                              //AAX_IParameter

    void                SetNormalizedDefaultValue(double normalizedDefault);                //AAX_IParameter
    double              GetNormalizedDefaultValue() const;                                  //AAX_IParameter        
    void                SetToDefaultValue();                                                //AAX_IParameter                
    void                SetNormalizedValue(double normalizedNewValue);                      //AAX_IParameter        
    double              GetNormalizedValue()    const;                                      //AAX_IParameter        
    void                SetNumberOfSteps(uint32_t numSteps);                                //AAX_IParameter            
    uint32_t            GetNumberOfSteps() const;                                           //AAX_IParameter    
    uint32_t            GetStepValue() const;                                               //AAX_IParameter    
    void                SetStepValue(uint32_t iStep);                                       //AAX_IParameter    
    void                SetType(AAX_EParameterType iControlType);                                       //AAX_IParameter            
    AAX_EParameterType  GetType() const;                                                    //AAX_IParameter        
    void                SetOrientation( AAX_EParameterOrientation iOrientation );
    AAX_EParameterOrientation           GetOrientation() const;

    bool                GetValueString( AAX_CString*    valueString) const;                                                                     //AAX_IParameter
    bool                GetValueString(int32_t iMaxNumChars, AAX_CString*   valueString) const;                                                 //AAX_IParameter
    bool                GetNormalizedValueFromString(const AAX_CString& valueString, double *normalizedValue) const;                            //AAX_IParameter
    bool                GetStringFromNormalizedValue(double normalizedValue, AAX_CString&   valueString) const;                                 //AAX_IParameter
    bool                GetStringFromNormalizedValue(double normalizedValue, int32_t iMaxNumChars, AAX_CString& valueString) const;         //AAX_IParameter
    bool                SetValueFromString(const AAX_CString&   newValueString);                                                                //AAX_IParameter

    void                SetAutomationDelegate ( AAX_IAutomationDelegate * iAutomationDelegate );    //AAX_IParameter
    bool                Automatable() const;                                                        //AAX_IParameter
    void                Touch();                                                                    //AAX_IParameter
    void                Release();                                                                  //AAX_IParameter
    
    bool                GetValueAsBool(bool* value) const;                                  //AAX_IParameter
    bool                GetValueAsInt32(int32_t* value) const;                              //AAX_IParameter
    bool                GetValueAsFloat(float* value) const;                                //AAX_IParameter
    bool                GetValueAsDouble(double* value) const;                              //AAX_IParameter
    bool                GetValueAsString(AAX_IString* value) const;                         //AAX_IParameter
    bool                SetValueWithBool(bool value);                                       //AAX_IParameter
    bool                SetValueWithInt32(int32_t value);                                   //AAX_IParameter
    bool                SetValueWithFloat(float value);                                     //AAX_IParameter
    bool                SetValueWithDouble(double value);                                   //AAX_IParameter
    bool                SetValueWithString(const AAX_IString& value);                               //AAX_IParameter
    
    void                            SetValue(T newValue );
    T                               GetValue() const;
    void                            SetDefaultValue(T newDefaultValue);
    T                               GetDefaultValue() const;
    void                            SetTaperDelegate(AAX_ITaperDelegateBase& taperDelegate,bool iPreserveValue=true);
    void                            SetDisplayDelegate(AAX_IDisplayDelegateBase& displayDelegate);
    const AAX_ITaperDelegate<T>*    TaperDelegate() const;
    const AAX_IDisplayDelegate<T>*  DisplayDelegate() const;
    
public: 
    
    void    UpdateNormalizedValue(double newNormalizedValue);                               //AAX_IParameter
    
    
protected:
    char                                        mIdentifier[eParemeterDefaultMaxIdentifierSize];
    AAX_CString                                 mName;
    std::map<uint32_t, AAX_CString>             mShortenedNames;
    bool                                        mAutomatable;
    uint32_t                                    mNumSteps;
    AAX_EParameterType                          mControlType;
    AAX_EParameterOrientation                   mOrientation;
    AAX_ITaperDelegate<T> *                     mTaperDelegate;
    AAX_IDisplayDelegate<T> *                   mDisplayDelegate;
    AAX_IAutomationDelegate *                   mAutomationDelegate;
    bool                                        mNeedNotify;
    
    T           mValue;
    T           mDefaultValue;

private:    
    AAX_CParameter();
    AAX_CParameter(const AAX_CParameter& other);
    AAX_CParameter& operator= (const AAX_CParameter& other);
};



template <typename T>
AAX_CParameter<T>::AAX_CParameter(AAX_CParamID identifier, const AAX_CString& name, T defaultValue, const AAX_ITaperDelegate<T>& taperDelegate, const AAX_IDisplayDelegate<T>& displayDelegate, bool automatable) :         
    mName(name),
    mAutomatable(automatable),
    mNumSteps(0), // Default set below for discrete/continuous
    mControlType( AAX_eParameterType_Continuous ),
    mOrientation( AAX_eParameterOrientation_BottomMinTopMax ),
    mTaperDelegate(taperDelegate.Clone()),
    mDisplayDelegate(displayDelegate.Clone()),
    mAutomationDelegate(0),
    mNeedNotify(true),
    mDefaultValue(defaultValue)
{ 
    size_t len = strlen(identifier);
    AAX_ASSERT(len < eParemeterDefaultMaxIdentifierSize);
    if (len < eParemeterDefaultMaxIdentifierSize)
    {
        std::strncpy(mIdentifier, identifier, 1+len);
        mIdentifier[len] = 0;
    }
    else
    {
        std::strncpy(mIdentifier, identifier, eParameterDefaultMaxIdentifierLength);
        mIdentifier[eParemeterDefaultMaxIdentifierSize - 1] = 0;
    }
    
    if (mNumSteps == 0) // If no explicit number of steps has been set...
    {
        switch (mControlType)
        {
            case AAX_eParameterType_Discrete:
            {
                // Discrete parameters default to binary unless
                // otherwise specified
                SetNumberOfSteps (eParameterDefaultNumStepsDiscrete);
                break;
            }
            case AAX_eParameterType_Continuous:
            {
                // Defaulting to 128 steps to match one full rotation of
                // Command|8 and similar surfaces, which query the num
                // steps to determine tick values for rotary encoders
                SetNumberOfSteps (eParameterDefaultNumStepsContinuous);
                break;
            }
            default:
            {
                AAX_ASSERT (0); // Invalid type
                break;
            }
        }
    }
        
    SetToDefaultValue();
}

template <typename T>
AAX_CParameter<T>::~AAX_CParameter()
{
    //Make sure to remove any registration with the token system.
    SetAutomationDelegate(0);
    
    delete mTaperDelegate;
    mTaperDelegate = 0;
    delete mDisplayDelegate;
    mDisplayDelegate = 0;
}

template <typename T>
AAX_CParamID        AAX_CParameter<T>::Identifier() const                   
{   
    return mIdentifier; 
}

template <typename T>
void        AAX_CParameter<T>::SetName(const AAX_CString& name) 
{   
    mName = name;  
}

template <typename T>
const AAX_CString&  AAX_CParameter<T>::Name() const                     
{   
    return mName;   
}


template <typename T>
void    AAX_CParameter<T>::AddShortenedName(const AAX_CString& name)
{
    uint32_t stringLength = name.Length();
    mShortenedNames[stringLength] = name;   //Does a string copy into the map.
}

template <typename T>
const AAX_CString&  AAX_CParameter<T>::ShortenedName(int32_t iNumCharacters) const
{
    //More characters than the full name of no specific shortened names.
    if ((iNumCharacters >= int32_t(mName.Length())) || (mShortenedNames.empty()) || (0 > iNumCharacters))
        return mName;
            
    std::map<uint32_t, AAX_CString>::const_iterator iter = mShortenedNames.upper_bound(static_cast<uint32_t>(iNumCharacters));
    
    //If the iterator is already pointing to shortest name, return that.
    if (iter == mShortenedNames.begin())    
        return iter->second;
    
    //lower_bound() will return the iterator that is larger than the desired value, so decrement the iterator.
    --iter;
    return iter->second;
}

template <typename T>
void                AAX_CParameter<T>::ClearShortenedNames()
{
    mShortenedNames.clear();
}



template<typename T>
void    AAX_CParameter<T>::SetValue( T newValue )
{
    double  newNormalizedValue = mTaperDelegate->RealToNormalized(newValue);

    // <DMT> Always go through the automation delegate even if the control isn't automatable to prevent fighting with other GUIs.
    // Somewhere back in the automation delegate, or elsewhere in the system, it will determine the differences in behavior surrounding
    // automation.  The only reason that there wouldn't be an automation delegate is if this parameter has yet to be added to a
    // ParameterManager.  Let's put the null value guards in place, just in case, and also for unit tests.
    if ( mAutomationDelegate )
    {
        //TODO: Create RAII utility class for touch/release
        
        //Touch the control
        Touch();
        
        //Send that token.
        mAutomationDelegate->PostSetValueRequest(Identifier(), newNormalizedValue );

        //Release the control
        Release();
    }
    else
    {
        mNeedNotify = true;

        // In the rare case that an automation delegate doesn't exist, lets still set the value.  It's possible that someone is trying to
        // set the new value before adding the parameter to a parametermanager.
        UpdateNormalizedValue(newNormalizedValue);
    }
}

template <typename T>
void    AAX_CParameter<T>::UpdateNormalizedValue(double newNormalizedValue)
{
    T newValue = mTaperDelegate->NormalizedToReal(newNormalizedValue);
    if (mNeedNotify || (mValue != newValue))
    {
        //Set the new value
        mValue = newValue;
                
        //<DMT> Always notify that the value has changed through the automation delegate to guarantee that all control surfaces and other
        // GUIs get their values updated.
        if (mAutomationDelegate)
            mAutomationDelegate->PostCurrentValue(Identifier(), newNormalizedValue);

        // clear flag
        mNeedNotify = false;
    }   
}

template<typename T>
T       AAX_CParameter<T>::GetValue()   const
{
    return mValue;
}


template<typename T>
bool        AAX_CParameter<T>::GetValueAsBool(bool* /*value*/) const
{
    return false;
}
template <>
bool        AAX_CParameter<bool>::GetValueAsBool(bool* value) const;


template<typename T>
bool        AAX_CParameter<T>::GetValueAsInt32(int32_t* /*value*/) const
{
    return false;
}
template<>
bool        AAX_CParameter<int32_t>::GetValueAsInt32(int32_t* value) const;

template<typename T>
bool        AAX_CParameter<T>::GetValueAsFloat(float* /*value*/) const
{
    return false;
}
template<>
bool        AAX_CParameter<float>::GetValueAsFloat(float* value) const;

template<typename T>
bool        AAX_CParameter<T>::GetValueAsDouble(double* /*value*/) const
{
    return false;
}
template<>
bool        AAX_CParameter<double>::GetValueAsDouble(double* value) const;

template<typename T>
bool        AAX_CParameter<T>::GetValueAsString(AAX_IString* /*value*/) const
{
    return false;
}
template<>
bool        AAX_CParameter<AAX_CString>::GetValueAsString(AAX_IString* value) const;

template<typename T>
bool        AAX_CParameter<T>::SetValueWithBool(bool /*value*/)
{
    return false;
}
template<>
bool        AAX_CParameter<bool>::SetValueWithBool(bool value);

template<typename T>
bool        AAX_CParameter<T>::SetValueWithInt32(int32_t /*value*/)
{
    return false;
}
template<>
bool        AAX_CParameter<int32_t>::SetValueWithInt32(int32_t value);

template<typename T>
bool        AAX_CParameter<T>::SetValueWithFloat(float /*value*/)
{
    return false;
}
template<>
bool        AAX_CParameter<float>::SetValueWithFloat(float value);

template<typename T>
bool        AAX_CParameter<T>::SetValueWithDouble(double /*value*/)
{
    return false;
}
template<>
bool        AAX_CParameter<double>::SetValueWithDouble(double value);

template<typename T>
bool        AAX_CParameter<T>::SetValueWithString(const AAX_IString& /*value*/)
{
    return false;
}
template<>
bool        AAX_CParameter<AAX_CString>::SetValueWithString(const AAX_IString& value);

template<typename T>
void    AAX_CParameter<T>::SetNormalizedDefaultValue(double newNormalizedDefault)
{
    T newDefaultValue = mTaperDelegate->NormalizedToReal(newNormalizedDefault);
    SetDefaultValue(newDefaultValue);
}

template<typename T>
double  AAX_CParameter<T>::GetNormalizedDefaultValue() const
{
    double normalizedDefault = mTaperDelegate->RealToNormalized(mDefaultValue);
    return normalizedDefault;
}

template<typename T>
void    AAX_CParameter<T>::SetDefaultValue(T newDefaultValue)
{
    newDefaultValue = mTaperDelegate->ConstrainRealValue(newDefaultValue);
    mDefaultValue = newDefaultValue;
}

template<typename T>
T       AAX_CParameter<T>::GetDefaultValue() const
{
    return mDefaultValue;
}

template<typename T>
void    AAX_CParameter<T>::SetToDefaultValue()
{
    SetValue(mDefaultValue);
}

template<typename T>
void    AAX_CParameter<T>::SetNumberOfSteps(uint32_t numSteps)
{
    mNumSteps = numSteps;
}

template<typename T>
uint32_t    AAX_CParameter<T>::GetNumberOfSteps() const
{
    return mNumSteps;
}

template<typename T>
uint32_t    AAX_CParameter<T>::GetStepValue() const
{
    double  numSteps = (double) this->GetNumberOfSteps ();
    if ( numSteps < 2.0 )
        return 0;
    
    double  value = this->GetNormalizedValue ();
    double  valuePerStep = 1.0 / ( numSteps - 1.0 );
    double  curStep = ( value / valuePerStep ) + 0.5;
    if ( curStep < 0.0 )
        curStep = 0.0;
    else if ( curStep > (double) ( numSteps - 1.0 ) )
        curStep = (double) ( numSteps - 1.0 );
    
    return (uint32_t) curStep;
}

template<typename T>
void    AAX_CParameter<T>::SetStepValue(uint32_t iStep)
{
    double  numSteps = (double) this->GetNumberOfSteps ();
    if ( numSteps < 2.0 )
        return;
    
    double  valuePerStep = 1.0 / ( numSteps - 1.0 );
    double  value = valuePerStep * (double) iStep;
    if ( value < 0.0 )
        value = 0.0;
    else if ( value > 1.0 )
        value = 1.0;

    this->SetNormalizedValue ( value );
}

template<typename T>
void    AAX_CParameter<T>::SetType(AAX_EParameterType iControlType)
{
    mControlType = iControlType;
}

template<typename T>
AAX_EParameterType  AAX_CParameter<T>::GetType() const
{
    return mControlType;
}

template<typename T>
void    AAX_CParameter<T>::SetOrientation(AAX_EParameterOrientation iOrientation)
{
    mOrientation = iOrientation;
}

template<typename T>
AAX_EParameterOrientation   AAX_CParameter<T>::GetOrientation() const
{
    return mOrientation;
}

template<typename T>
void    AAX_CParameter<T>::SetNormalizedValue(double normalizedNewValue)
{
    T newValue = mTaperDelegate->NormalizedToReal(normalizedNewValue);
    SetValue(newValue);
}

template<typename T>
double  AAX_CParameter<T>::GetNormalizedValue() const
{
    T val = GetValue();
    return mTaperDelegate->RealToNormalized(val);
}   


template<typename T>
bool    AAX_CParameter<T>::GetValueString(AAX_CString*  valueString) const
{
    return mDisplayDelegate->ValueToString(GetValue(), valueString);
}

template<typename T>
bool    AAX_CParameter<T>::GetValueString(int32_t /*iMaxNumChars*/, AAX_CString*    valueString) const
{
    return mDisplayDelegate->ValueToString(GetValue(), valueString);
}

template <typename T>
bool    AAX_CParameter<T>::GetNormalizedValueFromString(const AAX_CString&  valueString, double *normalizedValue) const
{
    //First, convert the string to a value using the wrapped parameter's display delegate.
    T value;
    if (!mDisplayDelegate->StringToValue(valueString, &value))
        return false;
    
    //Then use the wrapped parameter's taper delegate to convert to a normalized representation.
    *normalizedValue = mTaperDelegate->RealToNormalized(value);
    
    //If the parameter is out of range, we should probably return false, even though we clamped the normalizedValue already just to be safe.
    if ((value > mTaperDelegate->GetMaximumValue()) || (value < mTaperDelegate->GetMinimumValue()))
        return false;
    
    return true;    
}

template <typename T>
bool    AAX_CParameter<T>::GetStringFromNormalizedValue(double normalizedValue, AAX_CString&    valueString) const
{
    T value = mTaperDelegate->NormalizedToReal(normalizedValue);
    if (!mDisplayDelegate->ValueToString(value, &valueString))
        return false;   
    
    //If the parameter is out of range, we should probably return false, even though we clamped the normalizedValue already just to be safe.
    if ((value > mTaperDelegate->GetMaximumValue()) || (value < mTaperDelegate->GetMinimumValue()))
        return false;   
    return true;
}

template <typename T>
bool    AAX_CParameter<T>::GetStringFromNormalizedValue(double normalizedValue, int32_t iMaxNumChars, AAX_CString&  valueString) const
{
    T value = mTaperDelegate->NormalizedToReal(normalizedValue);
    if (!mDisplayDelegate->ValueToString(value, iMaxNumChars, &valueString))
        return false;   
    
    //If the parameter is out of range, we should probably return false, even though we clamped the normalizedValue already just to be safe.
    if ((value > mTaperDelegate->GetMaximumValue()) || (value < mTaperDelegate->GetMinimumValue()))
        return false;   
    return true;
}

template<typename T>
bool    AAX_CParameter<T>::SetValueFromString(const AAX_CString&    newValueString)
{   
    T newValue;
    if (!mDisplayDelegate->StringToValue(newValueString, &newValue))
        return false;
    SetValue(newValue);
    return true;
}

template<typename T>
void    AAX_CParameter<T>::SetTaperDelegate(AAX_ITaperDelegateBase& taperDelegate,bool iPreserveValue)
{
    double  normalizeValue = this->GetNormalizedValue ();

    AAX_ITaperDelegate<T>* oldDelegate = mTaperDelegate;
    mTaperDelegate = ((AAX_ITaperDelegate<T> &) taperDelegate).Clone();
    delete oldDelegate;

    mNeedNotify = true;
    if ( iPreserveValue )
        this->SetValue ( mValue );
    else this->UpdateNormalizedValue ( normalizeValue );
}

template<typename T>
void    AAX_CParameter<T>::SetDisplayDelegate(AAX_IDisplayDelegateBase& displayDelegate)
{
    AAX_IDisplayDelegate<T>* oldDelegate = mDisplayDelegate;
    mDisplayDelegate = ((AAX_IDisplayDelegate<T> &)displayDelegate).Clone();
    delete oldDelegate;
    
    if (mAutomationDelegate != 0)
        mAutomationDelegate->PostCurrentValue(mIdentifier, this->GetNormalizedValue());     //<DMT> Make sure GUIs are all notified of the change.
}

template<typename T>
const AAX_ITaperDelegate<T>*    AAX_CParameter<T>::TaperDelegate() const
{
    return mTaperDelegate;
}

template<typename T>
const AAX_IDisplayDelegate<T>*  AAX_CParameter<T>::DisplayDelegate() const
{
    return mDisplayDelegate;
}

template<typename T>
bool    AAX_CParameter<T>::Automatable() const          
{   
    return mAutomatable;
}

template<typename T>
void    AAX_CParameter<T>::SetAutomationDelegate ( AAX_IAutomationDelegate * iAutomationDelegate )
{
    //Remove the old automation delegate
    if ( mAutomationDelegate )
    {
        mAutomationDelegate->UnregisterParameter ( mIdentifier );
    }
    
    //Add the new automation delegate, wrapped by the versioning layer.
    mAutomationDelegate = iAutomationDelegate;
    if ( mAutomationDelegate )
        mAutomationDelegate->RegisterParameter ( mIdentifier );
}

template<typename T>
void    AAX_CParameter<T>::Touch()                      
{   
    //<DT>  Always send the touch command, even if the control isn't automatable.
    if (mAutomationDelegate)
        mAutomationDelegate->PostTouchRequest( Identifier() ); 
}               

template<typename T>
void    AAX_CParameter<T>::Release()                    
{   
    //<DT>  Always send the release command, even if the control isn't automatable.
    if (mAutomationDelegate)
        mAutomationDelegate->PostReleaseRequest( Identifier() );
}                   

#endif //AAX_CParameter_H