xref: /NW4C-2.0.3/include/nw/snd/snd_FxReverb.h

/*---------------------------------------------------------------------------*
  Project:  NintendoWare
  File:     snd_FxReverb.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: $
 *---------------------------------------------------------------------------*/

/**
 * :include nw/snd/snd_FxReverb.h
 *
 * @file snd_FxReverb.h
 */

#ifndef NW_SND_FX_REVERB_H_
#define NW_SND_FX_REVERB_H_

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

namespace nw {
namespace snd {

//---------------------------------------------------------------------------
//! @brief    リバーブエフェクトクラスです。
//!
//!           エフェクトの使用方法については、@ref SoundSystem
//!           クラスを参照してください。
//!
//!           エフェクトは CPU で処理されます (DSP では処理されません)。
//!
//! @see SoundSystem クラス
//! @see FxBase クラス
//!
//! @date 2010/08/25 エフェクトが CPU で処理される旨、追記
//! @date 2010/07/07 @ref GetParam 追加
//! @date 2010/06/17 初版
//---------------------------------------------------------------------------
class FxReverb : public FxBase
{
public:

    //---------------------------------------------------------------------------
    //! @brief  フィルタサイズを表現する構造体です。
    //!
    //!         m_Comb0 および m_Comb1 は、後置残響音
    //!         (詳しくは @ref Param の説明をご覧ください) にかかる
    //!         「くし型フィルタ」のサイズを表します。
    //!         この値を小さくすると、特定の周波数だけ際立った金属的な音になります。
    //!         m_Comb0 の初期値は 19 * 160、
    //!         m_Comb1 の初期値は 23 * 160 です。
    //!
    //!         m_AllPass は、後置残響音にかかる全域通過フィルタのサイズ (ディレイ長) を表します。
    //!         この値を大きくすると、後置残響音をきめ細かくすることができます。
    //!         初期値は 13 * 160 です。
    //!
    //!         160 は 1 オーディオフレーム (約 5 msec) で処理するサンプル数に由来します。
    //!         初期値で設定されているように 19, 23, 13 など、
    //!         「互いに素」な値を設定することが望ましいです。
    //!         互いに素な値に設定しないと、リバーブ音に周期性が出やすくなります。
    //!
    //!         エフェクト実行中にこれらの値を変更すると、
    //!         ノイズがのる可能性があります。
    //!
    //!         m_Comb0, m_Comb1, m_AllPath は、0 より大きな値を設定する必要があります。
    //!         0 を指定して @ref SetParam 関数を呼び出すと、
    //!         Debug 版 / Development 版ではアサートで停止します。
    //!         Release 版では @ref SetParam 関数は false を返します。
    //!
    //! @date 2011/02/01 各変数の最小値について説明追加
    //! @date 2010/10/14 各変数について説明追加
    //! @date 2010/09/30 コンストラクタの追加
    //! @date 2010/09/08 スペルミス修正 (m_AllPath → m_AllPass)
    //! @date 2010/06/17 初版
    //---------------------------------------------------------------------------
    struct FilterSize
    {
        u32  m_Comb0;    //!< くし型フィルタ 0 のサイズです。
        u32  m_Comb1;    //!< くし型フィルタ 1 のサイズです。
        u32  m_AllPass;  //!< 全域通過フィルタのサイズです。

        //---------------------------------------------------------------------------
        //! @brief    コンストラクタです。
        //!
        //! @date 2010/09/30 初版
        //---------------------------------------------------------------------------
        FilterSize()
        : m_Comb0( 19 * NN_SND_SAMPLES_PER_FRAME ),
          m_Comb1( 23 * NN_SND_SAMPLES_PER_FRAME ),
          m_AllPass( 13 * NN_SND_SAMPLES_PER_FRAME )
        {}
    };

    //---------------------------------------------------------------------------
    //! @brief  リバーブパラメータの構造体です。
    //!
    //!         リバーブは大きく「初期反射音」と「後置残響音」とに分けて考えられます。
    //!
    //!         「初期反射音」は m_EarlyReflectionTime および m_EarlyGain で
    //!         調整することができます。
    //!
    //!         m_EarlyReflectionTime は初期反射音が返ってくるまでの時間を表します。
    //!         この値が大きければ大きいほど、音が反射して返ってくるまでの時間が長くなります。
    //!         単位は msec で、5 以上かつ 5 の倍数を設定する必要があります。
    //!         初期値は 60 に設定されています。
    //!
    //!         m_EarlyGain は初期反射音の出力ゲインを表します。
    //!         0.0f ～ 1.0f で設定します。
    //!         0.0f にすると初期反射音が聞こえなくなります。
    //!         初期値は 0.6f に設定されています。
    //!
    //!         「後置残響音」は m_FusedTime, m_FusedGain, m_PreDelayTime,
    //!         m_Coloration, m_Damping, m_pFilterSize で調整することができます。
    //!
    //!         m_FusedTime は後置残響音が鳴り続ける時間を表します。
    //!         この値を大きくすると、音が反射しやすい空間を表現することができます。
    //!         単位は msec で、初期値は 4000 に設定されています。
    //!
    //!         m_FusedGain は後置残響音の出力ゲインを表します。
    //!         0.0f ～ 1.0f で設定します。
    //!         0.0f にすると後置残響音が聞こえなくなります。
    //!         初期値は 0.4f に設定されています。
    //!
    //!         m_PreDelayTime は、後置残響音の前に置かれる遅延時間を表します。
    //!         この値が大きければ大きいほど、後置残響音が遅れて聞こえるようになります。
    //!         単位は msec で、5 以上かつ 5 の倍数で設定する必要があります。
    //!         初期値は 100 です。
    //!
    //!         m_Coloration は後置残響音の全域通過フィルタの係数を表します。
    //!         この値を大きくすると後置残響音がきめ細かくなり、
    //!         より複雑な残響が混じるようなります。
    //!         0.0f ～ 1.0f で設定します。
    //!         0.0f にすると全域通過フィルタはスルーされます。
    //!         初期値は 0.5f です。
    //!
    //!         m_Damping は後置残響音に対する LPF (ローパスフィルタ) のかかり具合を表します。
    //!         0.0f ～ 1.0f で設定します。
    //!         この値を大きくすればするほど、カットオフ周波数が下がっていきます。
    //!         0.0f にすると、LPF はかかりません。
    //!         初期値は 0.4f です。
    //!
    //!         m_pFilterSize の各メンバ変数については、@ref FilterSize の説明をご覧ください。
    //!
    //!         m_IsEnableSurround は、
    //!         リバーブ処理をサラウンドチャンネルも有効にするかどうかを表します。
    //!         true の場合、サラウンド (リアの L と R) 成分もリバーブ処理されます。
    //!         false の場合は、サラウンド成分のリバーブ処理はスキップされます。
    //!         false にすると、その分処理負荷を減らすことができます。
    //!         初期値は false です。
    //!
    //!         @ref GetRequiredMemSize で取得できる必要メモリサイズは、@n
    //!         ・m_EarlyReflectionTime @n
    //!         ・m_PreDelayTime @n
    //!         ・m_pFilterSize @n
    //!         ・m_IsEnableSurround @n
    //!         に依存します。
    //!
    //!         エフェクト実行中に次の値を変更すると、ノイズがのる可能性があります。@n
    //!         ・m_EarlyReflectionTime @n
    //!         ・m_PreDelayTime
    //!
    //!         また、次の値はエフェクト実行中であっても、「連続的に」変化させる場合は、
    //!         ノイズはのりません。@n
    //!         ・m_FusedTime @n
    //!         ・m_Coloration @n
    //!         ・m_Damping @n
    //!         ・m_EarlyGain @n
    //!         ・m_FusedGain
    //!
    //!         エフェクト実行中にパラメータを変更する場合は、@ref SetParam を呼び出してください。
    //!
    //! @date 2010/10/28 誤記修正 (メンバ変数 m_pFilterSize の説明「初期値値」→「初期値」)
    //! @date 2010/10/14 各変数について説明追加
    //! @date 2010/09/30 初期値、必要メモリサイズについて追記
    //! @date 2010/07/22 m_IsEnableSurround の追加
    //! @date 2010/07/07 m_PreDelayTime の単位が msec であることを明記
    //! @date 2010/06/17 初版
    //---------------------------------------------------------------------------
    struct Param
    {
        u32 m_EarlyReflectionTime;  //!< 初期反射時間 (msec) です。
        u32 m_FusedTime;            //!< 後置残響音の減衰時間 (msec) です。
        u32 m_PreDelayTime;         //!< 後置残響音のプリディレイ時間 (msec) です。
        f32 m_Coloration;           //!< 後置残響音の全域通過フィルタの係数です。
        f32 m_Damping;              //!< 後置残響音の LPF のかかり具合です。

        //! フィルタサイズです。NULL を指定すると、FilterSize 構造体の初期値が設定されます。
        FilterSize* m_pFilterSize;

        f32 m_EarlyGain;            //!< 初期反射音の出力ゲインです。
        f32 m_FusedGain;            //!< 後置残響音の出力ゲインです。

        //! リバーブ処理をサラウンドチャンネルも有効にするかどうかのフラグです。
        bool m_IsEnableSurround;

        //---------------------------------------------------------------------------
        //! @brief    コンストラクタです。
        //!
        //! @date 2010/06/17 初版
        //---------------------------------------------------------------------------
        Param()
        : m_EarlyReflectionTime( 60 ),  // msec
          m_FusedTime( 4000 ),          // msec
          m_PreDelayTime( 100 ),        // msec
          m_Coloration( 0.5f ),
          m_Damping( 0.4f ),
          m_pFilterSize( &s_DefaultFilterSize ),
          m_EarlyGain( 0.6f ),
          m_FusedGain( 0.4f ),
          m_IsEnableSurround( false )
        {}
    };

    //----------------------------------------
    //! @name コンストラクタ / デストラクタ
    //@{
    //---------------------------------------------------------------------------
    //! @brief    コンストラクタです。
    //!
    //! @date 2010/06/17 初版
    //---------------------------------------------------------------------------
    FxReverb();

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

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

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

    //---------------------------------------------------------------------------
    //! @brief  リバーブパラメータを取得します。
    //!
    //! @return   現在のリバーブパラメータを返します。
    //!
    //! @see SetParam
    //!
    //! @date 2010/07/07 初版
    //---------------------------------------------------------------------------
    const Param& GetParam() const
    {
        return m_Param;
    }
    //@}


    //----------------------------------------
    //! @name メモリ割り当て
    //@{

    //---------------------------------------------------------------------------
    //! @brief    エフェクトに必要なメモリサイズを取得します。
    //!
    //!           あらかじめ @ref SetParam 関数で、
    //!           リバーブパラメータを設定しておく必要があります。
    //!
    //! @return   リバーブエフェクトに必要なメモリサイズを返します。
    //!
    //! @see AssignWorkBuffer
    //!
    //! @date 2010/06/17 初版
    //---------------------------------------------------------------------------
    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/06/17 初版
    //---------------------------------------------------------------------------
    bool AssignWorkBuffer( uptr buffer, size_t size );

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

private:
    struct WorkBuffer
    {
        s32*  m_EarlyReflection[4]; // 初期反射用
        s32*  m_PreDelay[4];        // プリディレイ用
        s32*  m_CombFilter[4][2];   // くし型フィルタ用（２段）
        s32*  m_AllPassFilter[4];   // 全域通過フィルタ用（１段）
        s32   m_Lpf[4];             // LPF用
    };

    static FilterSize s_DefaultFilterSize;

    void AllocBuffer();
    void FreeBuffer();

    void InitializeParam();

    Param           m_Param;
    uptr            m_pBuffer;
    size_t          m_BufferSize;
    FilterSize      m_FilterSize;
    WorkBuffer      m_WorkBuffer;

    s32  m_EarlyLength;
    s32  m_EarlyPos;

    s32  m_PreDelayLength;
    s32  m_PreDelayPos;

    s32  m_CombFilterLength[2];
    s32  m_CombFilterPos[2];
    s32  m_CombFilterCoef[2];

    s32  m_AllPassFilterLength;
    s32  m_AllPassFilterPos;
    s32  m_AllPassFilterCoef;

    s32  m_LastLpfOut[4];


    // 以下のパラメータは、InitializeParam() で算出されるように変更
    s32 m_EarlyGain;
    s32 m_FusedGain;
    s32 m_LpfCoef1;
    s32 m_LpfCoef2;

    u32 m_EarlyReflectionTimeAtInitialize;
    u32 m_PreDelayTimeAtInitialize;
    FilterSize m_FilterSizeAtInitialize;
    bool m_IsEnableSurroundAtInitialize;

    u8   m_ProcessChannelCount;
    bool m_IsActive;
};



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


#endif /* NW_SND_FX_REVERB_H_ */