QAXDecoder - QVorbis - Vorbis Decoder Library Wiki - QVorbis - Vorbis Decoder Library

QAXDecoder API

概要

QAXDecoder は、QAX/QAS ファイルファイルのデコードライブラリである。 QVorbis ライブラリを、Vorbis ストリームデコードライブラリとして使用している。 実装言語は、C++ で、Windows API に依存している。提供 API は、C++ クラスとして 公開される。

API の使用方法としては、libvorbis の vorbisfile API と類似しており、比較的容易に 移行が可能である。

API

QAX ネームスペース

コンポーネント基底クラス

 // QComponent
 class QComponent {
 
 public:
 
         virtual void STDCALL Release() = 0;
 
 }; // QComponent

QComponent

ライブラリが提供するコンポーネントクラスの基底クラス

Release() メソッドで、コンポーネントを解放する。COM インターフェイスとは異なり、 参照カウンターを管理しないので、呼び出しにより直ちに解放される。

ファイルマッピングコンポーネント

 // QFileMapping
 class QFileMapping : public QComponent {
 
 public:
 
         virtual const VOID* STDCALL MapView(
                 UINT64 offset,
                 SIZE_T size) = 0;
 
         virtual void STDCALL UnmapView(
                 const VOID* p) = 0;
 
 }; // QFileMapping

QFileMapping

QAX ファイルにアクセスするために、メモリマップドファイル読み込み機能を提供する。

ファイル読み込みのカスタマイズを行わない場合は、特に考慮する必要はない。

MapView() メソッド

MapViewOfFile() API で読み込みビューを割り当てる。

UnmapView() メソッド

UnmapViewOfFile() API で読み込みビューの割り当てを解除する。

デコーダーファクトリーコンポーネント

 // QDecoderFactory
 class QDecoderFactory : public QComponent {
 
 public:
 
         virtual QVorbisDecoder* STDCALL CreateVorbisDecoder(
                 const BYTE  key[20],
                 const VOID* id,
                 SIZE_T      idSize,
                 const VOID* setup,
                 SIZE_T      setupSize) = 0;
 
 }; // QDecoderFactory

QDecoderFactory

デコーダーコンポーネントを作成するためのコンポーネント。

ライブラリ内部で使用されるコンポーネントなので、使用者側では特に考慮する必要はない。

デコーダーコンポーネント

 // QItem
 struct QItem {
 
         std::string Type;
         std::string Name;
 
 }; // QItem
 
 // QDecoder
 class QDecoder : public QComponent {
 
 public:
 
         virtual QDecoderOutput* STDCALL CreateOutput(
                 const char* name) = 0;
 
         virtual INT32 STDCALL GetItemCount() = 0;
 
         virtual QItem STDCALL GetItem(
                 INT32 index) = 0;
 
 }; // QDecoder

QDecoder

QAX ファイルのデコードを行うコンポーネント

CreateOutput() メソッド

指定された名前 (name) のデータを検索し、該当する出力コンポーネントを作成する。 該当するデータがない場合は、0 を返す。

GetItemCount() メソッド

QAX ファイル内に含まれるデータアイテム数を返す。

GetItem() メソッド

データアイテムの 名前 (Name) タイプ (Type) を返す。 現在タイプには 'vorbis' のみが定義されている。

出力コンポーネント

 // QDecoderSpec
 struct QDecoderSpec {
 
         INT32 Channels;
         INT32 SamplingRate;
 
         UINT64 Samples;
 
 }; // QDecoderSpec
 
 // QDecoderOutput
 class QDecoderOutput : public QComponent {
 
 public:
 
         virtual QDecoderSpec STDCALL GetDecoderSpec() = 0;
 
         virtual UINT32 STDCALL Decode(
                 VOID*  buffer,
                 UINT32 samples) = 0;
 
         virtual void STDCALL Seek(
                 UINT64 sample) = 0;
 
         virtual std::string STDCALL QueryProperty(
                 const char* name) = 0;
 
 }; // QDecoderOutput

QDecoderOutput

ストリームのデコード結果を出力するコンポーネント

GetDecoderSpec() メソッド

ストリームのパラメータを返す。

チャンネル数 (Channels), サンプリングレート (SamplingRate), 全サンプル数 (Samples)

Decode() メソッド

ストリームのデコードを行い最大 1 フレーム分の PCM データの出力を行う。PCM フォーマットは、16 bit 符号つき整数、 リトルエンディアンである。

samples には、バッファの最大サンプル数を与える。 buffer として必要なメモリ量は、2 * チャンネル数 * samples (Byte) となるので、注意が必要。

戻り値は、出力されたサンプル数である。0 が返った場合は、ストリームの終端に達したことを表す。

Seek() メソッド

ストリームの指定されたサンプル位置 (sample) へ移動する。

移動は、サンプル単位で正確に処理される。

QueryProperty() メソッド

ストリームに関連付けられたプロパティ値を問い合わせる。

プロパティ値は、QAX ファイル作成ツール QAXMaker で指定することができる。ループポイントの位置など、 アプリケーションで利用できる任意の情報を設定可能。

初期化関数

 API_EXTERN bool STDCALL Initialize();

ライブラリ初期化のため、プロセス開始時に一度のみ呼び出す。

QVorbis ライブラリの初期化も内部で行う。

コンポーネント作成関数

 API_EXTERN QFileMapping* STDCALL QFileMappingCreate(
         LPCWSTR path);
 
 API_EXTERN QDecoderFactory* STDCALL QDecoderFactoryCreate();
 
 API_EXTERN QDecoder* STDCALL QDecoderCreate(
         QDecoderFactory* pFactory,
         QFileMapping*    pFileMapping);
 
 API_EXTERN IStream* STDCALL StreamReaderCreate(
         LPCWSTR path);
 
 API_EXTERN QDecoderOutput* STDCALL QASDecoderOutputCreate(
         QDecoderFactory* pFactory,
         IStream*         pStream);

QFileMappingCreate()

path で指定されたファイルのファイルマッピングコンポーネントを作成する。

QAX ファイルのオープンに使用する。

QDecoderFactoryCreate()

デコーダーファクトリーコンポーネントを作成する。

QDecoderCreate()

デコーダーファクトリーコンポーネントとファイルマッピングコンポーネントを指定して、デコーダー コンポーネントを作成する。

StreamReaderCreate()

path で指定されたファイルを読み込む、IStream COM インターフェイスを作成する。

QAS ファイルのオープンに使用できる。

QASDecoderOutputCreate()

デコーダーファクトリーコンポーネントと読み込み用 IStream インターフェイスを指定して、 QAS ファイル出力コンポーネントを作成する。

例外

QAXDecoder ライブラリでは、エラー時には例外を送出する。

例外安全性を確保するため、すべての API 呼び出しコードにおいて、try, catch 文で例外を捕捉する 必要がある。

 // Exception
 class Exception {
 
 public:
 
         virtual ~Exception()
         {
         }
 
         virtual std::string ToString() = 0;
 
 }; // Exception

Exception 基底例外クラス

QAXDecoder ライブラリで送出するすべての例外クラスの基底クラス

ToString() メソッドで、追加情報を取得できる。

実際に送出される、派生例外クラスは以下の通り。

• FormatError
• DecoderError
• WinError
• COMError