xref: /NW4C-2.0.3/include/nw/snd/snd_SoundArchive.h

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

#ifndef NW_SND_SOUND_ARCHIVE_H_
#define NW_SND_SOUND_ARCHIVE_H_

#include <nn/types.h>
#include <nw/snd/snd_Global.h>
#include <nw/snd/snd_Util.h>
#include <nw/snd/snd_ItemType.h>

namespace nw {

namespace io {
class FileStream;
} // namespace nw::io

namespace snd {

namespace internal {
class SoundArchiveFileReader;
} // namespace nw::snd::internal


//---------------------------------------------------------------------------
//! @brief        サウンドアーカイブを扱うクラスです。
//!
//!               ユーザーがこのクラスを直接扱うことはできません。
//!               このクラスを継承した @ref RomSoundArchive クラス、
//!               または @ref MemorySoundArchive クラスを使用してください。
//!
//! @see RomSoundArchive
//! @see MemorySoundArchive
//!
//! @date 2010/02/23 ヘッダーを追記
//! @date 2010/01/29 「参照」追加
//! @date 2010/01/15 初版
//---------------------------------------------------------------------------
class SoundArchive
{
public:
    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブの中でのアイテム ID を示す型です。
    //!
    //!           サウンド、バンク、プレイヤー、グループ、波形アーカイブに、
    //!           重複しないアイテム ID が割り振られています。
    //!
    //! @see GetItemLabel
    //! @see GetItemId
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    typedef u32 ItemId;

    //---------------------------------------------------------------------------
    //! @brief    無効な ID を表す値です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static const ItemId INVALID_ID = 0xffffffff;

    //---------------------------------------------------------------------------
    //! @brief    サウンドの種類を表す型です。
    //!
    //! @see GetSoundType
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    enum SoundType
    {
        SOUND_TYPE_INVALID = 0,     //!< 不正な種類のサウンドです。

        SOUND_TYPE_SEQ,             //!< シーケンスサウンドです。
        SOUND_TYPE_STRM,            //!< ストリームサウンドです。
        SOUND_TYPE_WAVE             //!< ウェーブサウンドです。
    };

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブの中でのファイル ID を示す型です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    typedef ItemId FileId;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブの中での文字列 ID を示す型です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    typedef ItemId StringId;

    //---------------------------------------------------------------------------
    //! @brief  サウンドの設定情報の構造体です。
    //!
    //!         isFrontBypass が true で、@ref SoundSystem::SetOutputMode
    //!         で設定する出力モードが OUTPUT_MODE_SURROUND の場合、
    //!         当該サウンドはフロントチャンネルをバイパスします。
    //!
    //! @see ReadSoundInfo
    //! @see FileId
    //! @see ItemId
    //! @see PanMode
    //! @see PanCurve
    //! @see nn::snd::Voice::SetFrontBypassFlag
    //!
    //! @date 2010/07/14 isFrontBypass 追加
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct SoundInfo
    {
        FileId fileId;      //!< サウンドアーカイブ内でのファイル ID です。
        ItemId playerId;    //!< サウンドを再生するときに使用されるプレイヤーの ID です。

        //! アクターでサウンドを再生するときに使用されるアクタープレイヤーの番号です。
        int actorPlayerId;

        int playerPriority; //!< サウンドを再生するときのプレイヤープライオリティの値です。
        int volume;         //!< サウンドを再生するときの音量です。
        PanMode panMode;    //!< パンモードの種類です。
        PanCurve panCurve;  //!< パンのカーブの種類です。

        bool isFrontBypass; //!< フロントバイパスするか否かを示すフラグです。
    };

    //---------------------------------------------------------------------------
    //! @brief    サウンドの 3D サウンド設定情報の構造体です。
    //!
    //! @see ReadSound3DInfo
    //!
    //! @date 2010/11/30 FLAG_CTRL_*** を static const u32 から enum に変更
    //! @date 2010/03/05 初版
    //---------------------------------------------------------------------------
    struct Sound3DInfo
    {
        //---------------------------------------------------------------------------
        //! @brief    3D 減衰カーブの形状を示す列挙体です。
        //!
        //! @date 2010/03/05 初版
        //---------------------------------------------------------------------------
        enum DecayCurve
        {
            DECAY_CURVE_LOG    = 1, //!< 対数カーブです。
            DECAY_CURVE_LINEAR = 2  //!< リニア (直線) です。
        };

        //---------------------------------------------------------------------------
        //! @brief    3D サウンドで各パラメータを計算するかどうかを示すフラグです。
        //!
        //! @date 2010/11/30 初版
        //---------------------------------------------------------------------------
        enum FlagCtrl
        {
            FLAG_CTRL_VOLUME   = (1 << 0), //!< 音量を計算するかどうかを示すフラグです。
            FLAG_CTRL_PRIORITY = (1 << 1), //!< プライオリティを計算するかどうかを示すフラグです。
            FLAG_CTRL_PAN      = (1 << 2), //!< パンを計算するかどうかを示すフラグです。
            FLAG_CTRL_SPAN     = (1 << 3), //!< サラウンドパンを計算するかどうかを示すフラグです。
            FLAG_CTRL_FILTER   = (1 << 4)  //!< biquad フィルタを計算するかどうかを示すフラグです。
        };

        //---------------------------------------------------------------------------
        //! @brief    3D 計算で処理するパラメータを表現するビットフラグです。
        //!           FLAG_CTRL_*** の論理和で表現されます。
        //---------------------------------------------------------------------------
        u32 flags;
        f32 decayRatio;     //!< 3D 減衰率です。
        u8 decayCurve;      //!< 3D 減衰カーブの形状です。@ref DecayCurve が格納されます。
        u8 dopplerFactor;   //!< 3D ドップラーファクターです。
    };

    //---------------------------------------------------------------------------
    //! @brief    シーケンスサウンドに関連付けられるバンクの最大数です。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    static const u32 SEQ_BANK_MAX = 4;

    //---------------------------------------------------------------------------
    //! @brief    シーケンスサウンドの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           シーケンスサウンドの情報を取得するための構造体です。
    //!
    //! @see ReadSequenceSoundInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct SequenceSoundInfo
    {
        u32 startOffset;                //!< 非公開です。ライブラリ内部で使用されています。
        u32 bankIds[ SEQ_BANK_MAX ];    //!< シーケンスサウンドで使用されるバンク ID です。

        //---------------------------------------------------------------------------
        //! @brief    シーケンスサウンドに含まれるトラックのビットフラグです。
        //!           下位ビットから順にトラック 0, トラック 1, トラック 2,... を表します。
        //---------------------------------------------------------------------------
        u32 allocateTrackFlags;

        //! シーケンスサウンドで発音される音のチャンネルプライオリティの値です。
        u8  channelPriority;

        //---------------------------------------------------------------------------
        //! @brief    シーケンスサウンドで発音される音が、
        //!           リリース時にプライオリティを固定されるかどうかのフラグです。
        //!           固定しない場合はリリース時にプライオリティが下がります。
        //---------------------------------------------------------------------------
        bool isReleasePriorityFix;

        //! コンストラクタです。
        SequenceSoundInfo()
        : startOffset( 0 ),
          allocateTrackFlags( 0 ),
          channelPriority( 0 ),
          isReleasePriorityFix( false )
        {
            for ( u32 i = 0; i < SEQ_BANK_MAX; i++ )
            {
                bankIds[ i ] = INVALID_ID;
            }
        }
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    ストリームサウンドの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           ストリームサウンドの情報を取得するための構造体です。
    //!
    //! @see detail_ReadStreamSoundInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct StreamSoundInfo
    {
        u16 allocTrackCount;
        u16 allocChannelCount;

        //! コンストラクタです。
        StreamSoundInfo()
        : allocTrackCount( 0 ),
          allocChannelCount( 0 )
        {}
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    ウェーブサウンドの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           ウェーブサウンドの情報を取得するための構造体です。
    //!
    //! @see detail_ReadWaveSoundInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct WaveSoundInfo
    {
        u32     index;              // ウェーブサウンドセットファイル (bcwsd) 内で何番目か
        u32     allocTrackCount;    // 現状は 1。今後マルチトラック化した場合、ほかの値が入る
        u8      channelPriority;
        bool    isReleasePriorityFix;

        //! コンストラクタです。
        WaveSoundInfo()
        : allocTrackCount( 0 ),
          channelPriority( 0 ),
          isReleasePriorityFix( false ) {}
    };

    //---------------------------------------------------------------------------
    //! @brief    バンクの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           バンクの情報を取得するための構造体です。
    //!
    //! @see ReadBankInfo
    //! @see FileId
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct BankInfo
    {
        FileId fileId;              //!< サウンドアーカイブ内でのファイル ID です。

        //! コンストラクタです。
        BankInfo() : fileId( INVALID_ID ) {}
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    波形アーカイブの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           波形アーカイブの情報を取得するための構造体です。
    //!
    //! @see ReadWaveArchiveInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct WaveArchiveInfo
    {
        u32  fileId;
        u32  waveCount;
        bool isLoadIndividual;
        u8   padding1;
        u16  padding2;

        //! コンストラクタです。
        WaveArchiveInfo() : fileId( INVALID_ID ), isLoadIndividual( false ) {}
    };

    //---------------------------------------------------------------------------
    //! @brief    プレイヤーの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           プレイヤーの情報を取得するための構造体です。
    //!
    //! @see ReadPlayerInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct PlayerInfo
    {
        int playableSoundMax;   //!< プレイヤーで同時に再生できるサウンドの数です。
        u32 playerHeapSize;     //!< プレイヤーに割り当てられるプレイヤーヒープのサイズです。

        //! コンストラクタです。
        PlayerInfo()
        : playableSoundMax( 0 ),
          playerHeapSize( 0 ) {}
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    ウェーブサウンドセット・シーケンスサウンドセットの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           ウェーブサウンドセット・シーケンスサウンドセットの情報を
    //!           取得するための構造体です。
    //!
    //! @see detail_ReadSoundGroupInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct SoundGroupInfo
    {
        ItemId startId;
        ItemId endId;
        const internal::Util::Table<ut::ResU32>* fileIdTable;

        //! コンストラクタです。
        SoundGroupInfo()
        : startId( INVALID_ID ),
          endId( INVALID_ID ),
          fileIdTable( NULL ) {}
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    グループの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           グループの情報を取得するための構造体です。
    //!
    //! @see detail_ReadGroupInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct GroupInfo
    {
        FileId fileId;
        GroupInfo() : fileId( INVALID_ID ) {}
    };

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブプレイヤーの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           サウンドアーカイブプレイヤーの情報を取得するための構造体です。
    //!
    //! @see ReadSoundArchivePlayerInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct SoundArchivePlayerInfo
    {
        int sequenceSoundMax;   //!< 確保するシーケンスサウンドインスタンスの数です。
        int sequenceTrackMax;   //!< 確保するシーケンストラックインスタンスの数です。
        int streamSoundMax;     //!< 確保するストリームサウンドインスタンスの数です。
        int streamTrackMax;     //!< 確保するストリームトラックインスンスの数です。
        int streamChannelMax;   //!< 確保するストリームチャンネルインスタンスの数です。
        int waveSoundMax;       //!< 確保するウェーブサウンドインスタンスの数です。
        int waveTrackMax;       //!< 確保するウェーブサウンドトラックの数です。
    };

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    ファイルの設定情報の構造体です。
    //!
    //!           サウンドアーカイブで定義されている、
    //!           ファイルの情報を取得するための構造体です。
    //!
    //! @see detail_ReadFileInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    struct FileInfo
    {
        u32 fileSize;
        u32 offsetFromFileBlockHead;
        const char* externalFilePath;

        FileInfo()
        : fileSize( 0xffffffff ),
          offsetFromFileBlockHead( 0xffffffff ),
          externalFilePath( NULL )
        {}
    };

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

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

    //@}

public:
    //----------------------------------------
    //! @name 状態取得
    //@{
    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中のデータが利用可能な状態か調べます。
    //!
    //! @return   サウンドアーカイブ中のデータが利用可能な状態なら true を、
    //!           そうでなければ false を返します。
    //!
    //! @date 2010/11/12 誤植修正 (サウンドアーカイブ中のの→サウンドアーカイブ中の)
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool IsAvailable() const;
    //@}

    //----------------------------------------
    //! @name ID / ラベル文字列
    //@{
    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中のサウンドの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のサウンドの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetSoundCount() const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中のグループの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のグループの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetGroupCount() const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中のプレイヤーの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のプレイヤーの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetPlayerCount() const;

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    サウンドアーカイブ中のウェーブサウンドセット・
    //!           シーケンスサウンドセットの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のウェーブサウンドセット・
    //!           シーケンスサウンドセットの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetSoundGroupCount() const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中のバンクの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のバンクの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetBankCount() const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブ中の波形アーカイブの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中の波形アーカイブの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 GetWaveArchiveCount() const;

    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief    サウンドアーカイブ中のファイルの個数を取得します。
    //!
    //! @return   サウンドアーカイブ中のファイルの個数を返します。
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    u32 detail_GetFileCount() const;

    //---------------------------------------------------------------------------
    //! @brief  アイテム ID から、対応するラベル文字列を取得します。
    //!
    //!         指定したアイテム ID が存在しない場合は、NULL を返します。
    //!
    //!         @ref MemorySoundArchive、@ref RomSoundArchive 問わず、
    //!         文字列情報を利用する場合は、
    //!         サウンドアーカイブファイルに文字列テーブルが含まれている必要があります。
    //!
    //!         サウンドアーカイブファイルに文字列テーブルを含めるには、
    //!         SoundMaker の [プロジェクト設定] - [サウンドアーカイブ] タブ -
    //!         [文字列テーブルを出力する] にチェックをつけておいてください。
    //!
    //!         @ref RomSoundArchive 使用時は、あらかじめ
    //!         @ref RomSoundArchive::LoadLabelStringData でラベル文字列データを
    //!         ロードしておく必要があります。
    //!         文字列データをロードしていない無い場合は、NULL を返します。
    //!
    //!         @ref MemorySoundArchive に文字列テーブルが含まれていない場合は、
    //!         NULL を返します。
    //!
    //! @param[in]    id      サウンドアーカイブ内のアイテム ID です。
    //!
    //! @return   指定した ID に対応したラベル文字列を返します。
    //!
    //! @see ItemId
    //! @see GetItemId
    //! @see RomSoundArchive::LoadLabelStringData
    //!
    //! @date 2010/09/21 存在しない ID やラベル文字列が含まれていない場合など、NULL を返す旨追記
    //! @date 2010/06/25 サウンドアーカイブの文字列テーブルに関する記述を追加
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    const char* GetItemLabel( ItemId id ) const;

    //---------------------------------------------------------------------------
    //! @brief  ラベル文字列から、対応するアイテム ID に変換します。
    //!
    //!         指定したラベル文字列が存在しない場合は、
    //!         @ref INVALID_ID を返します。
    //!
    //!         @ref MemorySoundArchive、@ref RomSoundArchive 問わず、
    //!         文字列情報を利用する場合は、
    //!         サウンドアーカイブファイルに文字列テーブルが含まれている必要があります。
    //!
    //!         サウンドアーカイブファイルに文字列テーブルを含めるには、
    //!         SoundMaker の [プロジェクト設定] - [サウンドアーカイブ] タブ -
    //!         [文字列テーブルを出力する] にチェックをつけておいてください。
    //!
    //!         @ref RomSoundArchive 使用時は、あらかじめ
    //!         @ref RomSoundArchive::LoadLabelStringData でラベル文字列データを
    //!         ロードしておく必要があります。
    //!
    //! @param[in]    pLabel  ラベル文字列です。
    //!
    //! @return   指定したラベル文字列に対応したアイテム ID を返します。
    //!
    //! @see GetItemLabel
    //! @see RomSoundArchive::LoadLabelStringData
    //!
    //! @date 2010/06/25 サウンドアーカイブの文字列テーブルに関する記述を追加
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    ItemId GetItemId( const char* pLabel ) const;

    //---------------------------------------------------------------------------
    //! @brief  アイテム ID から、対応するファイル ID を取得します。
    //!
    //!         変換できるアイテム ID の種類は、
    //!         サウンド (STRM / WSD / SEQ) および、
    //!         ウェーブサウンドセット、シーケンスサウンドセット、
    //!         バンク、波形アーカイブ、グループです。
    //!
    //!         ウェーブサウンドセットの ID を指定した場合と、
    //!         当該ウェーブサウンドセットに含まれる任意のウェーブサウンドの ID
    //!         を指定した場合では、同じファイル ID が返ります。
    //!
    //!         シーケンスサウンドセットの ID を指定した場合と、
    //!         当該シーケンスサウンドセットに含まれるシーケンスサウンドのうち、
    //!         一番若い ID のシーケンスサウンドを指定した場合では、
    //!         同じファイル ID が返ります。
    //!
    //!         プレイヤーの ID を指定すると、
    //!         SoundArchive::INVALID_ID が返ります。
    //!
    //!         本関数で取得したファイル ID は、@ref SoundDataManager::SetFileAddress
    //!         関数で利用することができます。
    //!
    //! @param[in]    id      サウンドアーカイブ内のアイテム ID です。
    //!
    //! @return   指定したアイテム ID に対応したファイル ID を返します。
    //!
    //! @see FileId
    //! @see ItemId
    //! @see SoundDataManager::SetFileAddress
    //!
    //! @date 2010/12/17 ウェーブサウンドセットおよびシーケンスサウンドセットに対応
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    FileId GetItemFileId( ItemId id ) const;

    //---------------------------------------------------------------------------
    //! @brief      サウンドの通し番号をサウンド ID に変換します。
    //!
    //!             index に 0 以上 @ref GetSoundCount 未満の値を渡すと、
    //!             全サウンドの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   サウンドの通し番号です。
    //!
    //! @return     通し番号に対応したサウンド ID を返します。
    //!
    //! @see ItemId
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetSoundIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_Sound );
    }
    //---------------------------------------------------------------------------
    //! :private
    //!
    //! @brief      サウンドグループ (ウェーブサウンドセット、シーケンスサウンドセット)
    //!             の通し番号をサウンド ID に変換します。
    //!
    //!             index に 0 以上 @ref GetSoundGroupCount 未満の値を渡すと、
    //!             全サウンドグループの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   サウンドグループの通し番号です。
    //!
    //! @return     通し番号に対応したサウンドグループ ID を返します。
    //!
    //! @see ItemId
    //! @see GetSoundGroupCount
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetSoundGroupIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_SoundGroup );
    }
    //---------------------------------------------------------------------------
    //! @brief      バンクの通し番号をバンク ID に変換します。
    //!
    //!             index に 0 以上 @ref GetBankCount 未満の値を渡すと、
    //!             全バンクの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   バンクの通し番号です。
    //!
    //! @return     通し番号に対応したバンク ID を返します。
    //!
    //! @see ItemId
    //! @see GetBankCount
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetBankIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_Bank );
    }
    //---------------------------------------------------------------------------
    //! @brief      プレイヤーの通し番号をプレイヤー ID に変換します。
    //!
    //!             index に 0 以上 @ref GetPlayerCount 未満の値を渡すと、
    //!             全プレイヤーの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   プレイヤーの通し番号です。
    //!
    //! @return     通し番号に対応したプレイヤー ID を返します。
    //!
    //! @see ItemId
    //! @see GetPlayerCount
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetPlayerIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_Player );
    }
    //---------------------------------------------------------------------------
    //! @brief      波形アーカイブの通し番号を波形アーカイブ ID に変換します。
    //!
    //!             index に 0 以上 @ref GetWaveArchiveCount 未満の値を渡すと、
    //!             全波形アーカイブの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   波形アーカイブの通し番号です。
    //!
    //! @return     通し番号に対応した波形アーカイブ ID を返します。
    //!
    //! @see ItemId
    //! @see GetWaveArchiveCount
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetWaveArchiveIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_WaveArchive );
    }
    //---------------------------------------------------------------------------
    //! @brief      グループの通し番号をグループ ID に変換します。
    //!
    //!             index に 0 以上 @ref GetGroupCount 未満の値を渡すと、
    //!             全グループの ID を取得することができます。
    //!
    //!             最大値は範囲チェックされませんので、
    //!             取得値を利用する場合は、アプリケーション側で注意してください。
    //!
    //! @param[in]  index   グループの通し番号です。
    //!
    //! @return     通し番号に対応したグループ ID を返します。
    //!
    //! @see ItemId
    //! @see GetGroupCount
    //!
    //! @date 2010/08/30 初版
    //---------------------------------------------------------------------------
    static ItemId GetGroupIdFromIndex( u32 index )
    {
        return internal::Util::GetMaskedItemId( index, internal::ItemType_Group );
    }
    //@}


    //----------------------------------------
    //! @name 情報取得
    //@{
    //---------------------------------------------------------------------------
    //! @brief    指定した ID のサウンドのユーザーパラメータを取得します。
    //!
    //!           指定した ID のサウンドが存在しない場合は、
    //!           0 を返します。
    //!
    //! @param[in]    soundId     サウンドアーカイブ内のサウンド ID です。
    //!
    //! @return   サウンドのユーザーパラメータを返します。
    //!
    //! @see      ItemId
    //!
    //! @date 2010/01/18 初版
    //---------------------------------------------------------------------------
    u32 GetSoundUserParam( ItemId soundId ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID のサウンドの種類を取得します。
    //!
    //!           指定した ID のサウンドが存在しない場合は、
    //!           @ref SOUND_TYPE_INVALID を返します。
    //!
    //! @param[in]    soundId     サウンドアーカイブ内のサウンド ID です。
    //!
    //! @return   サウンドの種類を返します。
    //!
    //! @see SoundType
    //! @see ItemId
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    SoundType GetSoundType( ItemId soundId ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID のサウンドの情報を取得します。
    //!
    //!           指定した ID のサウンドが存在しない場合は読み取りは失敗します。
    //!
    //! @param[in]    soundId     サウンドアーカイブ内のサウンド ID です。
    //! @param[out]   info        サウンド情報を取得するための構造体です。
    //!
    //! @return   サウンド情報の取得に成功したら true を、失敗したら false を返します。
    //!
    //! @see ItemId
    //! @see SoundInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool ReadSoundInfo( ItemId soundId, SoundInfo* info ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID のシーケンスサウンドの情報を取得します。
    //!
    //!           指定した ID のシーケンスサウンドが存在しない場合は読み取りは失敗します。
    //!
    //! @param[in]    soundId     サウンドアーカイブ内のサウンド ID です。
    //! @param[out]   info        シーケンスサウンド情報を取得するための構造体です。
    //!
    //! @return   シーケンスサウンド情報の取得に成功したら true を、失敗したら false を返します。
    //!
    //! @see ItemId
    //! @see SequenceSoundInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool ReadSequenceSoundInfo( ItemId soundId, SequenceSoundInfo* info ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID のバンクの情報を取得します。
    //!
    //!           指定した ID のバンクが存在しない場合は読み取りは失敗します。
    //!
    //! @param[in]    bankId      サウンドアーカイブ内のバンク ID です。
    //! @param[out]   info        バンク情報を取得するための構造体です。
    //!
    //! @return   バンク情報の取得に成功したら true を、失敗したら false を返します。
    //!
    //! @see ItemId
    //! @see PlayerInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool ReadBankInfo( ItemId bankId, BankInfo* info ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID のプレイヤーの情報を取得します。
    //!
    //!           指定した ID のプレイヤーが存在しない場合は読み取りは失敗します。
    //!
    //! @param[in]    playerId    サウンドアーカイブ内のプレイヤー ID です。
    //! @param[out]   info        プレイヤー情報を取得するための構造体です。
    //!
    //! @return   プレイヤー情報の取得に成功したら true を、失敗したら false を返します。
    //!
    //! @see ItemId
    //! @see PlayerInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool ReadPlayerInfo( ItemId playerId, PlayerInfo* info ) const;

    //---------------------------------------------------------------------------
    //! @brief    サウンドアーカイブプレイヤーの情報を取得します。
    //!
    //! @param[out]   info    サウンドアーカイブプレイヤー情報を取得するための構造体です。
    //!
    //! @return   サウンドアーカイブプレイヤー情報の取得に成功したら true を、
    //!           失敗したら false を返します。
    //!
    //! @see SoundArchivePlayerInfo
    //!
    //! @date 2010/01/15 初版
    //---------------------------------------------------------------------------
    bool ReadSoundArchivePlayerInfo( SoundArchivePlayerInfo* info ) const;

    //! @details :private
    bool detail_ReadStreamSoundInfo( ItemId soundId, StreamSoundInfo* info ) const;

    //! @details :private
    bool detail_ReadWaveSoundInfo( ItemId soundId, WaveSoundInfo* info ) const;

    //---------------------------------------------------------------------------
    //! @brief    指定した ID の 3D サウンド情報を取得します。
    //!
    //!           指定した ID のサウンドが存在しない場合は読み取りに失敗します。
    //!
    //! @param[in]    soundId サウンドアーカイブ内のサウンド ID です。
    //! @param[out]   info    サウンドアーカイブプレイヤー情報を取得するための構造体です。
    //!
    //! @return   3D サウンド情報の取得に成功したら true を、
    //!           失敗したら false を返します。
    //!
    //! @see Sound3DInfo
    //!
    //! @date 2010/03/05 初版
    //---------------------------------------------------------------------------
    bool ReadSound3DInfo( ItemId soundId, Sound3DInfo* info ) const;

    //! @details :private
    bool ReadWaveArchiveInfo( ItemId warcId, WaveArchiveInfo* info ) const;

    //! @details :private
    bool detail_ReadSoundGroupInfo( ItemId groupId, SoundGroupInfo* info ) const;

    //! @details :private
    bool detail_ReadGroupInfo( ItemId groupId, GroupInfo* info ) const;

    //! @details :private
    bool detail_ReadFileInfo( FileId fileId, FileInfo* info ) const;

    //! @details :private
    // TODO: bool detail_ReadGroupItemInfo( GroupId groupId, unsigned long index, GroupItemInfo* info ) const;

    //! @details :private
    // TODO: bool detail_ReadFilePos( FileId fileId, unsigned long index, FilePos* filePos ) const;
    const internal::Util::Table<u32>* detail_GetWaveArchiveIdTable( ItemId id ) const;

    // ファイルアクセス
    //! @details :private
    virtual const void* detail_GetFileAddress( FileId fileId ) const = 0;
    //! @details :private
    virtual size_t detail_GetRequiredStreamBufferSize() const = 0;

    /* MEMO: NW4R では const がついていたが、CTR では nn::fs::FileReader を内部で使っているため
             const をはずした */
    //! @details :private
    io::FileStream* detail_OpenFileStream( FileId fileId, void* buffer, int size );
#if 0 // たぶん不要
    io::FileStream* detail_OpenFileWaveDataStream( FileId fileId, void* buffer, int size ) const;
    io::FileStream* detail_OpenGroupStream( GroupId groupId, void* buffer, int size ) const;
    io::FileStream* detail_OpenGroupWaveDataStream( GroupId groupId, void* buffer, int size ) const;
#endif
    //@}

    //----------------------------------------
    //! @name ファイルパス
    //@{
    //---------------------------------------------------------------------------
    //! @brief    外部参照ファイルのルートディレクトリを設定します。
    //!
    //!           サウンドアーカイブの外部参照ファイルのファイルパスが、
    //!           相対パスで記述されている場合には、
    //!           この関数で設定したルートディレクトリからの相対パスとして解釈されます。
    //!
    //!           初期状態はルートディレクトリに設定されています。
    //!
    //!           この関数は @ref nw::snd::RomSoundArchive::Open から呼び出されています。
    //!
    //! @param[in] extFileRoot    ルートディレクトリに設定するディレクトリパスです。
    //!
    //! @see nw::snd::RomSoundArchive::Open
    //!
    //! @date 2010/01/29 初版
    //---------------------------------------------------------------------------
    void SetExternalFileRoot( const char* extFileRoot );
    //@}

protected:
    //! @details :private
    static const int FILE_PATH_MAX  = 256;

    //! @details :private
    void Initialize( internal::SoundArchiveFileReader* fileReader );

    //! @details :private
    void Finalize();

    //! @details :private
    virtual io::FileStream* OpenStream(
        void* buffer,
        int size,
        u32 begin,
        u32 length
    ) = 0;

    //! @details :private
    virtual io::FileStream* OpenExtStream(
        void* buffer,
        int size,
        const char* extFilePath,
        // const wchar_t* extFilePath,
        u32 begin,
        u32 length
    ) const = 0;

private:
    io::FileStream* OpenExtStreamImpl(
        void* buffer,
        int size,
        const char* extFilePath,
        // const wchar_t* extFilePath,
        u32 begin,
        u32 length
    ) const;

    internal::SoundArchiveFileReader* m_pFileReader;
    char m_ExtFileRoot[ FILE_PATH_MAX ];

    // キャッシュ (頻繁にアクセスする)
    u32 m_FileBlockOffset;
};

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


#endif /* NW_SND_SOUND_ARCHIVE_H_ */