/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     snd_FxDelay.h

  Copyright (C)2009 Nintendo Co., Ltd.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: $
 *---------------------------------------------------------------------------*/

#ifndef NN_SND_FX_DELAY_H_
#define NN_SND_FX_DELAY_H_

#ifdef __cplusplus

namespace nn  { namespace snd { namespace CTR {

//---------------------------------------------------------------------------
//! @brief  ディレイエフェクトクラスです。
//!
//!         エフェクトを実行するには、@ref SetEffect 関数を呼び出してください。
//!
//!         エフェクトは CPU で処理されます (DSP では処理されません)。
//!
//!         @ref Param 構造体の m_IsEnableSurround フラグを利用することで、
//!         前方 2ch のみのエフェクトか、
//!         後方 2ch を含めた計 4ch のエフェクト処理かを選ぶことができます。
//!
//! @see FxReverb クラス
//!
//! @date 2010/10/20 初版
//---------------------------------------------------------------------------
class FxDelay
{
public:
    //---------------------------------------------------------------------------
    //! @brief  ディレイパラメータの構造体です。
    //!
    //!         m_DelayTime はディレイ時間を表します。
    //!         単位は msec です。
    //!         この値を大きくすればするほど、反響が遅れてやって来ます。
    //!         また、この値を大きくすると @ref GetRequiredMemSize
    //!         で得られる必要メモリサイズが大きくなります。
    //!         初期値は 250 です。
    //!
    //!         m_FeedbackGain をディレイ音のフィードバックゲインを表します。
    //!         0.0f ～ 1.0f で設定する必要があります。
    //!         この値を大きくすればするほど、ディレイ音がなかなか消えなくなります。
    //!         0.0f を指定すると、ワンショットディレイ (フィードバックなし) になります。
    //!         初期値は 0.4f です。
    //!
    //!         m_Damping は LPF (ローパスフィルタ) のかかり具合を表します。
    //!         0.0f ～ 1.0f で設定する必要があります。
    //!         この値を大きくすればするほど、カットオフ周波数が下がっていきます。
    //!         0.0f にすると、ローパスフィルタはかかりません。
    //!         初期値は 0.5f です。
    //!
    //!         m_IsEnableSurround が true の場合、サラウンド (リアの L と R)
    //!         成分もディレイ処理されます。
    //!         false の場合は、サラウンド成分のディレイ処理はスキップされ、
    //!         その分処理負荷が減ります。
    //!         一方、true にすると、処理負荷は増え、
    //!         @ref GetRequiredMemSize で得られる必要メモリサイズも大きくなります。
    //!
    //!         エフェクト実行中に m_DelayTime を変更すると、ノイズがのる可能性があります。
    //!
    //!         また、m_FeedbackGain および m_Damping は、
    //!         エフェクト実行中であっても「連続的に」変化させる場合は、
    //!         ノイズはのりません。
    //!
    //!         エフェクト実行中にパラメータ変更をするには、@ref SetParam を呼び出してください。
    //!         
    //! @date 2010/10/21 初期値を変更
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    struct Param
    {
        //! ディレイ時間 (msec) です。初期値は 250 です。
        u32 m_DelayTime;

        //! フィードバックゲインです。0.0f ～ 1.0f で指定します。初期値は 0.4f です。
        f32 m_FeedbackGain;  

        //! LPF のかかり具合です。0.0f ～ 1.0f で指定します。初期値は 0.5f です。
        f32 m_Damping;

        //! ディレイ処理をサラウンドチャンネルも有効にするかどうかのフラグです。初期値は false です。
        bool m_IsEnableSurround;

        NN_PADDING3;
        
        //---------------------------------------------------------------------------
        //! @brief    コンストラクタです。
        //!
        //! @date 2010/10/21 初期値を変更
        //! @date 2010/10/20 初版
        //---------------------------------------------------------------------------
        Param()
        : m_DelayTime( 250 ),
          m_FeedbackGain( 0.4f ),
          m_Damping( 0.5f ),
          m_IsEnableSurround( false )
          {}
    };

    //----------------------------------------------------------------
    /// @name   コンストラクタ／デストラクタ
    //----------------------------------------------------------------
    //@{
    //---------------------------------------------------------------------------
    //! @brief    コンストラクタです。
    //!
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    FxDelay();

    //---------------------------------------------------------------------------
    //! @brief    デストラクタです。
    //!
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    virtual ~FxDelay();
    //@}

    //----------------------------------------------------------------
    /// @name   パラメータ設定／取得
    //----------------------------------------------------------------
    //@{
    //---------------------------------------------------------------------------
    //! @brief  ディレイパラメータを設定します。
    //!
    //!         @ref GetRequiredMemSize 関数は、
    //!         ここで設定されたディレイパラメータを元に必要なメモリサイズを計算します。
    //!
    //!         設定された @ref Param 構造体は、FxDelay インスタンス内部でコピーされます。
    //!
    //!         FxDelay インスタンスを @ref SetEffect 関数に渡す前と後で挙動が変わります。
    //!
    //!         @ref SetEffect を呼び出す前は、
    //!         @ref Param 構造体のうち、m_FeedbackGain および m_Damping
    //!         の範囲チェックが行われます。
    //!         範囲外の場合は、Debug / Development 版ではアサートで停止し、
    //!         Release 版では false を返します。
    //!         
    //!         @ref SetEffect 呼び出し後は、
    //!         呼び出し前に行われる範囲チェックに加え、
    //!         必要メモリサイズが増えるかどうかのチェックが行われます。
    //!         すなわち、@n
    //!         ・m_DelayTime に @ref SetEffect が呼び出された時より大きな値を設定する @n
    //!         ・m_IsEnableSurround が @ref SetEffect 呼び出し時には false を設定していたのに
    //!         true を設定する @n
    //!         のような操作をした場合、本関数は失敗し false を返します。
    //!         上記の条件を満たさない場合は、
    //!         @ref SetEffect 以降でもパラメータの変更が可能です。
    //!
    //! @param[in] param  ディレイパラメータです。
    //!
    //! @return     設定に成功すると true を、失敗 (範囲外の値を設定するなど) した場合は
    //!             false を返します
    //!
    //! @see GetRequiredMemSize
    //! @see GetParam
    //! @see SetEffect
    //!
    //! @date 2010/11/04 関数名誤記修正 (Initialize → SetEffect)
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    bool SetParam( const FxDelay::Param& param );
    
    //---------------------------------------------------------------------------
    //! @brief  ディレイパラメータを取得します。
    //!
    //! @return   現在のディレイパラメータを返します。
    //!
    //! @see SetParam
    //!
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    const Param& GetParam() const
    {
        return m_Param;
    }
    //@}
    
    //----------------------------------------
    //! @name メモリ割り当て
    //@{
    //---------------------------------------------------------------------------
    //! @brief    エフェクトに必要なメモリサイズを取得します。
    //!
    //!           あらかじめ @ref SetParam 関数で、
    //!           ディレイパラメータを設定しておく必要があります。
    //!
    //! @return   ディレイエフェクトに必要なメモリサイズを返します。
    //!
    //! @see AssignWorkBuffer
    //!
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    size_t GetRequiredMemSize();
     
    //---------------------------------------------------------------------------
    //! @brief    エフェクトで使用するメモリ領域を割り当てます。
    //!
    //!           メモリ領域の割り当ては、エフェクトを
    //!           @ref SetEffect 関数に渡す前に行う必要があります。
    //!
    //!           エフェクトが必要とするバッファサイズは、パラメータの値によって変化しますので、
    //!           @ref GetRequiredMemSize を呼び出して、必要なメモリサイズを取得してください。
    //!
    //! @param[in] buffer 割り当てるメモリの先頭アドレスです。
    //! @param[in] size   割り当てるメモリのサイズです。
    //!
    //! @return   メモリ領域の割り当てに成功すると true を、
    //!           失敗すると false を返します。
    //!
    //! @see GetRequiredMemSize
    //! @see ReleaseWorkBuffer
    //! @see SetEffect
    //!
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    bool AssignWorkBuffer( uptr buffer, size_t size );
    
    //---------------------------------------------------------------------------
    //! @brief    エフェクトで使用していたメモリ領域を解放します。
    //!
    //!           この関数で解放を行う前に、@ref ClearEffect
    //!           関数でエフェクトを削除しておく必要があります。
    //!
    //! @see AssignWorkBuffer
    //! @see ClearEffect
    //!
    //! @date 2010/11/04 誤植修正 (開放→解放)
    //! @date 2010/10/20 初版
    //---------------------------------------------------------------------------
    void ReleaseWorkBuffer();
    //@}

    /*! :private */
    bool Initialize();

    /*! :private */
    void Finalize();

    /*! :private */
    void UpdateBuffer( uptr data );


private:
    struct WorkBuffer
    {
        s32* m_Delay[4];      ///< ディレイ
        s32  m_Lpf[4];        ///< one-pole LPF の履歴
    };
    
    void AllocBuffer();
    void FreeBuffer();
    void InitializeParam();
    
    Param   m_Param;
    uptr    m_Buffer;            ///< バッファ
    size_t  m_BufferSize;        ///< バッファサイズ
    
    WorkBuffer  m_WorkBuffer;    ///< ワークバッファ
    
    u32     m_DelayFrames;       ///< ディレイフレーム数（オーディオフレームが幾つ分か）
    u32     m_CurFrame;          ///< 現在のフレーム
    
    s32     m_FeedbackGain;      ///< フィードバックゲイン
    s32     m_LpfCoef1;          ///< LPF係数1
    s32     m_LpfCoef2;          ///< LPF係数2
    
    u32     m_DelayTimeAtInitialize;
    bool    m_IsEnableSurroundAtInitialize;

    u8      m_ProcessChannelCount;
    bool    m_IsActive;          ///< アクティブか？

    NN_PADDING1;
};

}}} // namespace nn::snd::CTR

#endif // __cplusplus

#endif /* NN_SND_FX_DELAY_H_ */