nw/snd/snd_FxDelay.h

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

  Copyright (C)2009-2011 Nintendo/HAL Laboratory, Inc.  All rights reserved.

  These coded instructions, statements, and computer programs contain proprietary
  information of Nintendo and/or its licensed developers and are protected by
  national and international copyright laws. 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.

  The content herein is highly confidential and should be handled accordingly.

  $Revision: $
 *---------------------------------------------------------------------------*/

#ifndef NW_SND_FX_DELAY_H_
#define NW_SND_FX_DELAY_H_

#include <nn/types.h>
#include <nw/snd/snd_FxBase.h>

// #define NW_SND_FX_DELAY_CALC_LOAD

namespace nw {
namespace snd {

//---------------------------------------------------------------------------
//! @brief    ディレイエフェクトクラスです。
//!
//!           エフェクトの使用方法については、@ref SoundSystem
//!           クラスを参照してください。
//!
//!           エフェクトは CPU で処理されます (DSP では処理されません)。
//!
//! @see SoundSystem クラス
//! @see FxBase クラス
//!
//! @date 2010/09/03 初版
//---------------------------------------------------------------------------
class FxDelay : public FxBase
{
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/14 各変数について説明追加
    //! @date 2010/09/30 必要メモリサイズについて追記
    //! @date 2010/09/06 初版
    //---------------------------------------------------------------------------
    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;

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

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

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

    //----------------------------------------------------------------
    /// @name   エフェクト
    //----------------------------------------------------------------
    //@{
    virtual bool Initialize();
    virtual void Finalize();
    virtual void UpdateBuffer(
        int numChannels,
        nn::snd::AuxBusData* data,
        s32 sampleLength,
        nw::snd::SampleFormat format,
        f32 sampleRate,
        nw::snd::OutputMode mode );

    //---------------------------------------------------------------------------
    //! @brief  ディレイパラメータを設定します。
    //!
    //!         @ref GetRequiredMemSize 関数は、
    //!         ここで設定されたディレイパラメータを元に必要なメモリサイズを計算します。
    //!
    //!         設定された @ref Param 構造体は、FxDelay インスタンス内部でコピーされます。
    //!
    //!         @ref SoundSystem::AppendEffect を呼び出して
    //!         FxDelay インスタンスを渡す前と後で挙動が変わります。
    //!
    //!         @ref SoundSystem::AppendEffect 呼び出し前は、
    //!         @ref Param 構造体のうち、m_FeedbackGain および m_Damping
    //!         の範囲チェックが行われます。
    //!         範囲外の場合は、Debug / Development 版ではアサートで停止し、
    //!         Release 版では false を返します。
    //!
    //!         @ref SoundSystem::AppendEffect 呼び出し後は、
    //!         呼び出し前に行われる範囲チェックに加え、
    //!         必要メモリサイズが増えるかどうかのチェックが行われます。
    //!         すなわち、@n
    //!         ・m_DelayTime に @ref Initialize が呼び出された時より大きな値を設定する @n
    //!         ・m_IsEnableSurround が @ref Initialize 呼び出し時には false を設定していたのに
    //!         true を設定する @n
    //!         のような操作をした場合、本関数は失敗し false を返します。
    //!         上記の条件を満たさない場合は、
    //!         @ref SoundSystem::AppendEffect 以降でもパラメータの変更が可能です。
    //!
    //! @param[in] param  ディレイパラメータです。
    //!
    //! @return     設定に成功すると true を、失敗 (範囲外の値を設定するなど) した場合は
    //!             false を返します
    //!
    //! @see GetRequiredMemSize
    //! @see GetParam
    //! @see SoundSystem::AppendEffect
    //!
    //! @date 2010/09/30 SoundSystem::AppendEffect 前後の挙動を追記
    //! @date 2010/09/03 初版
    //---------------------------------------------------------------------------
    bool SetParam( const FxDelay::Param& param );

    //---------------------------------------------------------------------------
    //! @brief  ディレイパラメータを取得します。
    //!
    //! @return   現在のディレイパラメータを返します。
    //!
    //! @see SetParam
    //!
    //! @date 2010/09/14 初版
    //---------------------------------------------------------------------------
    const Param& GetParam() const
    {
        return m_Param;
    }
    //@}

    //----------------------------------------
    //! @name メモリ割り当て
    //@{
    //---------------------------------------------------------------------------
    //! @brief    エフェクトに必要なメモリサイズを取得します。
    //!
    //!           あらかじめ @ref SetParam 関数で、
    //!           ディレイパラメータを設定しておく必要があります。
    //!
    //! @return   ディレイエフェクトに必要なメモリサイズを返します。
    //!
    //! @see AssignWorkBuffer
    //!
    //! @date 2010/09/03 初版
    //---------------------------------------------------------------------------
    size_t GetRequiredMemSize();

    //---------------------------------------------------------------------------
    //! @brief    エフェクトで使用するメモリ領域を割り当てます。
    //!
    //!           メモリ領域の割り当ては、エフェクトを
    //!           @ref SoundSystem::AppendEffect 関数で追加する前に行う必要があります。
    //!
    //!           エフェクトが必要とするバッファサイズは、パラメータの値によって変化しますので、
    //!           @ref GetRequiredMemSize を呼び出して、必要なメモリサイズを取得してください。
    //!
    //! @param[in] buffer 割り当てるメモリの先頭アドレスです。
    //! @param[in] size   割り当てるメモリのサイズです。
    //!
    //! @return   メモリ領域の割り当てに成功すると true を、
    //!           失敗すると false を返します。
    //!
    //! @see GetRequiredMemSize
    //! @see ReleaseWorkBuffer
    //! @see SoundSystem::AppendEffect
    //!
    //! @date 2010/09/03 初版
    //---------------------------------------------------------------------------
    bool AssignWorkBuffer( uptr buffer, size_t size );

    //---------------------------------------------------------------------------
    //! @brief    エフェクトで使用していたメモリ領域を解放します。
    //!
    //!           この関数で開放を行う前に、@ref SoundSystem::ClearEffect
    //!           関数でエフェクトを削除しておく必要があります。
    //!
    //! @see AssignWorkBuffer
    //! @see SoundSystem::ClearEffect
    //!
    //! @date 2010/09/03 初版
    //---------------------------------------------------------------------------
    void ReleaseWorkBuffer();
    //@}


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_pBuffer;           ///< バッファ
    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;          ///< アクティブか？


#ifdef NW_SND_FX_DELAY_CALC_LOAD
public:
    static f32 GetLoad();

private:
    static s64 s_FxLoad;
    static s32 s_SampleLength;
    static f32 s_SampleRate;
#endif
};

} // namespace nw::snd
} // namespace nw


#endif /* NW_SND_FX_DELAY_H_ */