CH_Tweener.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        CH_Tweener.h (C++)
 *
 * COMMENTS:    Tool for tweening channels in various ways.
 *
 */

#ifndef __CH_Tweener__
#define __CH_Tweener__

#include "CH_API.h"

#include "CH_Types.h"

#include <UT/UT_Function.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_SuperInterval.h>
#include <UT/UT_UniquePtr.h>

class CH_Channel;
class CH_TweenTool;

struct CH_ChannelSelections
{
    CH_ChannelSelections()
        : myChannel(nullptr)
    {}

    CH_ChannelSelections(
            CH_Channel *channel,
            UT_Array<UT_SuperIntervalR> &&ranges)
        : myChannel(channel), myRanges(ranges)
    {
    }

    CH_Channel *myChannel;
    UT_Array<UT_SuperIntervalR> myRanges;

    /// Can be set by the component providing current channel selections
    /// to update its UI during the tween.
    /// Parameters:
    /// const UT_Array<UT_SuperIntervalR>& intervals -- selected intervals
    /// bool first -- true if the tween is starting. The first UI update
    /// bool last -- true if the tween is ending. This is the last UI update
    UT_Function<void(const UT_Array<UT_SuperIntervalR>&, bool, bool)>
        myUpdateUICallback;
};

// Informs UT_Array that CH_ChannelSelections is not safe for trivial relocation
// due to the UT_Function
SYS_DECLARE_IS_NOT_TR(CH_ChannelSelections);

class CH_API CH_Tweener
{
public:
    CH_Tweener();

    ~CH_Tweener();

    UT_NON_COPYABLE(CH_Tweener);

    // Add channel and selection ranges for that channel
    // Used for the methods that tween sequences of existing keys
    void setChannels(UT_Array<CH_ChannelSelections> &&channels);

    // Set channels only, used for the methods that blend a pose at the current
    // time.
    void setChannels(const CH_ChannelList &channels);

    // Clears the channel list, setting it to all scoped channels
    void setChannelsFromScopedChannels();

    // Clear all channels and ranges
    void clear();

    /// Perform a tween on all channels currently added to the Tweener
    /// @param first Starts a new tween, creating a new undo block and  caching
    ///              any relevant data for the given tween mode. For instance,
    ///              blending tween modes need to cache the current values of
    ///              the keys.
    /// @param last  Finishes a tween, closing undo blocks. This MUST be called
    ///              when finishing a tween
    void tween(
            CH_TweenMode mode,
            fpreal val,
            bool first = false,
            bool last = false);

    int getNumModes() { return static_cast<int>(CH_TweenMode::Count); }

    /// Set the eval times used by the blend to frame mode.
    void setLeftBlendTime(fpreal t) { myLeftBlendTime = t; };
    void setRightBlendTime(fpreal t) { myRightBlendTime = t; };
    void setBlendTimes(fpreal left, fpreal right)
    {
        setLeftBlendTime(left);
        setRightBlendTime(right);
    };

    void getBlendTimes(fpreal &left, fpreal &right) const
    {
        left = myLeftBlendTime;
        right = myRightBlendTime;
    }

    /// Returns the name of the tween mode in a format suitable to display.
    /// eg CH_TweenMode::BlendToNeighbor -> "Blend To Neighbor"
    UT_StringHolder getModeName(CH_TweenMode mode) const;
    UT_StringHolder getModeAbbreviation(CH_TweenMode mode) const;
    /// Returns a simple, all lowercase token unique to each tween mode
    /// Used by the playbar to generate unique UI_Value names for each tween
    /// Mode.
    UT_StringHolder getModeToken(CH_TweenMode mode) const;
    /// Given the mode token, return the CH_TweenMode enum value.
    /// If there is no such mode, returns CH_TweenMode::Count
    CH_TweenMode getMode(const UT_StringHolder &token) const;

    bool getOvershootSupported(CH_TweenMode mode) const;
    // Returns whether we need to save the entire channel for undo or
    // if we just need to save the keys that already exist.
    bool getRequiresFullChannelUndo(CH_TweenMode mode) const;
    CH_TweenToolType getToolType(CH_TweenMode mode) const;

private:
    void startTween(CH_TweenMode mode);
    void endTween();

    UT_Array<CH_ChannelSelections> myChannels;

    // Eval Times to use when using the blend to frame mode
    fpreal myLeftBlendTime;
    fpreal myRightBlendTime;

    int myUndo;

    // The tween being currently evaluated. Set when starting a new tween
    // based on the mode.
    UT_UniquePtr<CH_TweenTool> myCurrentTween;

    int myUndoEventHandlerLevel;
};

#endif