/*---------------------------------------------------------------------------*
  Project:  NintendoWare
  File:     snd_Sound3DEngine.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_Sound3DEngine.h
 *
 * @file snd_Sound3DEngine.h
 */

#ifndef NW_SND_SOUND_3D_ENGINE_H_
#define NW_SND_SOUND_3D_ENGINE_H_

#include <nw/snd/snd_Sound3DManager.h>
#include <nw/snd/snd_Sound3DCalculator.h>

namespace nw {
namespace snd {

//---------------------------------------------------------------------------
//! @brief    3D サウンドのパラメータ演算エンジンクラスです。
//!
//!           3D サウンドアクターや 3D サウンドリスナーの位置情報などから、
//!           サウンドに設定する音量やパンなどの各種パラメータを計算します。
//!           このクラスでは、3D サウンドの標準的なパラメータ計算が定義されています。
//!
//!           3D サウンドマネージャーには、初期状態でこのクラスのインスタンスが登録されています。
//!
//!           3D サウンドエンジンをカスタマイズしたい場合、
//!           このクラスを継承して独自のエンジンクラスを作成することができます。
//!           カスタマイズしたエンジンクラスは、
//!           @ref Sound3DManager::SetEngine で 3D サウンドマネージャーに登録し、
//!           デフォルトのエンジンクラスの代わりに使用することができます。 
//!
//! @see Sound3DManager クラス
//! @see Sound3DManager::SetEngine
//!
//! @date 2010/03/12 初版
//---------------------------------------------------------------------------
class Sound3DEngine : public internal::ISound3DEngine
{
public:

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

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


    //! @name 設定
    //@{
    //---------------------------------------------------------------------------
    //! @brief    パン計算用パラメータ構造体を設定します。
    //!
    //!           設定したパラメータは、3D サウンドエンジン内のパン計算の際に使用されます。 
    //!
    //! @param[in] calcPanParam   パン計算用パラメータ構造体です。
    //!
    //! @see Sound3DCalculator::CalcPanParam 構造体
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    void SetCalcPanParam( const Sound3DCalculator::CalcPanParam& calcPanParam )
    {
        m_CalcPanParam = calcPanParam;
    }

    //---------------------------------------------------------------------------
    //! @brief    現在設定されているパン計算用パラメータ構造体を取得します。 
    //!
    //! @return   パン計算用パラメータ構造体を返します。
    //!
    //! @see Sound3DCalculator::CalcPanParam 構造体
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    const Sound3DCalculator::CalcPanParam& GetCalcPanParam() const
    {
        return m_CalcPanParam;
    }
    //@}

protected:
    //---------------------------------------------------------------------------
    //! @brief    UpdateAmbientParam で音量計算をする必要があることを示すフラグです。
    //!
    //! @see UpdateAmbientParam
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_VOLUME      = ( 1 << 0 );

    //---------------------------------------------------------------------------
    //! @brief    UpdateAmbientParam でプライオリティ計算をする必要があることを示すフラグです。
    //!
    //! @see UpdateAmbientParam
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_PRIORITY    = ( 1 << 1 );

    //---------------------------------------------------------------------------
    //! @brief    UpdateAmbientParam でパン計算をする必要があることを示すフラグです。
    //!
    //! @see UpdateAmbientParam
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_PAN         = ( 1 << 2 );

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    UpdateAmbientParam でサラウンドパン計算をする必要があることを示すフラグです。
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_SPAN        = ( 1 << 3 );

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    UpdateAmbientParam で
    //!           biquad フィルタのかかり具合を計算する必要があることを示すフラグです。
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_FILTER      = ( 1 << 4 );

    //---------------------------------------------------------------------------
    //! @brief    UpdateAmbientParam でピッチ計算をする必要があることを示すフラグです。
    //!
    //! @see UpdateAmbientParam
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_PITCH       = ( 1 << 5 );

    //---------------------------------------------------------------------------
    //! @brief    サウンド開始前のプライオリティ計算のために
    //!           UpdateAmbientParam が呼ばれた事を示すフラグです。
    //!
    //! @see UpdateAmbientParam
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    static const u32 UPDATE_START_PRIORITY = ( 1 << 24 );

    //! @name パラメータ
    //@{
    //---------------------------------------------------------------------------
    //! @brief    3D サウンドのパラメータ演算を行う関数です。
    //!
    //!           この関数はサウンドの開始時とサウンドの毎フレームの更新で呼び出されます。
    //!
    //!           カスタマイズした 3D サウンドエンジンクラスを作成する場合、
    //!           この関数をオーバーライドして、 ambientParam にパラメータ演算の結果を格納します。
    //!           格納された値は、毎フレームのサウンド処理に反映されます。
    //!
    //!           パラメータ計算には、3D サウンドリスナーや 3D サウンドアクターの情報を使用します。
    //!           3D サウンドリスナーは、sound3DManager から取得できます。
    //!           また、sound3DParam は計算に使用するパラメータの構造体で、
    //!           アクターの座標などや、サウンドごとの 3D サウンド設定を含みます。
    //!
    //!           updateFlag は、どのパラメータを計算する必要があるかを示したビットフラグです。
    //!           ambientParam 構造体内の、
    //!           各フラグに対応したパラメータがサウンドに対して反映されます。
    //!           フラグがたっていないパラメータを更新した場合の動作は不定です。 
    //!
    //!           ・ UPDATE_VOLUME ... ambientParam.volume @n
    //!           ・ UPDATE_PAN ... ambientParam.pan @n
    //!           ・ UPDATE_PRIORITY ... ambientParam.priority @n
    //!           ・ UPDATE_PITCH ... ambientParam.pitch @n
    //! 
    //!           サウンド再生開始前に行われるプライオリティ計算のためにこの関数が呼ばれた場合には、
    //!           updateFlag  に UPDATE_START_PRIORITY が設定されます。
    //!           (このとき UPDATE_PRIORITY  も同時に設定されています。)
    //!
    //!           引数として渡される ambientParam 構造体には、
    //!           前回の 3D サウンド計算結果が格納されています。
    //!           UpdateAmbientParam 関数をオーバーライドする際、
    //!           ここで渡される値と今回計算される値とを比較することで急激なパラメータ変化を避け、
    //!           プチノイズを抑制することが可能になります。
    //!
    //! @param[in] sound3DManager 3D サウンドマネージャです。
    //! @param[in] sound3DParam   3D サウンドパラメータです。
    //! @param[in] soundId        サウンドの ID です。
    //! @param[in] updateFlag     どのパラメータを更新するかを示したフラグです。
    //! @param[out] ambientParam  計算結果を格納するパラメータ構造体です。
    //!
    //! @see Sound3DManager クラス
    //! @see Sound3DParam 構造体
    //! @see SoundAmbientParam 構造体
    //!
    //! @date 2010/03/12 初版
    //---------------------------------------------------------------------------
    virtual void UpdateAmbientParam(
        const Sound3DManager* sound3DManager,
        const Sound3DParam* sound3DParam,
        u32 soundId,
        u32 updateFlag,
        SoundAmbientParam* ambientParam
    );
    //@}

private:
    virtual int GetAmbientPriority(
        const Sound3DManager* sound3DManager,
        const Sound3DParam* sound3DParam,
        u32 soundId
    );
    virtual void UpdateAmbientParam(
        const Sound3DManager* sound3DManager,
        const Sound3DParam* sound3DParam,
        u32 soundId,
        SoundAmbientParam* ambientParam
    );

    Sound3DCalculator::CalcPanParam m_CalcPanParam;
};

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


#endif /* NW_SND_SOUND_3D_ENGINE_H_ */