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

#ifndef NW_SND_SOUND_DATA_MANAGER_H_
#define NW_SND_SOUND_DATA_MANAGER_H_

#include <nw/snd/snd_DisposeCallback.h>
#include <nw/snd/snd_SoundArchive.h>
#include <nw/snd/snd_SoundArchiveLoader.h>
#include <nw/snd/snd_Util.h>

namespace nw {
namespace snd {

class SoundMemoryAllocatable;

namespace internal
{

//! @details :private
class SoundFileManager
{
public:
    virtual const void* GetFileAddress( SoundArchive::FileId fileId ) const = 0;
    virtual const void* GetFileWaveDataAddress( SoundArchive::FileId fileId ) const = 0;
};

} // namespace nw::snd::internal

//---------------------------------------------------------------------------
//! @brief    サウンドアーカイブのデータをロードするためのクラスです。
//!
//! @see SoundArchivePlayer クラス
//!
//! @date 2010/12/28 NW4C-1.3.0 にて全体的にリファレンスがおかしかったのを修正
//! @date 2010/11/12 SetFileAddress 関数を追加
//! @date 2010/04/09 IsDataLoaded 関数を追加
//! @date 2010/02/01 「参照」に SoundArchivePlayer クラス追加
//! @date 2010/01/15 初版
//---------------------------------------------------------------------------
class SoundDataManager : public internal::driver::DisposeCallback,
                         public internal::SoundArchiveLoader
{
public:

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

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

    //----------------------------------------
    //! @name 初期化
    //@{
    //---------------------------------------------------------------------------
    //! @brief    初期化に必要なメモリのサイズを取得します。
    //!
    //! @param[in]    arc     このサウンドデータマネージャを登録するプレイヤーで
    //!                       使用するサウンドアーカイブです。
    //!
    //! @return   初期化に必要なメモリのサイズを返します。
    //!
    //! @see Initialize
    //!
    //! @date 参照から SoundArchivePlayer::Initialize を削除
    //! @date 2010/02/01 関数名変更 (Setup → Initialize) にともなう文言の調整
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    size_t GetRequiredMemSize( const SoundArchive* arc ) const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドデータマネージャの初期化を行います。
    //!
    //!           サウンドデータマネージャを使用する前に初期化を行う必要があります。
    //!           初期化を行うことにより、
    //!           サウンドデータマネージャがサウンドアーカイブと関連付けられ、
    //!           サウンドアーカイブプレイヤーに登録することができます。
    //!
    //!           サウンドデータマネージャが必要とするメモリのサイズは
    //!           @ref GetRequiredMemSize で取得することができます。
    //!
    //! @param[in]    arc     このサウンドデータマネージャを登録するプレイヤーで
    //!                       使用するサウンドアーカイブです。
    //! @param[out]   buffer  バッファへのポインタです。
    //!                       4 バイトアライメントされている必要があります。
    //! @param[in]    size    バッファサイズです。
    //!
    //! @return   初期化に成功したら true を、失敗したら false を返します。
    //!
    //! @see GetRequiredMemSize
    //! @see Finalize
    //!
    //! @date 2010/02/01 関数名変更 (Setup → Initialize)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool Initialize( const SoundArchive* arc, void* buffer, u32 size );

    //---------------------------------------------------------------------------
    //! @brief    サウンドデータマネージャを破棄します。
    //!
    //! @see Initialize
    //!
    //! @date 2010/02/01 関数名変更 (Shutdown → Finalize)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    void Finalize();
    //@}

    //! @details :private
    void detail_SetFileManager( internal::SoundFileManager* fileManager )
    {
        m_pFileManager = fileManager;
    }

    //----------------------------------------
    //! @name ロード
    //@{
    //---------------------------------------------------------------------------
    //! @brief  独自にロードしたデータを、ファイル管理テーブルに登録します。
    //!
    //!         あらかじめ別のアドレスが登録されている場合は、
    //!         上書きされます。
    //!
    //!         引数として渡すファイル ID は、
    //!         @ref SoundArchive::GetItemFileId 関数で、
    //!         アイテム ID から変換することができます。
    //!
    //!         ファイル管理テーブルに登録することによって、
    //!         当該データを使ったサウンド再生が可能になります。
    //!         詳しくは demos/snd/externalFile デモ、
    //!         および当該デモのドキュメントをご覧ください。
    //!
    //! @param[in] fileId   セットするデータのファイル ID です。
    //! @param[in] address  関連するデータを確認するかを示すフラグです。
    //!
    //! @return   あらかじめ登録されていたアドレスを返します。
    //!
    //! @see SoundArchive::GetItemFileId
    //!
    //! @date 2010/12/28 fileId 引数の説明を修正
    //! @date 2010/12/17 SoundArchive::GetItemFileId 関数との関係を追記
    //! @date 2010/11/12 初版
    //---------------------------------------------------------------------------
    const void* SetFileAddress( SoundArchive::FileId fileId, const void* address );
    //@}

    //! @details :private
    const void* detail_GetFileAddress( SoundArchive::FileId fileId ) const;

    //! @details :private
    u32 detail_GetFileIdFromTable( const void* address ) const;


    // 外部ロードしたサウンドデータを破棄する直前に呼び、データ・インスタンスを無効化する
    //! @details :private
    // void InvalidateSoundData( void* mem, size_t size );

protected:
    //! @details :private
    virtual void InvalidateData( const void* start, const void* end );

    //! @details :private
    virtual const void* SetFileAddressToTable(
            SoundArchive::FileId fileId, const void* address );
    //! @details :private
    virtual const void* GetFileAddressFromTable( SoundArchive::FileId fileId ) const;

    //! @details :private
    virtual const void* GetFileAddressImpl( SoundArchive::FileId fileId ) const;
        // テーブルを含め、アクセス可能な箇所にデータが読み込まれているかを確認する

private:
    //! @details :private
    struct FileAddress
    {
        const void* address;
    };

    //! @details :private
    typedef internal::Util::Table<FileAddress> FileTable;

    //! @details :private
    bool CreateFileAddressTable( const SoundArchive* arc, void** buffer, void* endp );

    //! @details :private
    FileTable* m_pFileTable;

    //! @details :private
    internal::SoundFileManager* m_pFileManager;
};

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


#endif /* NW_SND_SOUND_DATA_MANAGER_H_ */