Yggdrasil Seeds : Software Works : DualMusik : DS8OUT.DLL用プラグ仕様
PV[1194248]

DS8OUT.DLL用プラグ仕様

DS8OUT.DLLではファイルからPCMを取り込む処理をプラグに分離しており、このプラグを切り替えることでより多くのファイル形式を扱えるようになっています。

ファイル名命名規則

ファイル名は"wd"+拡張子名+".dll"としておくことを推奨としますが、プレイヤがファイル形式とプラグを関連付ける手段が別にあれば、この限りでありません。

定義等

必要な定義等は develop/dumwdec.h と develop/dumdef.h に全て記述してあります。
ただし、これはBorland C/C++用のものです。他のコンパイラを使用する場合は多少の修正を要するものと思われます。

ユーティリティ関数

インポート関数の引数で渡される PDWUTL 型のポインタで、DS8OUT.DLL から一部の機能が提供されます。
PDUMVOID DUMCALLTYPE PDWUTL::alloc(PDWUTL utl,DUMU4B size)

・引数
utlユーティリティ関数テーブルのポインタ
size確保すべきメモリのサイズ

・処理内容
DS8OUT.DLLと同じ手段でメモリを確保する。

・返値
NULLメモリが確保できなかった場合
other確保したメモリのポインタ

void DUMCALLTYPE PDWUTL::free(PDWUTL utl,PDUMVOID mem)

・引数
utlユーティリティ関数テーブルのポインタ
mem確保すべきメモリのポインタ

・処理内容
DS8OUT.DLLと同じ手段でメモリを解放する。

DUMS4B DUMCALLTYPE PDWUTL::open(PDWUTL utl,DUMCSTR file,DUMU4B f)

・引数
utlユーティリティ関数テーブルのポインタ
fileファイル名
fフラグ

・処理内容
ファイルを開く。
用途に合わせ、以下のフラグを論理和で組み合わせる必要がある。
DW_FILE_READ読み取り可で開くことを示す
DW_FILE_WRITE書き込み可で開くことを示す
DW_FILE_RDWRDW_FILE_READ|DW_FILE_WRITE と同等
DW_FILE_NEWファイルを新規に生成することを示す
DW_FILE_EXCLが指定されていない場合、既存のファイルは削除される
DW_FILE_EXCLファイルが既存であるときは新規に生成できないことを示す
DW_FILE_APPEND既存のファイルに追記されることを示す

・返値
開いたファイルを識別する値,またはエラーであることを示す値を返す。

DUMS4B DUMCALLTYPE PDWUTL::openerrcode(PDWUTL utl)

・引数
utlユーティリティ関数テーブルのポインタ

・処理内容
ファイルのオープンエラーを示す値を取得する。

・返値
オープンエラーであることを示す値を返す。

DUMBOOL DUMCALLTYPE PDWUTL::isopenerr(PDWUTL utl,DUMS4B fd)

・引数
utlユーティリティ関数テーブルのポインタ
fdopen() または openerrcode() の返値

・処理内容
開いたファイルがエラーかどうかを調べる。

・返値
FALSE正常
TRUE異常

void DUMCALLTYPE PDWUTL::close(PDWUTL utl,DUMS4B fd)

・引数
utlユーティリティ関数テーブルのポインタ
fdopen() の返値

・処理内容
open()で開いたファイルを閉じる。

DUMU8B DUMCALLTYPE PDWUTL::seek(PDWUTL utl,DUMS4B fd,DWS8B pos,DUMS4B mode)

・引数
utlユーティリティ関数テーブルのポインタ
fdopen() の返値
pos変化量
mode基準位置(DW_SEEK_SET=先頭,DW_SEEK_CUR=現在位置,DW_SEEK_END=最後尾)

・処理内容
open()で開いたファイルのカーソル位置を変更する。

・返値
現在位置を返す。

DUMU8B DUMCALLTYPE PDWUTL::read(PDWUTL utl,DUMS4B fd,PDUMVOID buf,DUMU8B size)

・引数
utlユーティリティ関数テーブルのポインタ
fdopen() の返値
buf転送先バッファ
size転送すべきサイズ

・処理内容
open()で開いたファイルから読み出し、バッファに転送する。

・返値
実際に転送した量を返す。

DUMU8B DUMCALLTYPE PDWUTL::write(PDWUTL utl,DUMS4B fd,PDUMVOID buf,DUMU8B size)

・引数
utlユーティリティ関数テーブルのポインタ
fdopen() の返値
buf転送先バッファ
size転送すべきサイズ

・処理内容
バッファの内容をopen()で開いたファイルへ書き込む。

・返値
実際に書き込んだ量を返す。

インポート関数

関数により、実装必須なものとそうでないものがあります。
必須な関数がない場合はプラグとして利用できなくなります。
DUMU4B DUMEXPORTTYPE dw_version(void)[必須]

・返値
プラグの動作に最低限必要なDS8OUT.DLLのヴァージョンを返す。
DUMDLLVERSION(アンオフィシャル識別番号,メジャーヴァージョン,マイナーヴァージョン,リリース番号) に相当する値。
通常は DUMDLLVERSION(0,0,40,0) でよい。
新しいDS8OUT.DLLが必要な場合は必要なヴァージョンの値に変えておけば、古いDS8OUT.DLLで使用するときに利用を阻止できる。
また、アンオフィシャル識別番号が0以外の場合はDS8OUT.DLLのアンオフィシャル識別番号と同じ場合のみ使用できる。独自のDS8OUT.DLLを使用する場合は、この値を合わせておく。

PDUMVOID DUMEXPORTTYPE dw_credit(void)

・返値
プラグの著作権情報が書かれている文字列のポインタを返す。
DS8OUT.DLLで参照するものであるため、ポインタの場所以降に固定された文字列でなくてはならない。
また、使用できる文字セットはUS-ASCIIのみとする。

DUMU4B DUMEXPORTTYPE dw_pcmcount(PDWUTL utl,DUMCSTR file)[必須]

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル

・処理内容
データファイルに含まれるPCMの数を調べる。

・返値
0エラーが出た場合
otherPCMの数。または、このファイルで使える最大のPCM番号+1

(V0.45以降)
なくても動作可能になった。
その場合、PCMの数は1として扱われる。

void DUMEXPORTTYPE dw_enumpcmtext(PDWUTL utl,DUMCSTR file,DUMU4B ch,DUMS4B kind,DWCBFINDTEXT cbfindtext,LPVOID tag)(V0.46以降)

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル
chPCM番号
kind文字列種別
cbfindtext文字列を検出したときに呼ぶコールバック
tag↑に渡すポインタ

・処理内容
対象のPCMに対応する文字列を列挙し、それぞれについてコールバックで渡す。
このコールバックは4つの引数を持つ。
1番目はtagをそのまま渡す。2～4番目は文字列を指すポインタで、それぞれ文字列本体,言語コード,文字セット名を表す。このうち、文字列本体以外についてはNULLを渡して省略することも可能。寧ろ、データファイル内で明示されていない場合はNULLを渡すべき。

コールバックがTRUEを返したときは列挙処理を続行し、FALSEを返したときは処理を中断する。
FALSEが返ってきたにも関わらず無視してコールバックを呼んだ場合、処理はDS8OUT.DLL内で弾かれるようになっている。

kindが負数の場合、対象種別の文字列だけに限定する。そうでない場合は全ての文字列を対象とする。

kindの値は負数に限りdw_pcmtext()のidxと上位互換性がある。0はDW_TEXT_OTHERに当てられ、正数は無効となる。
DW_PCM_TITLEタイトル
DW_PCM_RIGHT著作権情報
DW_PCM_ALBUMアルバム名
DW_PCM_ARTISTアーティスト名
DW_PCM_DATE公表日
DW_PCM_NUMBERトラックナンバ
DW_PCM_GENREジャンル
DW_PCM_SUBJECT内容説明(タイトルとは似て非なるもの)

DUMU4B DUMEXPORTTYPE dw_pcmtextcount(PDWUTL utl,DUMCSTR file,DUMU4B ch)

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル
chPCM番号

・処理内容
対象のPCMに対応する文字列の数(インデクス数)を調べる。

・返値
0エラーが出た場合
other文字列の数

(V0.46以降)
dw_enumpcmtext()が実装されている場合、この関数は無効となる。

DUMU4B DUMEXPORTTYPE dw_pcmtext(PDWUTL utl,DUMCSTR file,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.45以降)
DUMU4B DUMEXPORTTYPE dw_pcmtext(PDWUTL utl,DUMCSTR file,DUMU4B ch,DUMS4B idx,DUMCSTR buf,DUMU4B size)

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル
chPCM番号
idxインデクス番号(-2～dw_pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

・処理内容
対象のPCM番号とインデクスに対応する文字列を取得する。
インデクス番号が0未満の場合、特別な用途に則った文字列となる。(dw_enumpcmtext()参照)

bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
バッファサイズは実際の長さより1バイト少ない数が渡されるので、全て使用しても構わない。
ヌルターミネイトはDS8OUT.DLL側で行うので、プラグ側で処理する必要はない。

・返値
0文字列がない場合
other文字列の長さ(バイト単位)

(V0.46以降)
dw_enumpcmtext()が実装されている場合、この関数は無効となる。

DUMU4B DUMEXPORTTYPE dw_pcmtextcset(PDWUTL utl,DUMCSTRBUF file,DUMU4B ch,DUMS4B idx,DUMCSTR buf,DUMU4B size)(V0.45以降)
DUMU4B DUMEXPORTTYPE dw_pcmtextcs(PDWUTL utl,DUMCSTR file,DUMU4B ch,DUMS4B idx,DUMCSTR buf,DUMU4B size)

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル
chPCM番号
idxインデクス番号(-2～dw_pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

・処理内容
dw_pcmtext()で取得する文字列の文字セット名を取得する。
bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
バッファサイズは実際の長さより1バイト少ない数が渡されるので、全て使用しても構わない。
ヌルターミネイトはDS8OUT.DLL側で行うので、プラグ側で処理する必要はない。

(V0.45以降)
2つの関数名はどちらも同じで、片方を実装しておけばよい。
両方実装されている場合は dw_pcmtextcset() が優先される。

(V0.46以降)
dw_enumpcmtext()が実装されている場合、この関数は無効となる。

・返値
0文字列がない場合
other文字列の長さ(バイト単位)

DUMU4B DUMEXPORTTYPE dw_pcmtextlang(PDWUTL utl,DUMCSTR file,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.45以降)

・引数
utlユーティリティ関数テーブルのポインタ
file対象のデータファイル
chPCM番号
idxインデクス番号(-2～dw_pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

・処理内容
dw_pcmtext()で取得する文字列の言語コードを取得する。
bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
バッファサイズは実際の長さより1バイト少ない数が渡されるので、全て使用しても構わない。
ヌルターミネイトはDS8OUT.DLL側で行うので、プラグ側で処理する必要はない。

・返値
0文字列がない場合
other文字列の長さ(バイト単位)

(V0.46以降)
dw_enumpcmtext()が実装されている場合、この関数は無効となる。

PDWDECSTA DUMEXPORTTYPE dw_open(PDWUTL utl,int mode,DUMCSTR file,DUMU4B ch,DUMU4B sw)[必須]

・引数
utlユーティリティ関数テーブルのポインタ
mode処理モード(0=通常,1=ストリーム用)
file対象のデータファイル
ch対象のPCM番号
swPCM制禦スウィッチ

・処理内容
データファイルを開き、ディコードの準備を行う。
ch はファイル中に複数のPCMがある場合に選択するPCMを表す。
sw はプラグ側で自由に使える32bitのフラグ群。
また、構造体DWDECSTAのメモリを確保して各種PCM情報を書き込む。
DWDECSTAに書き込むべき内容は以下の通り。
chPCMチャネル数(1=モノラル,2=ステレオ)
depサンプルデプス(1=8bit unsigned,2=16bit signed)
cap機能対応フラグ(V0.45以降)
以下のうち、対応しているものを論理和
DW_CAP_GETLENGTH: 全サンプル数取得(samplesメンバに有効な値を設定)
DW_CAP_GETPOS: ディコード位置取得(dw_getpos()実装)
DW_CAP_SETPOS: ディコード位置設定(dw_setpos()実装)
DW_CAP_SETEND: 終端位置設定(dw_setend()実装)
DW_CAP_SETLOOP: ループ設定(dw_setloop()実装)
ver構造体ヴァージョン(原則、DWDECSTAVERSIONを書き込む)(V0.45以降)
freqサンプルレート
samplesサンプル数(ループなどで特定できない場合は0)
lbgnループ始端サンプル位置(V0.45以降)
(verが1未満のときは無視される)
lendループ終端サンプル位置(V0.45以降)
(verが1未満のときは無視される)

・返値
NULLエラーが出た場合
other確保したDWDECSTAのポインタ

・注意事項

(V0.45以降)
DS8OUT.DLLではverの値をみて構造体のサイズを判断している。
verにDWDECSTAVERSIONが書き込まれていなかった場合、拡張された部分の設定は無視されてしまい、常に0として扱われる。

DUMU4B DUMEXPORTTYPE dw_decode(PDWUTL utl,PDWDECSTA fp,PDUMVOID buf,DUMU4B size)[必須]

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値
bufPCMを格納するバッファ(NULL=格納しない)
sizeバッファサイズ(バイト単位)

・処理内容
dw_open() で開いたPCMをディコードしてバッファに格納する。
bufがNULLの場合は格納を行わず、その他の処理を進める。
(bufがNULL且つsizeが0でない場合は、その部分を読み飛ばす)
[補足]:
DS8OUT.DLLでは dw_open() の直後やバッファ飽和後に dw_decode(fp,NULL,0) が呼ばれる。
ディコード処理とバッファへの格納処理を分けておけば、このときにディコード処理だけ行っておき、次回の格納処理を迅速に行うことができる。
格納処理に時間がかかると、ストリーム再生が正常に行われなくなる惧れがある。このため、ディコード処理は分離して先行できるような仕様にしておくことを推奨。

・返値
バッファに格納したPCMのサイズをバイト単位で返す。

DWSETRES DUMEXPORTTYPE dw_setpos(PDWUTL utl,PDWDECSTA fp,DUMU8B pos)(V0.45以降)

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値
pos位置(サンプル単位)

・処理内容
dw_open() で開いたPCMの次回ディコード位置を変更する。

・返値
DW_SET_SUCCESS処理成功
DW_SET_UNSTABLE処理成功だが動作が不正確
DW_SET_FATAL処理失敗
DW_SET_UNSUPPORT未対応

DUMU8B DUMEXPORTTYPE dw_getpos(PDWUTL utl,PDWDECSTA fp)(V0.45以降)

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値

・処理内容
dw_open() で開いたPCMの次回ディコード開始位置を調べる。

・返値
ディコード開始位置をサンプル単位で返す。
エラーの場合は常に0が返る。

DWSETRES DUMEXPORTTYPE dw_setend(PDWUTL utl,PDWDECSTA fp,DUMU8B pos)(V0.45以降)

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値
posディコード終了位置(サンプル単位)

・処理内容
dw_open() で開いたPCMのディコード終了位置を設定する。この後、設定位置より1つ手前のサンプルをディコードしたところで終了扱いとなる。
ただし、0を設定する場合に限り設定解除として扱い、本来のサンプルデータ終端と同じ位置にする。

・返値
DW_SET_SUCCESS処理成功
DW_SET_UNSTABLE処理成功だが動作が不正確
DW_SET_FATAL処理失敗
DW_SET_UNSUPPORT未対応

DWSETRES DUMEXPORTTYPE dw_setloop(PDWUTL utl,PDWDECSTA fp,DUMU8B begin,DUMU8B end)(V0.45以降)

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値
beginループ始端位置(サンプル単位)
endループ終端位置(サンプル単位)

・処理内容
dw_open() で開いたPCMのループ位置を設定する。この後、始端から終端の1つ手前のサンプルを繰り返してディコードするようになる。
ただし、endに0を設定する場合に限り設定解除として扱い、ディコードの繰り返しを中止する。

・返値
DW_SET_SUCCESS処理成功
DW_SET_UNSTABLE処理成功だが動作が不正確
DW_SET_FATAL処理失敗
DW_SET_UNSUPPORT未対応

void DUMEXPORTTYPE dw_switch(PDWUTL utl,PDWDECSTA fp,DUMU4B sw)

・引数
utlユーティリティ関数テーブルのポインタ
fpdw_open()の返値
swPCM制禦スウィッチ

・処理内容
PCM制禦スウィッチの内容を変更する。
変更が不可能な場合は無理に対応せず、無視して構わない。

DUMBOOL DUMEXPORTTYPE dw_isend(PDWUTL utl,PDWDECSTA fp)[必須]

・引数
utlユーティリティ関数テーブルのポインタ
fpDWDECSTAのポインタ; dw_open()の返値

・処理内容
PCMが終端しているかを調べる。

・返値
全てのサンプルがバッファへ格納完了していればTRUE、そうでなければFALSEを返す。
終端が検知できない場合は、常にFALSEを返してもよい。ただ、用途により終端の検知を必要とする場合があるので、可能な限り実装しておくこと。

void DUMEXPORTTYPE dw_close(PDWUTL utl,PDWDECSTA fp)[必須]

・引数
utlユーティリティ関数テーブルのポインタ
fpDWDECSTAのポインタ; dw_open()の返値

・処理内容
dw_open() で開いたファイルを閉じ、後始末を行う。
dw_open() や dw_decode() で確保したメモリは必ず全て明示的に解放すること。

[表紙]