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

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

#ifndef NW_SND_SOUND_HANDLE_H_
#define NW_SND_SOUND_HANDLE_H_

#include <nw/ut/ut_PreProcessor.h>
#include <nw/snd/snd_BasicSound.h>
#include <nw/snd/snd_Global.h>      // BIQUAD_FILTER_TYPE_USER_MAX

namespace nw {
namespace snd {

//---------------------------------------------------------------------------
//! @brief    再生したサウンドの操作を行うためのハンドルクラスです。
//!
//!           サウンドハンドルは、 @ref SoundArchivePlayer::PrepareSound または
//!           @ref SoundArchivePlayer::StartSound を呼び出すことにより、
//!           サウンドと関連付けられます。
//!           
//!           その際、ハンドルが既に別のサウンドと関連付けられていた場合は、
//!           古いサウンドとの関連は外され、新たに再生するサウンドと関連付けられます。
//!
//!           下記の状態になると、ハンドルとサウンドの関連が外れ、
//!           その後はサウンドに対しての操作が行えないようになります。
//!
//!           ・サウンドが終端に達して停止したとき @n
//!           ・フェードフレーム 0 で @ref Stop をコールしたとき @n
//!           ・フェードフレームを 1 以上に指定して @ref Stop をコールし、
//!           そのフレーム数だけ時間が経過して停止したとき @n
//!           ・明示的に SoundHandle::DetachSound を呼び出したとき @n
//!           ・プレイヤープライオリティの判定でサウンドが停止したとき
//!
//!           したがって、@ref IsAttachedSound を毎フレーム監視することで、
//!           サウンドが終端に達して停止したかどうか、確認することができます。
//!           ただし、@ref Stop での停止や明示的な @ref DetachSound、
//!           プレイヤープライオリティ判定でのサウンド停止の影響を考慮しておく必要があります。
//!
//!           プレイヤープライオリティの判定については、サウンドシステムマニュアルの
//!           「プライオリティの動作」の章をご参照ください。
//!
//!           サウンドにはシーケンスサウンド・ストリームサウンド・ウェーブサウンドの
//!           3 種類があります。 
//!           SoundHandle クラスはこれら全てのサウンドの共通の操作を扱うことができます。
//!
//!           SoundHandle クラスでは扱えない、各サウンド専用の操作を行うために、
//!           @ref SequenceSoundHandle クラス、
//!           @ref StreamSoundHandle クラス、
//!           @ref WaveSoundHandle クラスが用意されています。
//!
//! @see SoundArchivePlayer クラス
//! @see SequenceSoundHandle クラス
//! @see StreamSoundHandle クラス
//! @see WaveSoundHandle クラス
//!
//! @date 2010/04/28 サウンドとの関連が外れる条件を追記、サウンド終端停止判定について追記
//! @date 2010/01/25 SequenceSoundHandle、StreamSoundHandle、WaveSoundHandle に関する記述を追加
//! @date 2010/01/15 初版
//---------------------------------------------------------------------------
class SoundHandle
{
public:

    //----------------------------------------
    //! @name コンストラクタ/デストラクタ
    //@{
    //! コンストラクタです。
    SoundHandle() : m_pSound( NULL ) { }
    //! デストラクタです。
    ~SoundHandle() { DetachSound(); }
    //@}

    //----------------------------------------
    //! @name 再生/停止/一時停止/再開
    //@{
    //---------------------------------------------------------------------------
    //! @brief    再生準備が完了したサウンドを再生します。
    //! 
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           サウンドの再生を開始するためには、
    //!           @ref SoundArchivePlayer::PrepareSound を呼び出した後、
    //!           再生準備が完了していなければなりません。
    //!           この関数は、再生準備が完了したサウンドの再生を開始します。
    //!           再生準備が完了していないサウンドは、
    //!           完了するまで待ってから再生を開始します。
    //!
    //! @see SoundArchivePlayer::PrepareSound
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void StartPrepared()
    {
        if ( IsAttachedSound() ) m_pSound->StartPrepared();
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドを停止します。
    //!
    //!           ハンドルに関連付けられたサウンドを停止します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           fadeFrames で指定したフレーム数をかけて
    //!           フェードアウトさせることができます。
    //!           0 を指定した場合は、フェードアウトを行いません。
    //!           ただし、シーケンスサウンドで発音中の音は、
    //!           エンベロープのリリースを発音し全ての減衰が完了した後に 
    //!           サウンドが停止します。
    //!
    //!           フェードアウトの音量制御は、フェードインと共有されます。
    //!           フェードアウトにかかるフレーム数は、
    //!           最大音量から音が消えるまでにかかる変化速度を表しますので、
    //!           フェードイン中にフェードアウトを指定した時などは、
    //!           指定したフレーム数よりも短い時間で
    //!           フェードアウトが完了する可能性があります。
    //!
    //! @param[in] fadeFrames   フェードアウトにかけるフレーム数です。
    //!                         フレーム数は @ref SoundArchivePlayer::Update
    //!                         の呼び出し回数で換算されます。
    //!
    //! @see Pause
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void Stop( int fadeFrames )
    {
        if ( IsAttachedSound() ) m_pSound->Stop( fadeFrames );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドを一時停止または再開します。
    //!
    //!           ハンドルに関連付けられたサウンドを一時停止または再開します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           fadeFrames で指定したフレーム数をかけてフェードアウトしながら一時停止、
    //!           またはフェードインしながら再開させることができます。
    //!           0 を指定した場合は、即座に一時停止または再開します。
    //!
    //!           一時停止・再開時のフェードは、再生開始時のフェードイン、
    //!           停止時のフェードアウトとは独立してはたらきます。
    //!           フェードにかかるフレーム数は、最大音量から音が消えるまで、
    //!           あるいは発音していない状態から最大音量に達するまでに 
    //!           かかる変化速度を表しますので、
    //!           フェード中にさらにフェードを指定した時などは、
    //!           指定したフレーム数よりも短い時間でフェードが完了する可能性があります。
    //!
    //! @param[in]    flag        true なら一時停止、false なら再開します。
    //! @param[in]    fadeFrames  フェードイン・フェードアウトにかけるフレーム数です。
    //!                           フレーム数は @ref SoundArchivePlayer::Update
    //!                           の呼び出し回数で換算されます。
    //!
    //! @see IsPause
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void Pause( bool flag, int fadeFrames )
    {
        if ( IsAttachedSound() ) m_pSound->Pause( flag, fadeFrames );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドの再生準備が完了しているかどうかを調べます。
    //!
    //!           @ref SoundArchivePlayer::PrepareSound を呼び出した後、
    //!           そのサウンドの再生準備が完了しているかどうかを調べます。
    //!           再生準備が完了したサウンドは、
    //!           @ref SoundHandle::StartPrepared を呼び出した際に、
    //!           すぐに再生を始めることができます。
    //!
    //! @return   サウンドの再生準備が完了していれば true を返します。
    //!
    //! @see SoundArchivePlayer::PrepareSound
    //! @see StartPrepared
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool IsPrepared() const { return IsAttachedSound() && m_pSound->IsPrepared(); }

    //---------------------------------------------------------------------------
    //! @brief    サウンドが一時停止中かどうかを調べます。
    //!
    //! @return   サウンドが一時停止状態であれば true を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool IsPause() const { return IsAttachedSound() && m_pSound->IsPause(); }

    //---------------------------------------------------------------------------
    //! @brief    サウンドを再生開始時にフェードインさせます。
    //!
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数でフェードインの指定を行うと、
    //!           @ref SoundArchivePlayer::StartSound または
    //!           @ref SoundHandle::StartPrepared を呼び出して再生を開始してから、
    //!           最初の @ref SoundArchivePlayer::Update が呼び出されたときに
    //!           フェードインが設定されます。
    //!
    //!           サウンドの再生が開始され、最初の @ref SoundArchivePlayer::Update
    //!           が呼ばれた後にこの関数を呼び出しても効果がありません。
    //!
    //!           フェードインの音量制御は、停止時のフェードアウトと共有されます。
    //!       
    //! @param[in]    frames  フェードインにかけるフレーム数です。
    //!                       フレーム数は @ref SoundArchivePlayer::Update
    //!                       の呼び出し回数で換算されます。
    //!
    //! @see StartPrepared
    //! @see SoundArchivePlayer::StartSound
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void FadeIn( int frames )
    {
        if ( IsAttachedSound() ) m_pSound->FadeIn( frames );
    }

    //---------------------------------------------------------------------------
    //! @brief    フェードイン・フェードアウト完了までの残りフレーム数を取得します。
    //!
    //!           フェード中でない場合は 0 を返します。
    //!
    //! @return   フェード完了までの残りフレーム数を返します。
    //!           フレーム数は @ref SoundArchivePlayer::Update
    //!           の呼び出し回数で換算されます。
    //!
    //! @see FadeIn
    //! @see Stop
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    int GetRemainingFadeFrames() const
    {
        if ( IsAttachedSound() ) return m_pSound->GetRemainingFadeFrames();
        else return 0;
    }

    //---------------------------------------------------------------------------
    //! @brief    一時停止時のフェード完了までの残りフレーム数を取得します。
    //!
    //!           フェード中でない場合は 0 を返します。
    //!
    //! @return   フェード完了までの残りフレーム数を返します。
    //!           フレーム数は @ref SoundArchivePlayer::Update
    //!           の呼び出し回数で換算されます。
    //!
    //! @see Pause
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    int GetRemainingPauseFadeFrames() const
    {
        if ( IsAttachedSound() ) return m_pSound->GetRemainingPauseFadeFrames();
        else return 0;
    }
    //@}

    //----------------------------------------
    //! @name パラメータ
    //@{
    //---------------------------------------------------------------------------
    //! @brief    サウンドの音量を変更します。
    //!
    //!           ハンドルに関連付けられたサウンドの音量を変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、他のどの音量パラメータとも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           音量 volume は、0.0 以上の倍率で指定します。
    //!           すなわち、1.0 を指定すると音量に影響を与えません。
    //!           0.0 を指定すると発音されなくなります。デフォルト値は 1.0 です。
    //!
    //!           他の音量パラメータと重ね合わされたあと、
    //!           最終的な音量は 0.0 ～ 2.0 の範囲でクランプされます。
    //!           この関数で 2.0 を設定したとしても、
    //!           元の音量の 2 倍にならない可能性があることに注意してください。
    //!
    //!           音量の変化は frames で指定したフレーム数をかけて行われます。
    //!           音量の変化途中にさらにこの関数を呼び出した場合は、
    //!           その時点での変化途中の音量値を基点として、
    //!           新しく指定したフレーム数をかけて音量を変化させます。
    //!
    //! @param[in]    volume  変更する音量の倍率（ 0.0 ～ ）です。
    //! @param[in]    frames  音量変化にかけるフレーム数です。
    //!                       フレーム数は @ref SoundArchivePlayer::Update
    //!                       の呼び出し回数で換算されます。
    //!
    //! @date 2010/12/24 フレーム数について追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void SetVolume( float volume, int frames = 0 )
    {
        if ( IsAttachedSound() ) m_pSound->SetVolume( volume, frames );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドの音程を変更します。
    //!
    //!           ハンドルに関連付けられたサウンドの音程を変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、他のどの音程パラメータとも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           音程 pitch は、周波数の比率で指定します。
    //!           すなわち、1.0 を指定すると音程に影響を与えません。 
    //!           2.0 を指定すると再生される周波数が 2 倍になり、
    //!           1 オクターブ高い音程になります。
    //!           0.5 を指定すると 1 オクターブ低い音程になります。
    //!
    //!           デフォルト値は 1.0 です。
    //!
    //! @param[in]    pitch  変更する音程の周波数比率です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void SetPitch( float pitch )
    {
        if ( IsAttachedSound() ) m_pSound->SetPitch( pitch );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドのパン（左右の定位）を変更します。
    //!
    //!           ハンドルに関連付けられたサウンドのパンを変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、他のどのパンパラメータとも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           pan は、定位の相対変化の値を設定します。
    //!           0.0 を指定するとデータで設定されたパンの値から変化しません。
    //!           1.0 を指定すると中央に定位していた音が右端に定位するようになり、
    //!           -1.0 を指定すると中央に定位していた音が左端に定位するようになります。
    //!           
    //!           デフォルト値は 0.0 です。
    //!
    //! @param[in]    pan  0.0 を基準としたパンの相対変化の値です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void SetPan( float pan )
    {
        if ( IsAttachedSound() ) m_pSound->SetPan( pan );
    }

    //---------------------------------------------------------------------------
    //! @brief  サウンドのサラウンドパン（前後の定位）を変更します。
    //!
    //!         ハンドルに関連付けられたサウンドのサラウンドパンを変更します。
    //!         ハンドルが無効の場合は、何もしません。
    //!
    //!         この関数で指定する値は、他のどのサラウンドパンパラメータとも独立して動作し、
    //!         それらは全て重ね合わされます。
    //!
    //!         surroundPan は、定位の相対変化の値を設定します。
    //!         0.0 を指定するとデータで設定されたパンの値から変化しません。
    //!         1.0 を指定すると最前方に定位していた音が中央に定位するようになり、
    //!         2.0 を指定すると最前方に定位していた音が最後方に定位するようになります。
    //!         前方へ定位を移動させたい場合は負の値を指定してください。
    //!
    //!         デフォルト値は 0.0 です。
    //! 
    //! @param[in] surroundPan 0.0 を基準としたサラウンドパンの相対変化の値です。
    //!
    //! @date 2010/08/10 初版
    //---------------------------------------------------------------------------
    void SetSurroundPan( float surroundPan )
    {
        if ( IsAttachedSound() ) m_pSound->SetSurroundPan( surroundPan );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドのローパスフィルタカットオフ値を変更します。
    //!
    //!           ハンドルに関連付けられたローパスフィルタカットオフ値を変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、
    //!           他のどのローパスフィルタカットオフパラメータとも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           lpfFreq は、カットオフの相対変化の値を指定します。
    //!           0.0 を指定するとカットオフの値を変更しません。
    //!           -1.0 を指定すると、フィルタがかかっていない状態から、
    //!           もっともフィルタがかかっている状態 (カットオフ周波数が下がる方向)
    //!           に変更します。 
    //!
    //! @param[in] lpfFreq    0.0 を基準としたフィルタカットオフの相対変化の値です。
    //!
    //! @date 2010/10/18 初版
    //---------------------------------------------------------------------------
    void SetLpfFreq( f32 lpfFreq )
    {
        if ( IsAttachedSound() ) m_pSound->SetLpfFreq( lpfFreq );
    }

    //---------------------------------------------------------------------------
    //! @brief  サウンドの biquad フィルタの設定を変更します。
    //!
    //!         ハンドルに関連付けられたサウンドの biquad フィルタの設定を変更します。
    //!         ハンドルが無効の場合は、何もしません。
    //!
    //!         biquad フィルタは複数の箇所での設定が重ね合わされず、
    //!         以下の優先度に従って設定されます。
    //!         優先度が高い箇所でパラメータの設定がされた場合、
    //!         それより下位の設定は上書きされます。
    //!
    //!         (1) サウンドハンドルでの設定 @n
    //!         (2) サウンドプレーヤーでの設定 @n
    //!         (3) アンビエントパラメータ構造体での設定 @n
    //!         (4) シーケンスデータでの設定
    //!
    //!         フィルタの種類 type は @ref BiquadFilterType の値を使用します。
    //!         プリセットで用意されているフィルタの種類の他、
    //!         ユーザーが登録したフィルタを選択することができます。
    //!
    //!         type は 0 ～ BIQUAD_FILTER_TYPE_USER_MAX の値を指定します。
    //!         BIQUAD_FILTER_TYPE_USER_MAX については @ref BiquadFilterType をご参照ください。
    //!         範囲外の値を設定すると、Debug 版 / Development 版ではアサートで停止します。
    //!         Release 版では無視されます。
    //!
    //!         フィルタのかかり具合を指定する value は、
    //!         0.0f ～ 1.0f の値で指定します。
    //!         値の意味はフィルタの係数の種類によって変化します。
    //!
    //! @param[in] type     フィルタの種類です (0 ～ BIQUAD_FILTER_TYPE_USER_MAX)。
    //! @param[in] value    フィルタのかかり具合です (0.0f ～ 1.0f)。
    //!
    //! @see BiquadFilterType
    //!
    //! @date 2010/10/15 初版
    //---------------------------------------------------------------------------
    void SetBiquadFilter( int type, f32 value )
    {
        NW_MINMAX_ASSERT( type, 0 , BIQUAD_FILTER_TYPE_USER_MAX );
        if ( IsAttachedSound() )
        {
            m_pSound->SetBiquadFilter( type, value );
        }
    }
    // MEMO: 以下は NW4R 時代にあった記述。
    //       現状 LPF が未サポートなので、リファレンスには追記しない。
    // -----
    // biquad フィルタは従来の LPF に比べ3倍強の DSP 負荷がかかります。
    // これは、AUX バス1本分のミキサーの負荷とほぼ同等です。
    //
    // TODO: プリセットに対して value がどんな影響を持つのか、それぞれ説明が必要そう。


    //---------------------------------------------------------------------------
    //! @brief    プレイヤープライオリティを変更します。
    //!
    //!           ハンドルに関連付けられたサウンドのプレイヤープライオリティを変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数は、サウンドアーカイブ中のデータで指定されている
    //!           プレイヤープライオリティの値を変更します。
    //!
    //!           priority の値の範囲は 0～127 で、大きいほど優先度が高くなります。 
    //!
    //! @param[in] priority   プレイヤープライオリティの値です。
    //!
    //! @date 2010/01/25 初版
    //---------------------------------------------------------------------------
    void SetPlayerPriority( int priority )
    {
        if ( IsAttachedSound() ) m_pSound->SetPlayerPriority( priority );
    }
    //@}

    //----------------------------------------
    //! @name 出力パラメータ
    //@{

    //---------------------------------------------------------------------------
    //! @brief    サウンドのメインセンド量を変更します。
    //!
    //!           ハンドルに関連付けられたサウンドのメインセンド量を変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、他のどのメインセンド量とも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           メインセンドは、
    //!           出力に送るサウンドの音量をエフェクトセンドの後で調節するパラメータです。
    //!           主に、エフェクトのドライ・ウェット成分のバランスを調整するために使用されます。
    //!
    //!           センド量 send は、相対変化の値を指定します。
    //!           すなわち、0.0 を指定するとセンド量を変更しません。
    //!           -1.0 を指定するとメインバスに最大のセンド量で送られていたサウンドが、
    //!           メインバスに送られないようになります。 デフォルト値は 0.0 です。 
    //!
    //! @param[in] send   0.0 を基準としたセンド量の相対変化の値です。
    //!
    //! @see SetFxSend
    //!
    //! @date 2010/06/16 初版
    //---------------------------------------------------------------------------
    void SetMainSend( float send )
    {
        if ( IsAttachedSound() ) m_pSound->SetMainSend( send );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドのエフェクトセンド量を変更します。
    //!
    //!           ハンドルに関連付けられたサウンドのエフェクトセンド量を変更します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           この関数で指定する値は、他のどのエフェクトセンド量とも独立して動作し、
    //!           それらは全て重ね合わされます。
    //!
    //!           センド量 send は、相対変化の値を指定します。
    //!           すなわち、0.0 を指定するとセンド量を変更しません。
    //!           1.0 を指定すると AUX バスに送られていなかったサウンドが、
    //!           最大のセンド量で送られるようになります。 デフォルト値は 0.0 です。 
    //!
    //! @param[in] bus    センド量を設定する AUX のバスです。
    //! @param[in] send   0.0 を基準としたセンド量の相対変化の値です。
    //!
    //! @see AuxBus
    //! @see SetMainSend
    //!
    //! @date 2010/06/16 初版
    //---------------------------------------------------------------------------
    void SetFxSend( AuxBus bus, float send )
    {
        if ( IsAttachedSound() ) m_pSound->SetFxSend( bus, send );
    }
    //@}

    //----------------------------------------
    //! @name ハンドル操作
    //@{
    //---------------------------------------------------------------------------
    //! @brief    ハンドルにサウンドが関連付けられているかどうかを調べます。
    //!
    //! @return   ハンドルに関連付けられているサウンドがあれば true を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool IsAttachedSound() const { return m_pSound != NULL; }

    // サウンドハンドルからサウンドを解放
    //---------------------------------------------------------------------------
    //! @brief    ハンドルからサウンドを解放します。
    //!
    //!           ハンドルから開放されたサウンドは、
    //!           その後ハンドルを通して操作できないようになります。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void DetachSound();
    //@}

    //----------------------------------------
    //! @name ハンドル操作
    //@{
    //---------------------------------------------------------------------------
    //! @brief    サウンドの ID を設定します。
    //!
    //!           ハンドルに関連付けられたサウンドの ID を設定します。
    //!           ハンドルが無効の場合は、何もしません。
    //!
    //!           @ref SoundArchivePlayer でサウンドを再生すると、
    //!           再生開始時にサウンド ID が自動的に設定されます。
    //!           この関数を呼び出すと、 ID を上書きして変更します。
    //!
    //!           設定した ID を取得するためには @ref GetId を呼び出します。
    //!
    //! @param[in]    id      サウンドを識別する ID です。
    //!
    //! @see      @ref SoundArchivePlayer, @ref GetId
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void SetId( u32 id )
    {
        if ( IsAttachedSound() ) m_pSound->SetId( id );
    }

    //---------------------------------------------------------------------------
    //! @brief    サウンドに設定されている ID を取得します。
    //!
    //!           ハンドルに関連付けられたサウンドに設定されている ID を取得します。
    //!           ハンドルが無効の場合は 0xffffffff を返します。
    //!
    //!           この関数で取得できる ID は @ref SetId で設定された ID です。
    //!
    //! @return   SetId
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetId() const
    {
        if ( IsAttachedSound() ) return m_pSound->GetId();
        return internal::BasicSound::INVALID_ID;
    }

    // アンビエントパラメータ取得
    //! @details :private
    const SoundParam* GetAmbientParam() const
    {
        if ( ! IsAttachedSound() ) return NULL;
        return &m_pSound->GetAmbientParam();
    }
    //@}

    // -----------------------------------------------------------------
    // 非公開関数

    // ハンドルをサウンドに関連付ける
    //! @details :private
    void detail_AttachSound( internal::BasicSound* sound );
    //! @details :private
    void detail_AttachSoundAsTempHandle( internal::BasicSound* sound );

    //! @details :private
    internal::BasicSound* detail_GetAttachedSound() { return m_pSound; }
    //! @details :private
    const internal::BasicSound* detail_GetAttachedSound() const { return m_pSound; }

    // 一時ハンドルを生成する
    //! @details :private
    void detail_DuplicateHandle( SoundHandle* handle );

private:
    NW_DISALLOW_COPY_AND_ASSIGN( SoundHandle );

    internal::BasicSound* m_pSound;
};

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


#endif /* NW_SND_SOUND_HANDLE_H_ */