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

#ifndef NW_SND_SOUND_STARTABLE_H_
#define NW_SND_SOUND_STARTABLE_H_

#include <nw/snd/snd_SoundArchive.h>

namespace nw {
namespace snd {

class SoundHandle;


// 再生可能なことを表すインターフェイスです。
// 純粋仮想関数 detail_SetupSoundImpl() 及び detail_ConvertLabelStringToItemId() を
// 継承したクラスで実装することにより、そのクラスで
// StartSound(), HoldSound(), PrepareSound() 関数が使用できるようになります。

//---------------------------------------------------------------------------
//! @brief        サウンドの再生が可能なことを表す抽象クラスです。
//!
//! @date 2010/01/15 初版
//---------------------------------------------------------------------------
class SoundStartable
{
public:
    //---------------------------------------------------------------------------
    //! @brief    サウンド再生処理結果を表すクラスです。
    //!
    //!           START_ERR_NOT_ENOUGH_INSTANCE は、
    //!           再生しようとしたサウンドに必要な数のインスタンスが 
    //!           作られていないことを表します。
    //!           サウンドアーカイブを使って再生している場合は、
    //!           サウンドアーカイブ中に設定されている
    //!           インスタンス数を増やす必要があります。
    //!           
    //! @see SoundStartable::StartSound.
    //! @see SoundStartable::HoldSound
    //! @see SoundStartable::PrepareSound
    //! 
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    class StartResult
    {
    public:
        //---------------------------------------------------------------------------
        //! @brief    サウンド再生処理結果を表すコードです。
        //!     
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        enum ResultCode
        {
            //! 再生は成功しました。
            START_SUCCESS = 0,

            START_ERR_LOW_PRIORITY,
            START_ERR_INVALID_LABEL_STRING,
            START_ERR_INVALID_SOUNDID,
            START_ERR_NOT_DATA_LOADED,
            START_ERR_NOT_SEQ_LOADED,
            START_ERR_NOT_BANK_LOADED,
            START_ERR_NOT_WSD_LOADED,
            START_ERR_NOT_WARC_LOADED,
            START_ERR_NOT_ENOUGH_PLAYER_HEAP,
            START_ERR_CANNOT_OPEN_FILE,
            START_ERR_NOT_AVAILABLE,
            START_ERR_CANNOT_ALLOCATE_TRACK,    // 未使用
            START_ERR_NOT_ENOUGH_INSTANCE,
            START_ERR_INVALID_PARAMETER,
            START_ERR_INVALID_SEQ_START_LOCATION_LABEL,
            START_ERR_ACTOR_NOT_INITIALIZED,
            START_ERR_USER = 128,
            START_ERR_UNKNOWN = 255
        };

        //! @details :private
        StartResult() : m_Code( START_ERR_UNKNOWN ) {}

        //! @details :private
        StartResult( ResultCode code ) : m_Code( code ) {}

        //---------------------------------------------------------------------------
        //! @brief    再生成功したかどうかを取得します。
        //!
        //! @return   再生成功したら true, 失敗したら false を返します。
        //!
        //! @see SoundStartable::StartSound
        //! @see SoundStartable::HoldSound
        //! @see SoundStartable::PrepareSound
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        bool IsSuccess() const { return m_Code == START_SUCCESS; }

        //---------------------------------------------------------------------------
        //! @brief    再生処理結果コードを取得します。
        //!
        //! @return   再生処理結果コードを返します。
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        ResultCode GetCode() const { return m_Code; }

    private:
        ResultCode m_Code;
    };

    // static const char* detail_ConvertStartResultToString( StartResult startResult );

    //---------------------------------------------------------------------------
    //! @brief    サウンド再生時に渡される、詳細な再生パラメータです。
    //!
    //!           @ref SoundStartable::StartSound 等の関数に渡して使用します。
    //!           この構造体を使用しなくてもサウンドは再生出来ます。 
    //!
    //!           startOffsetType, startOffset を設定すると、
    //!           サウンドを途中から再生することが可能です。
    //!           この 2 つのパラメータは同時に設定する必要があります。
    //!           設定した値を有効にするには、
    //!           enableFlag の ENABLE_START_OFFSET ビットを設定してください。 
    //!
    //!           オフセット値が同じでも、
    //!           データの種類によって途中再生のために必要な処理時間が異なります。
    //!           大きな処理時間がかかる場合があることに注意してください。
    //!
    //!           【シーケンスサウンド】 @n
    //!           シーケンスを途中まで空回しするため、
    //!           開始オフセットの大きさに応じた処理時間がかかります。
    //!
    //!           【ストリームサウンド】 @n
    //!           データが PCM の場合は、開始オフセットの大きさに関わらず、
    //!           途中再生のための処理時間はほとんどかかりません。
    //!           データが ADPCM の場合は、最大 14336 サンプルのデータを
    //!           CPU でデコードするための処理がかかります。
    //!
    //!           【ウェーブサウンド】 @n
    //!           データが PCM の場合は、開始オフセットの大きさに関わらず、
    //!           途中再生のための処理時間はほとんどかかりません。
    //!           データが ADPCM の場合は、
    //!           データ先頭から再生開始位置までの全てのサンプルを
    //!           CPU でデコードする必要があるため、
    //!           開始オフセットの大きさに応じた処理時間がかかります。 
    //!
    //!           サウンドはサウンドアーカイブ中で設定された
    //!           ID のプレイヤーを使用して再生されますが、
    //!           これとは異なるプレイヤーを指定して再生したい場合、
    //!           playerId を設定します。設定した値を有効にするには、
    //!           enableFlag の ENABLE_PLAYER_ID ビットを設定してください。
    //!
    //!           サウンドはサウンドアーカイブ中で設定された
    //!           プレイヤープライオリティを使用して再生されますが、
    //!           これとは異なるプライオリティ値を指定して再生したい場合、
    //!           playerPriority を設定します。設定した値を有効にするには、
    //!           enableFlag の ENABLE_PLAYER_PRIORITY ビットを設定してください。
    //!
    //!           actorPlayerId は、@ref SoundActor 
    //!           クラスで再生する際に使用するアクタープレイヤー番号を設定します。
    //!           値の範囲は 0 ～ 3 です。設定した値を有効にするには、
    //!           enableFlag の ENABLE_ACTOR_PLAYER_ID ビットを設定してください。
    //!           (NW4C-0.4.1 現在、この値を設定しても効果はありません)
    //!
    //!           seqSoundInfo は、シーケンスサウンドに関するパラメータです。
    //!           シーケンスサウンドを再生するときにのみ有効です。
    //!           サウンドアーカイブ中で設定されている、
    //!           シーケンスサウンドに関する情報を上書きすることができます。
    //!           詳しくは SeqSoundInfo 構造体を参照してください。
    //!           設定した値を有効にするには、 enableFlag の ENABLE_SEQ_SOUND_INFO
    //!           ビットを設定してください。 
    //! 
    //! @see  SoundStartable::StartSound
    //!
    //! @date 2010/01/25 初版
    //---------------------------------------------------------------------------
    struct StartInfo
    {
        //---------------------------------------------------------------------------
        //! @brief    StartInfo 構造体のパラメータを有効にするためのビットフラグの定義です。
        //!
        //!           それぞれの値の論理和をとって使用します。 
        //!
        //! @see      SoundStartable::StartInfo
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        enum EnableFlagBit
        {
            /*!
              @brief    startOffsetType, startOffset に設定された値を有効にします。
                        2 つのパラメータは同時に設定する必要があります。
             */
            ENABLE_START_OFFSET      = 0x00000001,

            //! playerId に設定された値を有効にします。 
            ENABLE_PLAYER_ID         = 0x00000002,

            //! playerPriority に設定された値を有効にします。 
            ENABLE_PLAYER_PRIORITY   = 0x00000004,

            //!  actorPlayerId に設定された値を有効にします。 
            ENABLE_ACTOR_PLAYER_ID   = 0x00000008,

            //! seqSoundInfo に設定された値を有効にします。 
            ENABLE_SEQ_SOUND_INFO    = 0x00000010
        };

        //---------------------------------------------------------------------------
        //! @brief    サウンドの開始オフセット値の単位の定義です。
        //!
        //! @see      SoundStartable::StartInfo
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        enum StartOffsetType
        {
            START_OFFSET_TYPE_MILLISEC, //!< オフセット値の単位はミリ秒です。 

            /*!
                @brief  オフセット値の単位は Tick です。
                        この指定はシーケンスサウンドに対してのみ有効です。
                        それ以外では、オフセット値の指定が無効になります。 
             */
            START_OFFSET_TYPE_TICK,

            /*!
                @brief  オフセット値の単位は波形のサンプル数です。
                        この指定はストリームサウンドとウェーブサウンドに対して有効です。
                        それ以外では、オフセット値の指定が無効になります。 
             */
            START_OFFSET_TYPE_SAMPLE
        };

        //---------------------------------------------------------------------------
        //! @brief    シーケンスサウンドに関するパラメータ構造体です。
        //!
        //!           シーケンスサウンド再生時に渡されるます。
        //!
        //!           seqDataAddress にシーケンスデータのアドレスを指定すると、
        //!           サウンドアーカイブ中で設定されているシーケンスデータの代わりに、
        //!           メモリ上に置かれたシーケンスデータをアドレスで指定して再生することができます。
        //!           NULL を指定すると、
        //!           元々サウンドアーカイブで設定されているシーケンスデータを再生します。
        //!
        //!           startLocationLabel には、シーケンスデータ内の再生開始位置を指定します。
        //!           サウンドアーカイブ中で設定されているラベル文字列の代わりに、
        //!           ここで指定した文字列を使用するようになります。
        //!           NULL を指定すると、
        //!           元々サウンドアーカイブで設定されている再生開始位置を使用して再生します。 
        //!
        //!           bankIds には、シーケンスデータと関連付けるバンク ID を指定します。
        //!           サウンドアーカイブ中で設定されているバンク ID の代わりに、
        //!           ここで指定した ID を仕様するようになります。
        //!           NULL を指定すると、
        //!           元々サウンドアーカイブで設定されているバンク ID を仕様して再生します。
        //!
        //! @see      SoundStartable::StartInfo
        //!
        //! @date 2010/01/15 初版
        //---------------------------------------------------------------------------
        struct SeqSoundInfo
        {
            //! シーケンスデータのアドレスです。 
            const void* seqDataAddress;

            //! シーケンスデータ内の再生開始位置を示すラベル文字列です。 
            const char* startLocationLabel;

            //! シーケンスデータと関連付けるバンク ID です。
            SoundArchive::ItemId bankIds[ SoundArchive::SEQ_BANK_MAX ];

            //! コンストラクタです。
            SeqSoundInfo() : seqDataAddress( NULL ), startLocationLabel( NULL )
            {
                for ( int i = 0; i < SoundArchive::SEQ_BANK_MAX; i++ )
                {
                    bankIds[ i ] = SoundArchive::INVALID_ID;
                }
            }
        };

        /*!
            @brief  構造体に設定された値を有効にするためのビットフラグです。
                    デフォルト値では全て無効になっています。 
         */
        u32 enableFlag;                     

        //! サウンドの開始オフセット値の単位です。 
        StartOffsetType startOffsetType;

        //! サウンドの開始オフセット値です。
        int startOffset;

        //! サウンドの再生に使用するプレイヤーの ID です。 
        SoundArchive::ItemId playerId;

        //! サウンドに設定するプレイヤープライオリティです。 
        int playerPriority;

        /*!
            @brief  SoundActorで再生する場合に使用するアクタープレイヤーの番号です。
                    (NW4C-0.4.1 現在、設定しても効果はありません)
         */
        int actorPlayerId;

        //! シーケンスサウンドに関するパラメータです。 
        SeqSoundInfo seqSoundInfo;

        //! コンストラクタです
        StartInfo() : enableFlag( 0 ) {}
    };

    /* ------------------------------------------------------------------------
            member definition
       ------------------------------------------------------------------------ */
    // デストラクタ
    //! @details :private
    virtual ~SoundStartable() {};

    //----------------------------------------
    //! @name 再生
    //@{
    // 再生関数
    //---------------------------------------------------------------------------
    //! @brief  指定した ID のサウンドを再生します。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!         再生に成功したサウンドは、このサウンドハンドルと関連付けられます。
    //!
    //!         第二引数には、再生するサウンドの識別子としてサウンド ID を指定します。
    //!
    //!         pStartInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         この関数を呼び出すことは、@ref PrepareSound を呼び出した後、
    //!         すぐにハンドルクラスの @ref SoundHandle::StartPrepared
    //!         を呼び出すことと同じです。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] soundId        再生するサウンドの ID です。
    //! @param[in] pStartInfo     詳細な再生パラメータです。
    //!
    //! @return   再生処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see PrepareSound
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult StartSound(
            SoundHandle* pHandle,
            SoundArchive::ItemId soundId,
            const StartInfo* pStartInfo = NULL );

    //---------------------------------------------------------------------------
    //! @brief  指定したラベル文字列のサウンドを再生します。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!         再生に成功したサウンドは、このサウンドハンドルと関連付けられます。
    //!
    //!         第二引数には、再生するサウンドの識別子として、
    //!         サウンドのラベル文字列を指定します。
    //!
    //!         pStartInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         この関数を呼び出すことは、@ref PrepareSound を呼び出した後、
    //!         すぐにハンドルクラスの @ref SoundHandle::StartPrepared
    //!         を呼び出すことと同じです。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] pSoundName     再生するサウンドのラベル文字列です。
    //! @param[in] pStartInfo     詳細な再生パラメータです。
    //!
    //! @return   再生処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see PrepareSound
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult StartSound(
            SoundHandle* pHandle,
            const char* pSoundName,
            const StartInfo* pStartInfo = NULL );

    //---------------------------------------------------------------------------
    //! @brief  指定した ID のサウンドを再生または継続します。
    //!
    //!         同じ ID で毎フレームこの関数を呼び続けている間、
    //!         サウンドを再生することができます。
    //!         呼び出しが途切れた時はサウンドが停止します。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!
    //!         第二引数には、再生するサウンドの識別子としてサウンド ID を指定します。
    //!
    //!         pHoldInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] soundId        再生するサウンドの ID です。
    //! @param[in] pHoldInfo      詳細な再生パラメータです。
    //!
    //! @return   再生処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult HoldSound(
            SoundHandle* pHandle,
            SoundArchive::ItemId soundId,
            const StartInfo* pHoldInfo = NULL );

    //---------------------------------------------------------------------------
    //! @brief  指定したラベル文字列のサウンドを再生または継続します。
    //!
    //!         同じ ID で毎フレームこの関数を呼び続けている間、
    //!         サウンドを再生することができます。
    //!         呼び出しが途切れた時はサウンドが停止します。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!
    //!         第二引数には、再生するサウンドの識別子として、
    //!         サウンドのラベル文字列を指定します。
    //!
    //!         pHoldInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] pSoundName     再生するサウンドのラベル文字列です。
    //! @param[in] pHoldInfo      詳細な再生パラメータです。
    //!
    //! @return   再生処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult HoldSound(
            SoundHandle* pHandle,
            const char* pSoundName,
            const StartInfo* pHoldInfo = NULL );

    //---------------------------------------------------------------------------
    //! @brief  指定した ID のサウンドを再生する準備をします。
    //!
    //!         準備が完了したサウンドは、ハンドルクラスの
    //!         @ref SoundHandle::StartPrepared
    //!         を呼び出して再生を開始することができます。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!         再生に成功したサウンドは、このサウンドハンドルと関連付けられます。
    //!
    //!         第二引数には、再生するサウンドの識別子としてサウンド ID を指定します。
    //!
    //!         pStartInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] soundId        再生するサウンドの ID です。
    //! @param[in] pStartInfo     詳細な再生パラメータです。
    //!
    //! @return   再生準備処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see StartSound
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult PrepareSound(
            SoundHandle* pHandle,
            SoundArchive::ItemId soundId,
            const StartInfo* pStartInfo = NULL );

    //---------------------------------------------------------------------------
    //! @brief  指定したラベル文字列のサウンドを再生する準備をします。
    //!
    //!         準備が完了したサウンドは、ハンドルクラスの
    //!         @ref SoundHandle::StartPrepared
    //!         を呼び出して再生を開始することができます。
    //!
    //!         第一引数には、サウンドハンドルを指定します。
    //!         再生に成功したサウンドは、このサウンドハンドルと関連付けられます。
    //!
    //!         第二引数には、再生するサウンドの識別子として、
    //!         サウンドのラベル文字列を指定します。
    //!
    //!         pStartInfo は、再生時に設定できる詳細なパラメータです。
    //!         このパラメータは、設定せずに再生を開始することが可能です。
    //!
    //!         現在、未実装のため、pStartInfo を使ったサウンドの途中再生には対応していません。
    //!
    //! @param[in] pHandle        再生されるサウンドと関連付けられるハンドルです。
    //! @param[in] pSoundName     再生するサウンドのラベル文字列です。
    //! @param[in] pStartInfo     詳細な再生パラメータです。
    //!
    //! @return   再生準備処理結果を @ref StartResult 型で返します。
    //!
    //! @see SoundHandle クラス
    //! @see StartResult
    //! @see StartSound
    //! @see StartInfo
    //!
    //! @date 2010/07/27 pStartInfo を使ったサウンドの途中再生に未対応の旨、追記
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    StartResult PrepareSound(
            SoundHandle* pHandle,
            const char* pSoundName,
            const StartInfo* pStartInfo = NULL );
    //@}

protected:
    //! @details :private
    virtual StartResult detail_SetupSound(
        SoundHandle* handle,
        u32 soundId,
        bool holdFlag,
        const StartInfo* startInfo
    ) = 0;
    //! @details :private
    virtual SoundArchive::ItemId detail_GetItemId( const char* pString ) = 0;
};

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

#endif /* NW_SND_SOUND_STARTABLE_H_ */