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

QVorbis API

概要

QVorbis は、Vorbis オーディオストリームのデコードコアライブラリである。 C 言語で記述され、C 関数 API を提供する。 QVorbis ライブラリでは、純粋に Vorbis ストリームのみを扱い、Ogg コンテナフォーマット を取り扱う機能はサポートしていない。

Vorbis ストリームをデコードする低水準機能のみを提供するため、より高水準なライブラリを 使用する場合は、このレベルの API を使用する必要はない。

API

初期化

 BOOL QV_Initialize(void);
 
 BOOL QV_SetEnableSSE2(BOOL b);

QV_Initialize()

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

QV_SetEnableSSE2()

SSE2 拡張ルーチンを使用するかどうかを変更する。使用 CPU によって QV_Initialize() 関数が 自動的に設定するため、テスト以外の用途では呼び出す必要はない。

デコーダーセットアップ

 struct QVorbisDecoderSetup;
 
 typedef struct QVorbisDecoderSetup QVorbisDecoderSetup_t;
 
 QVorbisDecoderSetup_t* QV_CreateDecoderSetup(void);
 
 void QV_ReleaseDecoderSetup(QVorbisDecoderSetup_t* setup);
 
 BOOL QV_SetupDecoderSetup(
         QVorbisDecoderSetup_t* setup,
         const VOID*            id_packet,
         SIZE_T                 id_size,
         const VOID*            setup_packet,
         SIZE_T                 setup_size);
 
 INT32 QV_GetDecoderSetupChannels(
         QVorbisDecoderSetup_t* setup);
 
 INT32 QV_GetDecoderSetupSamplingRate(
         QVorbisDecoderSetup_t* setup);

QV_CreateDecoderSetup()

デコーダーセットアップオブジェクトを作成する。

QV_ReleaseDecoderSetup()

デコーダーセットアップオブジェクトを解放する。

QV_SetupDecoderSetup()

Vorbis の Identification header および Setup header を入力して、 デコーダーセットアップを準備する。 セットアップデーターが不正な場合は、エラーとして、FALSE を返す。

QV_GetDecoderSetupChannels()

Vorbis ストリームのオーディオチャンネル数を返す。

QV_GetDecoderSetupSamplingRate()

Vorbis ストリームのオーディオサンプリングレートを返す。(Hz)

デコーダー

 struct QVorbisDecoder;
 
 typedef struct QVorbisDecoder QVorbisDecoder_t;
 
 QVorbisDecoder_t* QV_CreateDecoder(void);
 
 void QV_ReleaseDecoder(QVorbisDecoder_t* d);
 
 BOOL QV_SetupDecoder(
         QVorbisDecoder_t*      d,
         QVorbisDecoderSetup_t* setup,
         SIZE_T                 size);
 
 struct QV_Output {
 
         INT32 Channels;
         INT32 Length;
 
         const FLOAT* Output[2];
 
 };
 
 typedef struct QV_Output QV_Output_t;
 
 BOOL QV_DecodeFrame(
         QVorbisDecoder_t* d,
         const VOID*       packet,
         SIZE_T            size,
         QV_Output_t*      output);
 
 void QV_ResetDecoder(
         QVorbisDecoder_t* d);

QV_CreateDecoder()

デコーダーオブジェクトを作成する。

QV_ReleaseDecoder()

デコーダーオブジェクトを解放する。

QV_SetupDecoder()

デコーダーオブジェクトを準備する。

setup には、セットアップオブジェクトを指定する。 単一のセットアップオブジェクトから、複数のデコーダーを準備することも可能である。

size には、内部で確保されるビットストリームバッファの容量を指定する。(Byte)

QV_DecodeFrame()

1 フレーム分のビットストリームをデコードし、PCM サンプルを返す。

packet, size には、1 フレーム分の入力ビットストリームを指定する。 size は、QV_SetupDecoder() で指定したサイズを超えてはならない。 (1 フレームごとのパケット化は、上位のコンテナフォーマットで処理される。)

output へ、出力結果が返される。

1 フレームに含まれるサンプル数 (Length) は、可変である。また、最初にデコードされる フレームの出力サンプル数は、Vorbis 仕様により 0 となる。

Output には、32 bit 浮動小数点サンプルが格納される。サンプル実体は、デコーダーの内部ワーク へ格納されているため、呼び出し側でデータをコピーしてから、次のデコード処理を呼び出すこと。

QV_ResetDecoder()

シーク処理などのために、デコーダーをリセットする。

デコーダー補助

 struct QV_Convert {
 
         const INT16* Sample;
 
         INT32 Samples;
 
 };
 
 typedef struct QV_Convert QV_Convert_t;
 
 BOOL QV_ConvertFrame(
         QVorbisDecoder_t*  d,
         const QV_Output_t* output,
         QV_Convert_t*      convert);
 
 void QV_ResetDecoderChecker(
         QVorbisDecoder_t* d);
 
 BOOL QV_CheckDecoderChecker(
         QVorbisDecoder_t* d,
         const VOID*       packet,
         SIZE_T            size,
         INT32*            samples);

QV_ConvertFrame()

デコーダーで出力される 32 bit 浮動小数点サンプルを 16 bit 符号付き整数サンプルへ変換する。

Sample が指すバッファーは、デコーダー内部ワークのため、呼び出し側でコピーして、次の処理を行うこと。

QV_ResetDecoderChecker()

サンプル数チェッカーをリセットする。

QV_CheckDecoderChecker()

フレームデータの出力サンプル数を、デコード処理を行うことなく算出する。 Vorbis 仕様では、1 フレームあたりのサンプル数が可変なので、出力サンプル数を高速に求めたい場合に使用する。

サンプルチェッカー

 struct QVorbisSamplesChecker;
 
 typedef struct QVorbisSamplesChecker QVorbisSamplesChecker_t;
 
 QVorbisSamplesChecker_t* QV_CreateSamplesChecker(void);
 
 void QV_ReleaseSamplesChecker(QVorbisSamplesChecker_t* t);
 
 BOOL QV_SetupSamplesChecker(
         QVorbisSamplesChecker_t* t,
         QVorbisDecoderSetup_t*   setup);
 
 void QV_ResetSamplesChecker(QVorbisSamplesChecker_t* t);
 
 BOOL QV_CheckSamplesChecker(
         QVorbisSamplesChecker_t* t,
         const VOID*              packet,
         SIZE_T                   size,
         INT32*                   samples);

サンプルチェッカーは、Vorbis ストリームのインデックス化を行うツール用の機能である。

QV_CreateSamplesChecker()

サンプルチェッカーオブジェクトを作成する。

QV_ReleaseSamplesChecker()

サンプルチェッカーオブジェクトを解放する。

QV_SetupSamplesChecker()

サンプルチェッカーオブジェクトを準備する。

QV_ResetSamplesChecker()

サンプルチェッカーオブジェクトをリセットする。

QV_CheckSamplesChecker()

フレーム内のサンプル数を算出する。