snd_SoundSystem.h - OpenGrok cross reference for /NW4C-1.3.3/include/nw/snd/snd_SoundSystem.h

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

  Copyright (C)2009-2010 Nintendo Co., Ltd./HAL Laboratory, Inc.  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.

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

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

#ifndef NW_SND_SOUND_SYSTEM_H_
#define NW_SND_SOUND_SYSTEM_H_

#include <nn/os.h>
#include <nn/snd.h>
#include <nw/snd/snd_Config.h>
#include <nw/snd/snd_Global.h>
#include <nw/snd/snd_HardwareManager.h>
#include <nw/snd/snd_VoiceManager.h>
#include <nw/snd/snd_SoundThread.h>
#include <nw/snd/snd_MmlParser.h>
#include <nw/snd/snd_TaskThread.h>
#include <nw/snd/snd_ThreadStack.h>

namespace nw {
namespace snd {

//---------------------------------------------------------------------------
//! @brief  サウンドシステム全体に関わる設定を行います。
//!
//!         @n
//!
//!         【エフェクト処理の概要】
//!
//!         エフェクトは @ref AppendEffect 関数および @ref ClearEffect 関数で、
//!         登録と解除ができます。
//!
//!         エフェクトには大きく分けて NW4C が提供するエフェクト
//!         (@ref nw::snd::FxBase, @ref nw::snd::FxDelay, @ref nw::snd::FxReverb)
//!         と、CTR_SDK が提供するエフェクト (nn::snd::FxDelay, nn::snd::FxReverb)
//!         があります。いずれも @ref AppendEffect 関数で登録することができます。
//!
//!         NW4C が提供するエフェクトは、必ずアプリケーションコアで実行されます。
//!         アプリケーションコアに負荷がかかるデメリットがある一方、
//!         1 つの AUX バスに複数のエフェクトを設定したり、
//!         ユーザーが @ref FxBase を継承して実装したエフェクトを実行させることができます。
//!
//!         SDK が提供するエフェクトは、サウンドスレッドがシステムコアで動作している場合は、
//!         システムコアで実行されます。
//!         エフェクトの処理負荷をシステムコアに逃がせる一方、
//!         1 つの AUX バスにつき、nn::snd::FxDelay か nn::snd::FxReverb
//!         のどちらかしか設定できません。
//!         さらに、nn::snd::FxReverb はシステムコアの処理量を抑えるため、
//!         前方 2ch のリバーブ処理しかできないようになっています
//!         (詳しくは CTR_SDK の nn::snd::FxReverb
//!         クラスのリファレンスマニュアルをご覧ください)。
//!         NW4C が提供するエフェクトと異なり、
//!         ユーザーが自分で実装したエフェクトを実行させることもできません。
//!         また、サウンドスレッドがアプリケーションコアで動作している場合は、
//!         SDK が提供するエフェクトもアプリケーションコアで動作します。
//!
//!         NW4C が提供するエフェクトと SDK が提供するエフェクトは、
//!         各 AUX バスに、それぞれ独立して登録することができます。
//!         たとえば、AUX_BUS_A に「NW4C の FxDelay」および
//!         「ユーザーが実装した NW4C エフェクト」、
//!         さらに「SDK の FxReverb」を、AUX_BUS_B に「NW4C の FxReverb」と
//!         「SDK の FxDelay」を登録する、といったことが可能です。
//!
//!         また、エフェクト処理は「NW4C 提供のエフェクト」→「SDK 提供のエフェクト」
//!         の順に実行されます。
//!
//!
//! @date 2010/20/21 【エフェクト処理の概要】を追記
//! @date 2010/01/15 初版
//---------------------------------------------------------------------------
class SoundSystem
{
  public:

    //---------------------------------------------------------------------------
    //! @brief  サウンドシステムの初期化に使用する構造体です。
    //!
    //!         soundThreadCoreNo を 1 にすると、サウンドスレッドをシステムコア
    //!         (コア 1) で処理させることができます。
    //!
    //!         autoCreateSoundThread を false にすると、
    //!         ユーザーは自前でサウンドスレッド用のスレッドをつくる必要があります。
    //!         ユーザーにはシステムコアで動作するスレッドを作ることは許可されていないため、
    //!         この場合はアプリケーションコア (コア 0)
    //!         でサウンドスレッドを動作させることになります。
    //!
    //! @see SoundSystem クラス
    //!
    //! @date 2010/12/02 autoCreateSoundThread の説明で、soundThreadCoreNo が無視される旨追記
    //! @date 2010/09/24 soundThreadCoreNo, enableGetSoundThreadTick メンバの追加
    //! @date 2010/01/29 メンバ変数の型 (u32 → size_t)、および、
    //!                  名前 (romThread*** → taskThread***) を変更
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct SoundSystemParam
    {
        //---------------------------------------------------------------------------
        //! @brief    サウンドスレッドのプライオリティです。初期値は 4 です。
        //---------------------------------------------------------------------------
        s32 soundThreadPriority;

        //---------------------------------------------------------------------------
        //! @brief  サウンドスレッドのコア番号です。初期値は 0 です。
        //          0 はアプリケーションコア、1 はシステムコアを意味します。
        //---------------------------------------------------------------------------
        s32 soundThreadCoreNo;

        //---------------------------------------------------------------------------
        //! @brief    サウンドスレッドのスタックサイズです。8 の倍数で指定してください。
        //!           初期値は 16KB です。
        //---------------------------------------------------------------------------
        size_t soundThreadStackSize;

        //---------------------------------------------------------------------------
        //! :private
        //!
        //! @brief    サウンドスレッドのコマンドバッファサイズです。4 の倍数で指定してください。
        //!           初期値は 128KB です。
        //---------------------------------------------------------------------------
        size_t soundThreadCommandBufferSize;

        //---------------------------------------------------------------------------
        //! @brief    サウンドデータロードスレッドのプライオリティです。初期値は 3 です。
        //---------------------------------------------------------------------------
        s32 taskThreadPriority;

        //---------------------------------------------------------------------------
        //! @brief    サウンドデータロードスレッドのスタックサイズです。
        //!           8 の倍数で指定してください。初期値は 16KB です。
        //---------------------------------------------------------------------------
        size_t taskThreadStackSize;

        //---------------------------------------------------------------------------
        //! :private
        //!
        //! @brief    サウンドデータロードスレッドのコマンドバッファサイズです。
        //!           4 の倍数で指定してください。初期値は 8KB です。
        //---------------------------------------------------------------------------
        size_t taskThreadCommandBufferSize;

        //---------------------------------------------------------------------------
        //! @brief    @ref Initialize でサウンドスレッドを自動生成するかどうかを示すフラグです。
        //!           初期値は true です。
        //!           false の場合は、soundThreadStackSize および soundThreadPriority、
        //!           soundThreadCoreNo は無視されます。
        //---------------------------------------------------------------------------
        bool autoCreateSoundThread;

        //---------------------------------------------------------------------------
        //! @brief    サウンドスレッド処理負荷計測するかどうかを示すフラグです。
        //!           初期値は true です。
        //!           false の場合は、@ref GetSoundThreadTickCount は正常に動作しません。
        //---------------------------------------------------------------------------
        bool enableGetSoundThreadTick;

        //! サウンドスレッドプライオリティのデフォルト値です。
        static const s32 DEFAULT_SOUND_THREAD_PRIORITY = 4;

        //! サウンドデータロードスレッドプライオリティのデフォルト値です。
        static const s32 DEFAULT_TASK_THREAD_PRIORITY = 3;

        //! サウンドスレッドスタックサイズのデフォルト値です。
        static const u32 DEFAULT_SOUND_THREAD_STACK_SIZE = 16 * 1024;

        //! サウンドデータロードスレッドスタックサイズのデフォルト値です。
        static const u32 DEFAULT_TASK_THREAD_STACK_SIZE = 16 * 1024;

        //---------------------------------------------------------------------------
        //! :private
        //!
        //! @brief    サウンドスレッドのコマンドバッファサイズのデフォルト値です。
        //---------------------------------------------------------------------------
        static const u32 DEFAULT_SOUND_THREAD_COMMAND_BUFFER_SIZE = 128 * 1024;

        //---------------------------------------------------------------------------
        //! :private
        //!
        //! @brief    サウンドデータロードスレッドのコマンドバッファサイズのデフォルト値です。
        //---------------------------------------------------------------------------
        static const u32 DEFAULT_TASK_THREAD_COMMAND_BUFFER_SIZE = 8 * 1024;


        //---------------------------------------------------------------------------
        //! @brief    コンストラクタです。
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        SoundSystemParam()
        : soundThreadPriority( DEFAULT_SOUND_THREAD_PRIORITY ),
          soundThreadCoreNo(0),
          soundThreadStackSize( DEFAULT_SOUND_THREAD_STACK_SIZE ),
          soundThreadCommandBufferSize( DEFAULT_SOUND_THREAD_COMMAND_BUFFER_SIZE ),
          taskThreadPriority( DEFAULT_TASK_THREAD_PRIORITY ),
          taskThreadStackSize( DEFAULT_TASK_THREAD_STACK_SIZE ),
          taskThreadCommandBufferSize( DEFAULT_TASK_THREAD_COMMAND_BUFFER_SIZE ),
          autoCreateSoundThread( true ),
          enableGetSoundThreadTick( true )
        {}
    };

    //----------------------------------------
    //! @name システム
    //@{
    //---------------------------------------------------------------------------
    //! @brief  サウンドライブラリの初期化を行います。
    //!
    //!         サウンドシステムが使用するワークメモリをユーザが渡します。
    //!         @ref SoundSystemParam 構造体に、初期化に必要なパラメータを設定し、
    //!         @ref nw::snd::SoundSystem::GetRequiredMemSize で、
    //!         必要なメモリサイズを取得してください。
    //!
    //!         @ref SoundSystemParam 構造体で指定した優先度・スタックサイズで、
    //!         サウンド処理を行うスレッドと、
    //!         ROM からサウンドデータをロードするためのスレッドの初期化、実行します。
    //!
    //!         nw::snd ライブラリ内部でサウンドスレッドを起動せずに初期化を行いたい場合は
    //!         @ref SoundSystemParam 構造体の autoCreateSoundThread を
    //!         false にして呼び出してください。
    //!         詳しくは demos/snd/createSoundThreadManually デモをご覧ください。
    //!
    //!         また、 nw::snd ライブラリ内部でサウンドスレッドを起動しない場合は、
    //!         @ref GetSoundThreadTickCount は正しく動作しません。
    //!
    //!         nw::snd ライブラリ内部で起動するサウンドスレッドをシステムコア (コア 1)
    //!         で動作させるには、@ref SoundSystemParam 構造体の soundThreadCoreNo を
    //!         1 に設定します。詳しくは、サウンドプログラマーズガイドの
    //!         「8 システムコアでの動作」の章をご覧ください。
    //!
    //! @param[in]    param           初期化パラメータです。
    //! @param[in]    workMem         サウンドシステムのワークメモリへのポインタです。
    //! @param[in]    workMemSize     ワークメモリのサイズです。
    //!
    //! @see Finalize
    //! @see GetRequiredMemSize
    //! @see SoundSystemParam
    //! @see IsInitialized
    //!
    //! @date 2010/09/27 システムコア動作について追記
    //! @date 2010/06/14 サウンドスレッドを起動せずに初期化する方法を追記
    //! @date 2010/03/30 workMem のアラインメント制限に関する記述を削除
    //! @date 2010/01/29 関数名を変更 (InitSoundSystem → Initialize)、
    //!                  スレッドプライオリティのみを指定する関数を削除、文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void Initialize(
        const SoundSystemParam& param,
        uptr workMem,
        size_t workMemSize
    );

    //---------------------------------------------------------------------------
    //! @brief        サウンドライブラリの初期化に必要なメモリサイズを取得します。
    //!
    //!               param に設定されている初期化パラメータに基づいて、
    //!               サウンドシステムのセットアップに必要なメモリサイズを計算します。
    //!
    //!               この関数で取得したサイズのメモリ領域を
    //!               @ref nw::snd::SoundSystem::Initialize に渡してください。
    //!
    //! @param[in]    param   初期化パラメータです。
    //!
    //! @return       サウンドシステムの初期化に必要なメモリサイズを返します。
    //!
    //! @see  Initialize
    //! @see  SoundSystemParam
    //!
    //! @date 2010/06/14 文言の調整
    //! @date 2010/01/29 返り値の型変更 (u32 → size_t)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static size_t GetRequiredMemSize( const SoundSystemParam& param );

    //---------------------------------------------------------------------------
    //! @brief        サウンドシステムの終了処理を行います。
    //!
    //!               @ref SoundSystem::Initialize で作成された、
    //!               サウンド処理を行うスレッドと
    //!               ROM からサウンドデータをロードするためのスレッドを終了させます。
    //!
    //! @see Initialize
    //!
    //! @date 2010/01/29 関数名を変更 (ShutdownSoundSystem → Finalize)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void Finalize();

    //---------------------------------------------------------------------------
    //! @brief        サウンドフレーム処理から呼び出されるコールバック関数を設定します。
    //!
    //!               たとえば、本関数で設定したユーザーコールバックから、
    //!               nn::snd::GetMixedBusData 関数を呼び出すことで、
    //!               ミックス済みのデータ (DSP が生成する最終段の波形データ)
    //!               を得ることができます。
    //!
    //!               また、ユーザーが独自に取得した nn::snd::Voice に対して、
    //!               パラメータ設定 (ボリューム設定など) タイミングを合わせるには、
    //!               本関数内で設定関数を呼び出すことで実現することができます。
    //!               demos/snd/withSdk サンプルデモもあわせてご覧ください。
    //!
    //!               @ref Initialize で、サウンドスレッドを起動しなかった場合は、
    //!               本関数を呼び出しても機能しません。
    //!
    //! @param[in] callback   サウンドフレーム処理から呼び出されるコールバック関数です。
    //! @param[in] arg        コールバック関数に渡されるユーザー引数です。
    //!
    //! @see Initialize
    //! @see SoundFrameUserCallback
    //! @see ClearSoundFrameUserCallback
    //!
    //! @date 2010/10/27 誤植修正 (dmoes→demos)
    //! @date 2010/06/14 初版
    //---------------------------------------------------------------------------
    static void SetSoundFrameUserCallback( SoundFrameUserCallback callback, uptr arg )
    {
        internal::driver::SoundThread::GetInstance().RegisterSoundFrameUserCallback(
                callback, arg );
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドフレーム処理から呼び出されるコールバック関数を削除します。
    //!
    //! @see SetSoundFrameUserCallback
    //!
    //! @date 2010/06/14 初版
    //---------------------------------------------------------------------------
    static void ClearSoundFrameUserCallback()
    {
        internal::driver::SoundThread::GetInstance().ClearSoundFrameUserCallback();
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドフレーム処理を行います。
    //!
    //!               @ref Initialize で、サウンドスレッドを起動しなかった場合、
    //!               ユーザーアプリ内で呼び出す必要があります。
    //!
    //!               典型的には、ユーザーアプリ内で呼び出される
    //!               nn::snd::WaitForDspSync と nn::snd::SendParameterToDsp の間に
    //!               1 回呼び出します。
    //!
    //!               詳しくは demos/snd/createSoundThreadManually デモをご覧ください。
    //!
    //! @see  Initialize
    //!
    //! @date 2010/06/14 初版
    //---------------------------------------------------------------------------
    static void SoundFrameProcess()
    {
        internal::driver::SoundThread::GetInstance().FrameProcessForExternalThread();
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドシステムが初期化されているかどうかを取得します。
    //!
    //!               @ref Initialize が呼び出され、
    //!               サウンドシステムの初期化が完了しているかどうかを調べます。
    //!
    //! @return       サウンドシステムの初期化が完了していれば true を、
    //!               そうでなければ false を返します。
    //!
    //! @see  Initialize
    //! @see  Finalize
    //!
    //! @date 2010/01/29 関数名変更 (IsInitializedSoundSystem → IsInitialized)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static bool IsInitialized();


    //---------------------------------------------------------------------------
    //! @brief      サウンドスレッドをロックします。
    //!
    //!             CTR_SDK の nn::snd::AllocVoice, nn::snd::FreeVoice,
    //!             nn::snd::Voice の各関数を呼び出す場合は、
    //!             必ず本関数でサウンドスレッドをロックするようにしてください。
    //!
    //!             ただし、サウンドスレッドをアプリケーションコアで動作させている状況で、
    //!             @ref RegisterSoundFrameUserCallback 関数で登録したコールバック内で
    //!             上記関数を呼び出す場合は、ロックは不要です。
    //!
    //!             コールバック以外から上記関数を呼び出す場合、あるいは、
    //!             サウンドスレッドをシステムコアで動作させている場合は、
    //!             本関数によるロックが必要です。
    //!
    //!             上記関数の使用後、@ref UnlockSoundThread
    //!             でロックを解除するようにしてください。
    //!
    //!             長時間ロックし続けると、nw::snd のサウンド処理が滞り、
    //!             音が途切れるなどの悪影響があります。
    //!
    //!             demos/snd/withSdk サンプルデモもあわせてご覧ください。
    //!
    //! @see  UnlockSoundThread
    //!
    //! @date 2010/10/27 初版
    //---------------------------------------------------------------------------
    static void LockSoundThread()
    {
    #ifdef NW_SND_CONFIG_USE_NN_SND_LOCKSOUNDTHREAD
        if ( s_AutoCreateSoundThreadFlag ) {
            nn::snd::LockSoundThread();
        }
        else {
            internal::driver::SoundThread::GetInstance().Lock();
        }
    #else
        internal::driver::SoundThread::GetInstance().Lock();
    #endif
    }

    //---------------------------------------------------------------------------
    //! @brief      サウンドスレッドをアンロックします。
    //!
    //!             @ref LockSoundThread 関数の説明もあわせてご覧ください。
    //!
    //! @see  LockSoundThread
    //!
    //! @date 2010/10/27 初版
    //---------------------------------------------------------------------------
    static void UnlockSoundThread()
    {
    #ifdef NW_SND_CONFIG_USE_NN_SND_LOCKSOUNDTHREAD
        if ( s_AutoCreateSoundThreadFlag ) {
            nn::snd::UnlockSoundThread();
        }
        else {
            internal::driver::SoundThread::GetInstance().Unlock();
        }
    #else
        internal::driver::SoundThread::GetInstance().Unlock();
    #endif
    }

    //---------------------------------------------------------------------------
    //! @brief      オブジェクトの生成時からオブジェクトの存在するスコープを抜けるまでの間、
    //!             サウンドスレッドをロックします。
    //!
    //!             使用に関する注意点は、@ref LockSoundThread 関数と同じです。
    //!
    //! @see LockSoundThread
    //! @see UnlockSoundThread
    //!
    //! @date 2010/10/27 初版
    //---------------------------------------------------------------------------
    class SoundThreadScopedLock
    {
    public:
        //---------------------------------------------------------------------------
        //! @brief  コンストラクタです。
        //!
        //!         内部で @ref LockSoundThread 関数を呼び出します。
        //!
        //! @see  LockSoundThread
        //!
        //! @date 2010/11/02 初版
        //---------------------------------------------------------------------------
        SoundThreadScopedLock()
        {
            LockSoundThread();
        }
        //---------------------------------------------------------------------------
        //! @brief  デストラクタです。
        //!
        //!         内部で @ref UnlockSoundThread 関数を呼び出します。
        //!
        //! @see  UnlockSoundThread
        //!
        //! @date 2010/11/02 初版
        //---------------------------------------------------------------------------
        ~SoundThreadScopedLock()
        {
            UnlockSoundThread();
        }
    private:
        NW_DISALLOW_COPY_AND_ASSIGN( SoundThreadScopedLock );
    };


    //---------------------------------------------------------------------------
    //! @brief  サウンドライブラリのスリープ準備処理を実行します。
    //!
    //!         スリープに入る前に、本関数を必ず呼び出してください。
    //!
    //!         スリープの準備では、
    //!         サウンドデータロードスレッドをロックします。
    //!
    //!         サウンドデータロードスレッドでロード中のデータがある場合は、
    //!         ロードが終わるまで本関数内でブロックされます。
    //!
    //!         スリープを解除する場合は、@ref LeaveSleep 関数を呼び出してください。
    //!
    //! @see  LeaveSleep
    //!
    //! @date 2011/01/11 初版
    //---------------------------------------------------------------------------
    static void EnterSleep()
    {
        s_IsStreamLoadWait = true;
        s_TaskThread.Lock();

        // サウンドスレッドは SDK 側で止められる
    }

    //---------------------------------------------------------------------------
    //! @brief  サウンドライブラリのスリープ終了処理を実行します。
    //!
    //!         スリープを解除した後に、必ず呼び出してください。
    //!
    //! @see  EnterSleep
    //!
    //! @date 2011/01/11 初版
    //---------------------------------------------------------------------------
    static void LeaveSleep()
    {
        // サウンドスレッドは SDK 側で復帰する

        s_TaskThread.Unlock();
        s_IsStreamLoadWait = false;
    }

    //! @details :private
    static bool detail_IsStreamLoadWait()
    {
        return s_IsStreamLoadWait;
    }
    //@}

    //----------------------------------------
    //! @name 出力モード
    //@{
    //---------------------------------------------------------------------------
    //! @brief  サウンドの出力モードを設定します。
    //!
    //!         内部で nn::snd::SetSoundOutputMode を呼び出し、
    //!         対応する出力モードを設定します。
    //!
    //!         以下に、@ref nw::snd::OutputMode と nn::snd::OutputMode の対応関係を示します。
    //!
    //!         ・OUTPUT_MODE_MONO → nn::snd::OUTPUT_MODE_MONO @n
    //!         ・OUTPUT_MODE_STEREO → nn::snd::OUTPUT_MODE_STEREO @n
    //!         ・OUTPUT_MODE_SURROUND → nn::snd::OUTPUT_MODE_3DSURROUND
    //!
    //! @param[in]    mode    サウンドの出力モードです。
    //!
    //! @see  nw::snd::OutputMode
    //! @see  GetOutputMode
    //!
    //! @date 2010/07/07 nn::snd::SetSoundOutputMode を呼び出す旨、追記
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void SetOutputMode( OutputMode mode )
    {
        internal::driver::HardwareManager::GetInstance().SetOutputMode( mode );
    }

    //---------------------------------------------------------------------------
    //! @brief        現在のサウンド出力モードを取得します。
    //!
    //! @return       現在のサウンド出力モードを返します。
    //!
    //! @see  nw::snd::OutputMode
    //! @see  SetOutputMode
    //!
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static OutputMode GetOutputMode()
    {
        return internal::driver::HardwareManager::GetInstance().GetOutputMode();
    }
    //@}

    //----------------------------------------
    //! @name マスターボリューム
    //@{
    //---------------------------------------------------------------------------
    //! @brief        マスターボリュームを設定します。
    //!
    //!               マスターボリュームは、
    //!               サウンドライブラリで発音される音全てに対して影響を与えます。
    //!               サウンドライブラリ以外で発音された音には影響を与えません。
    //!
    //!               この関数で指定する値は、他のどの音量パラメータとも独立して動作し、
    //!               それらは全て重ね合わされます。
    //!
    //!               音量 volume は、0.0 以上の倍率で指定します。
    //!               すなわち、1.0 を指定すると音量に影響を与えません。
    //!               0.0 を指定すると発音されなくなります。
    //!               デフォルト値は 1.0 です。
    //!
    //!               他の音量パラメータと重ね合わされたあと、最終的な音量は
    //!               0.0 ～ 2.0 の範囲でクランプされます。
    //!               この関数で 2.0 を設定したとしても、元サウンドの音量は 2
    //!               倍にならない可能性があることに注意してください。
    //!
    //!               音量の変化は fadeTimes で指定した時間をかけて行われます。
    //!               音量の変化途中にさらにこの関数を呼び出した場合は、
    //!               その時点での変化途中の音量値を基点として、
    //!               新しく指定した時間をかけて音量を変化させます。
    //!
    //! @param[in] volume     音量の倍率 ( 0.0 ～ ) です。
    //! @param[in] fadeTimes  音量変化にかける時間 (ミリ秒) です。
    //!
    //! @see  GetMasterVolume
    //!
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/25 引数の説明追加。
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void SetMasterVolume( float volume, int fadeTimes )
    {
        internal::driver::HardwareManager::GetInstance().SetMasterVolume( volume, fadeTimes );
    }
    // TODO: ★ 「AUX に送られる前に反映されるので～」を書いていない

    //---------------------------------------------------------------------------
    //! @brief        現在のマスターボリュームを取得します。
    //!
    //!               現在設定されている @ref SetMasterVolume で設定された
    //!               マスターボリュームの値を取得します。
    //!
    //!               音量が時間変化している間に値を取得した場合は、
    //!               その時点での変化途中の音量の値を返します。
    //!
    //! @return       現在のマスターボリュームの値を返します。
    //!
    //! @see          SetMasterVolume
    //!
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static float GetMasterVolume()
    {
        return internal::driver::HardwareManager::GetInstance().GetMasterVolume();
    }
    //@}

    //----------------------------------------
    //! @name エフェクト
    //@{

    //---------------------------------------------------------------------------
    //! @brief      指定したエフェクトを AUX バスに追加します。
    //!
    //!             エフェクトは、指定したバスそれぞれで独立して処理されます。
    //!             nw::snd のエフェクト (nn::snd::FxBase を継承したエフェクト) は、
    //!             1 つのバスに複数のエフェクトを登録することができます。
    //!             エフェクトは、追加した順番で処理されます。
    //!
    //!             途中でエフェクトの接続順を変更したい場合は、
    //!             @ref nw::snd::SoundSystem::ClearEffect
    //!             を呼び出して一度すべてのエフェクトの登録を削除した後、
    //!             改めて追加しなおしてください。
    //!
    //!             エフェクトを追加する際、内部で @ref nw::snd::FxBase::Initialize
    //!             を呼び出しています。
    //!
    //!             エフェクト処理の概要については @ref SoundSystem クラスの説明をご覧ください。
    //!
    //! @param[in]  bus         エフェクトを追加するバスです。
    //! @param[in]  effect      エフェクトです。
    //!
    //! @return     エフェクトの開始に成功したら true を、失敗したら false を返します。
    //!
    //! @see AuxBus
    //! @see FxBase
    //! @see ClearEffect
    //!
    //! @date 2010/10/22 参照に @ref ClearEffect を追加、微調整
    //! @date 2010/06/16 初版
    //---------------------------------------------------------------------------
    static bool AppendEffect( AuxBus bus, FxBase* effect );

#ifdef NW_SND_AVAILABLE_NN_EFFECT
    //---------------------------------------------------------------------------
    //! @brief      指定したエフェクトを AUX バスに追加します。
    //!
    //!             エフェクトは、指定したバスそれぞれで独立して処理されます。
    //!             nn::snd のエフェクト (nn::snd::FxDelay および nn::snd::FxReverb) は、
    //!             各バスにどちらかひとつしか設定することができません。
    //!
    //!             nn::snd エフェクトを解除したい場合は、@ref ClearEffect
    //!             関数を呼び出します。@ref ClearEffect 関数を呼びだすと、
    //!             内部で nn::snd::ClearEffect 関数が呼び出されます。
    //!
    //!             エフェクトを追加する際、内部で nn::snd::SetEffect
    //!             関数を呼び出しています。
    //!
    //!             エフェクト処理の概要については @ref SoundSystem クラスの説明をご覧ください。
    //!
    //! @param[in]  bus         エフェクトを追加するバスです。
    //! @param[in]  fxDelay     ディレイエフェクトです。
    //!
    //! @return     エフェクトの開始に成功したら true を、失敗したら false を返します。
    //!
    //! @see AuxBus
    //! @see ClearEffect
    //!
    //! @date 2010/10/22 初版
    //---------------------------------------------------------------------------
    static bool AppendEffect( AuxBus bus, nn::snd::FxDelay* fxDelay );

    //---------------------------------------------------------------------------
    //! @brief      指定したエフェクトを AUX バスに追加します。
    //!
    //!             エフェクトは、指定したバスそれぞれで独立して処理されます。
    //!             nn::snd のエフェクト (nn::snd::FxDelay および nn::snd::FxReverb) は、
    //!             各バスにどちらかひとつしか設定することができません。
    //!
    //!             nn::snd エフェクトを解除したい場合は、@ref ClearEffect
    //!             関数を呼び出します。@ref ClearEffect 関数を呼びだすと、
    //!             内部で nn::snd::ClearEffect 関数が呼び出されます。
    //!
    //!             エフェクトを追加する際、内部で nn::snd::SetEffect
    //!             関数を呼び出しています。
    //!
    //!             エフェクト処理の概要については @ref SoundSystem クラスの説明をご覧ください。
    //!
    //! @param[in]  bus         エフェクトを追加するバスです。
    //! @param[in]  fxReverb    リバーブエフェクトです。
    //!
    //! @return     エフェクトの開始に成功したら true を、失敗したら false を返します。
    //!
    //! @see AuxBus
    //! @see ClearEffect
    //!
    //! @date 2010/10/22 初版
    //---------------------------------------------------------------------------
    static bool AppendEffect( AuxBus bus, nn::snd::FxReverb* fxReverb );
#endif

    //---------------------------------------------------------------------------
    //! @brief        指定した AUX バスに登録されているエフェクトを全てバスから削除します。
    //!
    //!               エフェクトを終了させる際、 fadeTimes でフェードアウトをかけることができます。
    //!               フェードアウトが完了するまでエフェクトは終了しません。
    //!               フェードアウトが完了したかどうかを知るには
    //!               @ref nw::snd::SoundSystem::IsFinishedClearEffect を呼び出してください。
    //!
    //!               エフェクトをバスから削除する際、内部で
    //!               @ref nw::snd::FxBase::Finalize を呼び出しています。
    //!
    //! @param[in]    bus         エフェクトバスです。
    //! @param[in]    fadeTimes   フェード時間 (ミリ秒) です。
    //!
    //! @see IsFinishedClearEffect
    //! @see AuxBus
    //! @see FxBase
    //!
    //! @date 2010/06/16 初版
    //---------------------------------------------------------------------------
    static void ClearEffect( AuxBus bus, int fadeTimes = 0 );

    //---------------------------------------------------------------------------
    //! @brief        ClearEffect が完了したかどうかを調べます。
    //!
    //!               @ref ClearEffect が呼ばれる前の動作は不定です。
    //!
    //! @param[in]    bus エフェクトバスです。
    //!
    //! @return       @ref ClearEffect の処理が完了していれば true を、
    //!               そうでなければ false を返します。
    //!
    //! @see ClearEffect
    //! @see AuxBus
    //!
    //! @date 2010/06/16 初版
    //---------------------------------------------------------------------------
    static bool IsFinishedClearEffect( AuxBus bus )
    {
        return internal::driver::HardwareManager::GetInstance().IsFinishedClearEffect( bus );
    }
    //@}

    //----------------------------------------
    //! @name SRC タイプ
    //@{
    //---------------------------------------------------------------------------
    //! @brief      SRC タイプ (サンプリングレートコンバータの補間方法) を設定します。
    //!
    //!             デフォルトでは SRC_TYPE_4TAP が設定されています。
    //!
    //!             ウェーブサウンドおよびストリームサウンドに影響がありますが、
    //!             シーケンスサウンドには影響がありません。
    //!             シーケンスサウンドは、SoundMaker のインストリストおよび
    //!             パーカッションリスト上で設定された「補間タイプ」が影響します。
    //!
    //! @param[in]    type    SRC タイプです。
    //!
    //! @see nw::snd::SrcType
    //! @see GetSrcType
    //!
    //! @date 2010/10/15 シーケンスサウンドには影響のない旨、追記
    //! @date 2010/08/18 実装されたため、未実装の旨、削除
    //! @date 2010/07/27 未実装の旨、追記
    //! @date 2010/01/26 文言の調整、誤記修正 (参照の SetSrcType → GetSrcType)
    //! @date 2010/01/25 誤記修正 (SRC_4TAP_AUTO → SRC_TYPE_4TAP)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void SetSrcType( SrcType type )
    {
        internal::driver::HardwareManager::GetInstance().SetSrcType( type );
    }

    //---------------------------------------------------------------------------
    //! @brief        現在設定されている SRC タイプ
    //!               (サンプリングレートコンバータの補間方法) を取得します。
    //!
    //!               デフォルトでは SRC_TYPE_4TAP が設定されています。
    //!
    //! @return       現在設定されている SRC タイプの値を返します。
    //!
    //! @see nw::snd::SrcType
    //! @see SetSrcType
    //!
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/25 誤記修正 (SRC_4TAP_AUTO → SRC_TYPE_4TAP)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static SrcType GetSrcType()
    {
        return internal::driver::HardwareManager::GetInstance().GetSrcType();
    }
    //@}

    //----------------------------------------
    //! name リセット準備
    //{

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief        リセット前に必要なサウンドの処理を行います。
    //!
    //!               この関数は、リセット時にノイズが発生しないように再生中の音を緩やかに消します。
    //!               一度この関数が呼ばれた後は、再び発音することができません。
    //!
    //!               ノイズが発生しないようにリセットを行うためには、
    //!               @ref WaitForResetReady を呼び出して、
    //!               この関数の処理が完了するのを待つ必要があります。
    //!
    //! @see  WaitForResetReady
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void PrepareReset()
    {
        internal::driver::HardwareManager::GetInstance().PrepareReset();
    }

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief        サウンドのリセット準備処理が完了するのを待ちます。
    //!
    //!               この関数は、@ref PrepareReset が呼び出された後に、
    //!               その処理が完了するのを待ちます。
    //!
    //! @see  PrepareReset
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void WaitForResetReady();
    //}

    //----------------------------------------
    //! @name パフォーマンス計測
    //@{
    //---------------------------------------------------------------------------
    //! @brief        サウンドスレッド処理にかかった累積時間および処理回数を取得します。
    //!
    //!               サウンドスレッドの処理は、定期的 (約 5ms ごと。正確には、
    //!               @ref SOUND_THREAD_INTERVAL_USEC マイクロ秒ごと) に実行されるため、
    //!               本関数を 1/60 秒 (約 16.67ms) ごとに呼び出した場合、
    //!               処理回数は約 3～4 回になります。
    //!               累積処理時間は、この約 3～4 回分のサウンドスレッド処理にかかった時間になります。
    //!
    //!               処理に要した時間は、
    //!               サウンドスレッドを開始した時間と終了した時間の差分で計算します。
    //!               したがって、サウンドスレッドの実行中に他のスレッドに切り替わった場合、
    //!               それらの実行時間を含んだ値を返すことに注意してください。
    //!
    //!               処理時間には、NW4C サウンドライブラリ層の処理にかかった時間に加え、
    //!               nn::snd::WaitForDspSync および nn::snd::SendParameterToDsp
    //!               にかかった時間も含まれます。
    //!
    //!               累積時間及び処理回数は @ref ClearSoundThreadTickCount 関数によって、
    //!               ゼロにクリアすることができます。
    //!
    //! @param[out]   tick    サウンドスレッド内部の累積処理時間です。
    //! @param[out]   count   サウンドスレッド処理回数です。
    //!
    //! @see ClearSoundThreadTickCount
    //! @see SOUND_THREAD_INTERVAL_USEC
    //!
    //! @date 2010/12/10 PC 版に関する記述を削除
    //! @date 2010/05/08 GetSoundThreadProcessTick 関数を廃止し、本関数を追加
    //---------------------------------------------------------------------------
    static void GetSoundThreadTickCount( nn::os::Tick& tick, int& count )
    {
      #ifdef NW_PLATFORM_CTR
        internal::driver::SoundThread::GetInstance().GetTickCount( tick, count );
      #else
        NW_UNUSED_VARIABLE( tick );
        NW_UNUSED_VARIABLE( count );
      #endif
    }

    //---------------------------------------------------------------------------
    //! @brief      サウンドスレッド処理にかかった累積時間および処理回数を
    //!             ゼロにリセットします。
    //!
    //! @see  GetSoundThreadTickCount
    //!
    //! @date 2010/05/08 初版
    //---------------------------------------------------------------------------
    static void ClearSoundThreadTickCount()
    {
      #ifdef NW_PLATFORM_CTR
        internal::driver::SoundThread::GetInstance().ClearTickCount();
      #endif
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドスレッド処理間隔をマイクロ秒換算した値です。
    //!
    //!               @ref GetSoundThreadTickCount で得られた count と tick に対し、
    //!               ( tick.ToTimeSpan().GetMicroSeconds() * 100 ) /
    //!               ( count * SOUND_THREAD_INTERVAL_USEC ) とすると、
    //!               count 回のサウンドスレッド処理で、
    //!               CPU を何 % 占有しているかが算出できます。
    //!
    //! @see GetSoundThreadTickCount
    //!
    //! @date 2010/05/08 初版
    //---------------------------------------------------------------------------
    static const int SOUND_THREAD_INTERVAL_USEC = NN_SND_USECS_PER_FRAME;
    //@}

    //----------------------------------------
    //! @name シーケンス変数出力設定
    //@{
    // シーケンス変数のプリント ON/OFF を設定する
    //---------------------------------------------------------------------------
    //! @brief        printvar シーケンスコマンドを有効にします。
    //!
    //!               デフォルトでは無効になっています。
    //!               詳しくは、シーケンスデータマニュアルをご覧ください。
    //!
    //!               printvar シーケンスコマンドを有効にすると、
    //!               無効のときと比べて printvar コマンド処理で余分に処理がかかるので、
    //!               シーケンス変数デバッグをしない場合は無効にしておくことを推奨します。
    //!
    //! @see  DisableSeqPrintVar
    //! @see  IsEnabledSeqPrintVar
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void EnableSeqPrintVar() { internal::driver::MmlParser::EnablePrintVar( true ); }

    //---------------------------------------------------------------------------
    //! @brief        printvar シーケンスコマンドを無効にします。
    //!
    //!               詳しくは、シーケンスデータマニュアルをご覧ください。
    //!
    //! @see  EnableSeqPrintVar
    //! @see  IsEnabledSeqPrintVar
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static void DisableSeqPrintVar() { internal::driver::MmlParser::EnablePrintVar( false ); }

    //---------------------------------------------------------------------------
    //! @brief        printvar シーケンスコマンドが有効かどうかを取得します。
    //!
    //!               true のときは有効、false のときは無効です。
    //!
    //!               printvar シーケンスコマンドを有効にすると、
    //!               無効のときと比べて printvar コマンド処理で余分に処理がかかるので、
    //!               シーケンス変数デバッグをしない場合は無効にしておくことを推奨します。
    //!
    //! @return       現在、printvar シーケンスコマンドが有効か無効かを取得します。
    //!
    //! @see  EnableSeqPrintVar
    //! @see  DisableSeqPrintVar
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static bool IsEnabledSeqPrintVar()
    {
        return internal::driver::MmlParser::IsEnabledPrintVar();
    }
    //@}

    //----------------------------------------
    //! @name 使用ボイス数
    //@{
    //---------------------------------------------------------------------------
    //! @brief        サウンドライブラリで現在発音中のボイス数を取得します。
    //!
    //! @return       現在発音中のボイス数を返します。
    //!
    //! @see GetMaxVoiceCount
    //! @see SetMaxVoiceCount
    //!
    //! @date 2010/05/14 参照に SetMaxVoiceCount を追加
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static int GetVoiceCount()
    {
        return internal::driver::VoiceManager::GetInstance().GetVoiceCount();
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドライブラリで使用できる最大ボイス数を取得します。
    //!
    //!               デフォルトでは、NN_SND_VOICE_NUM を返します。
    //!
    //! @return       最大ボイス数を返します。
    //!
    //! @see GetVoiceCount
    //! @see SetMaxVoiceCount
    //!
    //! @date 2010/05/14 デフォルト値を追記、参照に SetMaxVoiceCount を追加
    //! @date 2010/01/26 文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static int GetMaxVoiceCount()
    {
        return s_MaxVoiceCount;
    }

    //---------------------------------------------------------------------------
    //! @brief        サウンドライブラリで使用する最大ボイス数を設定します。
    //!
    //!               @ref Initialize より先に呼ぶ必要があります。
    //!
    //!               設定できる最大値は NN_SND_VOICE_NUM です。
    //!               これは、@ref GetMaxVoiceCount で取得できるデフォルト値と同じです。
    //!
    //!               最大ボイス数を削減することで、サウンドの処理量を抑えることができます。
    //!
    //!               最大ボイス数として、1 ～ NN_SND_VOICE_NUM を指定する必要があります。
    //!               範囲外の値を指定した場合は、Debug 版、Development 版ではアサートで停止し、
    //!               Release 版では 1 ～ NN_SND_VOICE_NUM の範囲に丸められます。
    //!
    //! @param[in] count  最大ボイス数です。
    //!
    //! @see Initialize
    //! @see GetVoiceCount
    //! @see GetMaxVoiceCount
    //!
    //! @date 2010/05/14 関数名を SetVoiceMaxCount → SetMaxVoiceCount に変更、アサート条件追記
    //! @date 2010/04/23 初版
    //---------------------------------------------------------------------------
    static void SetMaxVoiceCount( int count )
    {
        NW_MINMAX_ASSERT( count, 1, NN_SND_VOICE_NUM );
        count = ut::Clamp( count, 1, NN_SND_VOICE_NUM );
        s_MaxVoiceCount = count;
    }
    //@}

    //----------------------------------------
    //! @name   biquad フィルタ
    //@{
    //---------------------------------------------------------------------------
    //! @brief  ユーザー定義の biquad フィルタを登録します。
    //!
    //!         @ref BiquadFilterCallback クラスを継承してユーザーが実装した
    //!         biquad フィルタを登録します。
    //!
    //!         type には、@ref BiquadFilterType で定義されている、
    //!         BIQUAD_FILTER_TYPE_USER_MIN ～ BIQUAD_FILTER_TYPE_USER_MAX
    //!         の値を指定します。
    //!         範囲外の値を設定すると、Debug 版 / Development 版ではアサートで停止します。
    //!         Release 版では無視されます。
    //!
    //!         ここで設定したコールバック関数はサウンドスレッドから呼び出されます。
    //!         排他制御が必要な場合は、
    //!         @ref SoundThreadScopedLock クラスあるいは、
    //!         @ref LockSoundThread / @ref UnlockSoundThread 関数を利用する必要があります。
    //!
    //!         コールバック関数はすみやかに処理を終える必要があります。
    //!         処理が長引くと、ノイズが発生する可能性が高くなります。
    //!         たとえば、コールバック関数内でブロックする可能性のある API
    //!         (クリティカルセクションなど) を呼び出すと、
    //!         処理を終えるのに時間がかかる可能性があります。
    //!
    //! @param[in] type     フィルタの種類です
    //!                     (BIQUAD_FILTER_TYPE_USER_MIN ～BIQUAD_FILTER_TYPE_USER_MAX)。
    //! @param[in] biquad   ユーザーが実装した biquad フィルタクラスです。
    //!
    //! @see BiquadFilterCallback クラス
    //! @see BiquadFilterType
    //!
    //! @date 2011/01/11 コールバック関数がサウンドスレッドから呼び出される旨、追記
    //! @date 2010/10/15 初版
    //---------------------------------------------------------------------------
    static void SetBiquadFilterCallback( int type, const BiquadFilterCallback* biquad )
    {
        NW_MINMAX_ASSERT( type, BIQUAD_FILTER_TYPE_USER_MIN, BIQUAD_FILTER_TYPE_USER_MAX );
        internal::driver::HardwareManager::GetInstance().SetBiquadFilterCallback( type, biquad );
    }
    //@}

  private:
    static internal::TaskThread s_TaskThread;    // TODO: シングルトン実装ではダメ？
    static int s_MaxVoiceCount;
    static internal::ThreadStack s_LoadThreadStack;
#if defined( NW_SND_AVAILABLE_NN_SND_STARTSOUNDTHREAD )
#else
    static internal::ThreadStack s_SoundThreadStack;
#endif
    static bool s_AutoCreateSoundThreadFlag;
    static bool s_IsInitialized;
    static bool s_IsStreamLoadWait;
};

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


#endif /* NW_SND_SOUND_SYSTEM_H_ */