Yggdrasil Seeds : Software Works : DualMusik : DS8OUT.DLL
PV[205531]

DS8OUT.DLL


DualMusikのPCM関連コールバックからDirectSoundに丸投げするためのライブラリです。
ファイルからのロードはプラグ側で行うので、プラグを追加することでより多くのファイル形式を扱えるようになります。
DirectX8.0aでビルドしたものですが、もしかしたら古いヴァージョンでも使えるかも。試してないけど。

因みに、このライブラリはDualMusikから完全に独立しているので、単にDirectSoundの上位ライブラリとしても使えます。

組み込み

DS8OUT.DLL を利用するソースファイルに DS8OUT.H をインクルードします。また、インポートライブラリを利用する場合は DS8OUT.LIB をリンクします。

使用手順

DS8OUT.DLL からインポートできる関数名は "ds8_const" "ds8_const_utl" "ds8_version" のみです。このうち、"ds8_const" "ds8_const_utl"はどちらか一方で構いません。通常は前者でいいでしょう。
インポートライブラリを利用する場合は、この関数を直接呼び出せます。
そうでない場合は、自前で関数のポインタを取得する必要があります。

HANDLE dllh; DS8CONST ds8_const; DS8VER ds8_version; /*説明のためエラー処理は省略してるけど、実際は省略するべからず*/ dllh=LoadLibrary("DS8OUT.DLL"); ds8_const=(DS8CONST)GetProcAddress(dllh,"ds8_const"); ds8_version=(DS8VER)GetProcAddress(dllh,"ds8_version");
DS8OUT.DLL を使うには、まずインスタンスを取得する必要があります。
(インスタンス関数の詳細は後述)
(V0.40以降)
cballoc,cbfreeをNULLにしても有効となった。ただし、どちらかがNULLの場合は両方ともNULLと同様に扱われる。

void *usr; /*ユーザポインタ(コールバックに渡される任意値)*/ PDS8OUT ds8; ds8=ds8_const(usr,NULL,NULL); if(!dp){ /*返値がNULLの場合はエラー発生(メモリ確保に失敗)*/ }
ここで得たインスタンスは、使用が済んだら必ず解放しなければなりません。

PDS8OUT ds8; /*インスタンス*/ volatile PDS8OUT p; /*安全に解放するため、解放前に変数の内容は消しておく*/ p=ds8; ds8=NULL; p->purge(p);

コールバック関数


typedef PDUMVOID DUMCALLTYPE (*DS8CBALLOC)(PDUMVOID usr,DUMU4B size)

引数
usrユーザポインタ
ds8_constの引数がそのまま
size確保すべきメモリサイズ(byte)

処理内容
インスタンス関数の処理中にメモリを確保する必要がでてきたときに呼ばれる。
通常、return malloc(size); だけでよい。
型名こそ違うが、実態は DUMPLAY.DLL のメモリ確保コールバックと同じなのでユーザポインタの意味付けさえ同じならば同一の関数を使っても構わない。

返値
NULLメモリが確保できなかったときに返す。
other確保したメモリの先頭アドレスを返す。


typedef void DUMCALLTYPE (*DS8CBFREE)(PDUMVOID usr,PDUMVOID mem)

引数
usrユーザポインタ
ds8_constの引数がそのまま
mem解放すべきメモリの先頭アドレス

処理内容
インスタンス関数の処理中に確保したメモリを解放する必要がでてきたときに呼ばれる。
通常、free(mem); だけでよい。
型名こそ違うが、実態は DUMPLAY.DLL のメモリ解放コールバックと同じなのでユーザポインタの意味付けさえ同じならば同一の関数を使っても構わない。


typedef DUMS4B DUMCALLTYPE (*DS8CBOPEN)(PDUMVOID usr,DUMCSTR file,DUMU4B f)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
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既存のファイルに追記されることを示す

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


typedef DUMS4B DUMCALLTYPE (*DS8CBOPENERRCODE)(PDUMVOID usr)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま

処理内容
インスタンス関数の処理中にファイルのオープンエラーを示す値を取得するときに呼ばれる。

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


typedef DUMBOOL DUMCALLTYPE (*DS8CBISOPENERR)(PDUMVOID usr,DUMS4B fd)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
fd(*DS8CBOPEN)() または (*DS8CBOPENERRCODE)() の返値

処理内容
開いたファイルがエラーかどうかを調べる必要がでてきたときに呼ばれる。

返値
TRUE異常(エラーがある)
FALSE正常


typedef void DUMCALLTYPE (*DS8CBCLOSE)(PDUMVOID usr,DUMS4B fd)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
fd(*DS8CBOPEN)() の返値

処理内容
(*DS8CBOPEN)()で開いたファイルを閉じる必要がでてきたときに呼ばれる。


typedef DUMU8B DUMCALLTYPE (*DS8CBSEEK)(PDUMVOID usr,DUMS4B fd,DUMS8B pos,DUMS4B mode)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
fd(*DS8CBOPEN)() の返値
pos変化量
mode基準位置(DW_SEEK_SET=先頭,DW_SEEK_CUR=現在位置,DW_SEEK_END=最後尾)

処理内容
(*DS8CBOPEN)()で開いたファイルのカーソル位置を変更する必要がでてきたときに呼ばれる。

返値
現在位置を返す。


typedef DUMU8B DUMCALLTYPE (*DS8CBREAD)(PDUMVOID usr,DUMS4B fd,PDUMVOID buf,DUMU8B size)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
fd(*DS8CBOPEN)() の返値
buf転送先バッファ
size転送すべきサイズ

処理内容
(*DS8CBOPEN)()で開いたファイルから読み出し、バッファに転送する必要がでてきたときに呼ばれる。

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


typedef DUMU8B DUMCALLTYPE (*DS8CBWRITE)(PDUMVOID usr,DUMS4B fd,PDUMVOID buf,DUMU8B size)(V0.40以降)

引数
usrユーザポインタ
ds8_constの引数がそのまま
fd(*DS8CBOPEN)() の返値
buf転送先バッファ
size転送すべきサイズ

処理内容
バッファの内容を(*DS8CBOPEN)()で開いたファイルへ書き込む必要がでてきたときに呼ばれる。

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


typedef DUMU4B DUMCALLTYPE (*DS8CBSAVETIME)(PDUMVOID usr)

引数
usrユーザポインタ
ds8_constの引数がそのまま

処理内容
DS8OUT::save() の処理中にPCMの長さを取得する必要が生じたときに呼ばれる。

返値
0PCMの書き出しを行わない。
otherPCMの長さをmsec単位で返す。


typedef DUMBOOL DUMCALLTYPE (*DS8CBSAVEPRGRS)(PDUMVOID usr,DUMU4B now,DUMU4B max)

引数
usrユーザポインタ
ds8_constの引数がそのまま
now現在のカウント数
max最終的なカウント数

処理内容
DS8OUT::save() の処理中に何度か呼ばれる。

返値
FALSE処理続行
TRUE処理中断


インスタンス関数


void DUMCALLTYPE DS8OUT::purge(PDS8OUT ds8)

引数
ds8ds8_const() の返値

処理内容
インスタンスを破棄する。
インスタンスが不要になったら必ず破棄すること。


void DUMCALLTYPE DS8OUT::lock(PDS8OUT ds8)(V0.40以降)

引数
ds8ds8_const() の返値

処理内容
DirectSoundのインスタンスをロックする。
外部でDirectSoundのインスタンス関数を呼ぶ場合、前後を lock() ~ unlock() で挟む必要がある。さもなくばDirectSoundの動作が不安定になる可能性がある。


DWERRCODE DUMCALLTYPE DS8OUT::locknw(PDS8OUT ds8)(V0.40以降)

引数
ds8ds8_const() の返値

処理内容
可能ならばDirectSoundのインスタンスをロックする。
ロックできないときは他のスレッドがDirectSoundをロックしていることを示す。

返値
DW_ERR_NONEロック成功
DW_ERR_FATALロック失敗
(V0.45以降)
密かに返値の型名が変わってたりするが、互換性は維持してあるので御安心を。


void DUMCALLTYPE DS8OUT::unlock(PDS8OUT ds8)(V0.40以降)

引数
ds8ds8_const() の返値

処理内容
lock() locknw() で行ったロックを解除する。
用済みになったら必ず解除しておくこと。さもなくば、lock() を実行中のスレッドが解除待ちのまま永久に待機することになる。


void DUMCALLTYPE DS8OUT::mute(PDS8OUT ds8,DUMBOOL side)(V0.40以降)

引数
ds8ds8_const() の返値
side0=ミュート解除,1=ミュート開始

処理内容
インスタンスが管理しているPCMを全て一時的に停止/再開する。


HRESULT DUMCALLTYPE DS8OUT::devopen(PDS8OUT ds8,DUMCSTR name,DUMS4B ch,DUMS4B bit,DUMS4B freq,HWND hw,DUMU4B coop)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::devopen(PDS8OUT ds8,DUMCSTR name,DUMS4B ch,DUMS4B bit,DUMS4B freq,DUMU4B coop,DUMU4B scale,DUMU4B sfreq)(V0.30)

引数
ds8ds8_const() の返値
nameWAVEディヴァイス名(NULL=WAVE MAPPER)
chチャネル数(1 or 2)
bitサンプルデプス(8 or 16)
freqサンプルレート(100~100000)
hw協調レベル設定用ウィンドウハンドル(NULL=自動取得)
coop協調レベル(IDirectSound::SetCooperativeLevelの引数と同じ, DSSCL_PRIORITY推奨)
scaleストリームバッファ単位時間(msec)(0=ストリームなし)
sfreqストリーム再生レート

処理内容
DirectSoundを初期化し、WAVEディヴァイスを使えるようにする。
ch,bit,freqはプライマリバッファ(最終的な波形合成先)のパラメータとなる。
scaleを0以外にした場合、ストリーム再生用のセカンダリバッファを確保する。
値が小さいほどサイズを小さくできるが、そのぶん正常な再生が期待できなくなる。
マシンパワーにもよるが、100~500あたりを推奨。

(V0.40以降)
ストリームバッファの確保は stropen() で行うようにした。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


void DUMCALLTYPE DS8OUT::devclose(PDS8OUT ds8)

引数
ds8ds8_const() の返値

処理内容
WAVEディヴァイスを解放し、DirectSoundインスタンスを破棄する。
getds で得たインスタンスを独自に使用している場合は事前に後始末しておく必要がある。


DUMU4B DUMCALLTYPE DS8OUT::plugdesc(PDS8OUT ds8,DUMCSTR plug,DUMCSTRBUF buf,DUMU4B size)(V0.40以降)

引数
ds8ds8_const() の返値
plugロードに使用するプラグ
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

処理内容
プラグの著作権情報を取得する。
bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
文字列の終端は自動的にヌルターミネイトされる。

返値
文字列の長さをバイト単位で返す。


DUMU4B DUMCALLTYPE DS8OUT::pcmcount(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug)(V0.40以降)

引数
ds8ds8_const() の返値
fileロードするファイル
plugロードに使用するプラグ

処理内容
対象ファイルに含まれるPCMの数を調べる。

返値
対象ファイルに含まれるPCMの数を返す。
エラーまたはPCMがないときは0を返す。


void DUMCALLTYPE DS8OUT::enumpcmtext(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B kind,DS8CBFINDTEXT cb)(V0.46以降)

引数
ds8ds8_const() の返値
file対象のデータファイル
plugロードに使用するプラグ
chPCM番号
kind文字列種別
cb文字列を検出したときに呼ばれるコールバック

処理内容
対象のPCMに対応する文字列を列挙し、それぞれについてコールバックが呼ばれる。
このコールバックは4つの引数を持つ。
1番目は他のコールバックと同じくユーザポインタが渡される。2~4番目は文字列を指すポインタで、それぞれ文字列本体,言語コード,文字セット名を表す。情報が存在しないときはNULLが渡ってくることに注意。
コールバックがTRUEを返すと文字列検索処理を続行し、FALSEを返すと中断となる。

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

なお、プラグに実装された文字列取得処理がV0.45以前のものでも、DS8OUT.DLLが代替処理で仕様の差を吸収するようになっている。


DUMU4B DUMCALLTYPE DS8OUT::pcmtextcount(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch)(V0.40以降)

引数
ds8ds8_const() の返値
file対象のデータファイル
plugロードに使用するプラグ
chPCM番号

処理内容
対象のPCM番号に対応する文字列の数(インデクス数)を取得する。

返値
文字列の数を返す。

(V0.46以降)
プラグにdw_enumpcmtext()が実装されている場合の文字列取得はできない。
新仕様への移行を推奨。


DUMU4B DUMCALLTYPE DS8OUT::pcmtext(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.45以降)
DUMU4B DUMCALLTYPE DS8OUT::pcmtext(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.40以降)

引数
ds8ds8_const() の返値
file対象のデータファイル
plugロードに使用するプラグ
chPCM番号
idxインデクス番号(-2~pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

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

bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
文字列の終端は自動的にヌルターミネイトされる。

返値
文字列の長さをバイト単位で返す。

(V0.46以降)
プラグにdw_enumpcmtext()が実装されている場合の文字列取得はできない。
新仕様への移行を推奨。


DUMU4B DUMCALLTYPE DS8OUT::pcmtextcset(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.45以降)
DUMU4B DUMCALLTYPE DS8OUT::pcmtextcs(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B idx,DUMCSTR buf,DUMU4B size)(V0.40以降)

引数
ds8ds8_const() の返値
file対象のデータファイル
plugロードに使用するプラグ
chPCM番号
idxインデクス番号(-2~pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

処理内容
pcmtext()で取得する文字列の文字セット名を取得する。
bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
文字列の終端は自動的にヌルターミネイトされる。
なお、0が返ってきた場合は文字セットが不明であることを表す。

返値
文字列の長さをバイト単位で返す。

(V0.46以降)
プラグにdw_enumpcmtext()が実装されている場合の文字列取得はできない。
新仕様への移行を推奨。


DUMU4B DUMCALLTYPE DS8OUT::pcmtextlang(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMS4B idx,DUMCSTRBUF buf,DUMU4B size)(V0.45以降)

引数
ds8ds8_const() の返値
file対象のデータファイル
plugロードに使用するプラグ
chPCM番号
idxインデクス番号(-2~pcmtextcount()-1)
buf文字列を格納するバッファ(NULL=調査用)
sizeバッファサイズ

処理内容
pcmtext()で取得する文字列の言語コードを取得する。
bufがNULLの場合は格納を行わず、文字列の長さだけ調べる。
文字列の終端は自動的にヌルターミネイトされる。
なお、0が返ってきた場合は言語コードが不明であることを表す。

返値
文字列の長さをバイト単位で返す。

(V0.46以降)
プラグにdw_enumpcmtext()が実装されている場合の文字列取得はできない。
新仕様への移行を推奨。


PDS8PCMUNIT DUMCALLTYPE DS8OUT::pcmload(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMU4B sw)(V0.40以降)
PDS8PCMUNIT DUMCALLTYPE DS8OUT::loadpcm(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch)(V0.30)

引数
ds8ds8_const() の返値
fileロードするファイル
plugロードに使用するプラグ
chPCM番号
swPCM制禦スウィッチ

処理内容
DirectSoundのセカンダリバッファを生成し、ファイルからPCMを読み込んでバッファにセットする。

(注) サンプル数が取得できないときは自動的に失敗扱いとなる。

返値
NULL処理に失敗
other生成したPCMの識別タグ


PDS8PCMUNIT DUMCALLTYPE DS8OUT::pcmdup(PDS8PCMUNIT unit)(V0.40以降)
PDS8PCMUNIT DUMCALLTYPE DS8OUT::duppcm(PDS8OUT ds8,PDS8PCMUNIT unit)(V0.30)

引数
ds8ds8_const() の返値
unit複製元PCM識別タグ

処理内容
DirectSoundのセカンダリバッファを複製する。

返値
NULL処理に失敗
other生成したPCMの識別タグ


void DUMCALLTYPE DS8OUT::pcmfree(PDS8PCMUNIT unit)(V0.40以降)
void DUMCALLTYPE DS8OUT::freepcm(PDS8OUT ds8,PDS8PCMUNIT unit)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ

処理内容
DirectSoundのセカンダリバッファを破棄する。


HRESULT DUMCALLTYPE DS8OUT::pcmplay(PDS8PCMUNIT unit,DUMU4B flg)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::playpcm(PDS8OUT ds8,PDS8PCMUNIT unit,DUMU4B flg)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ
flg再生モード(0=ワンショット, 1=ループ)

処理内容
DirectSoundのセカンダリバッファを再生する。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


void DUMCALLTYPE DS8OUT::pcmstop(PDS8PCMUNIT unit)(V0.40以降)
void DUMCALLTYPE DS8OUT::stoppcm(PDS8OUT ds8,PDS8PCMUNIT unit)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ

処理内容
DirectSoundのセカンダリバッファの再生を止める。


HRESULT DUMCALLTYPE DS8OUT::pcmvol(PDS8PCMUNIT unit,DUMS4B vol)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::volpcm(PDS8OUT ds8,PDS8PCMUNIT unit,DUMS4B vol)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ(NULL=ストリーム用)
vol音量(0=ミュート ~ 16384=最大)

処理内容
DirectSoundのセカンダリバッファの音量を変更する。
聴感上の変化量を調整するため、実際の設定値は -log2(1+(16384-vol)*16383/16384)/14 と変換される。
(V0.40以降)
ストリームの音量変更は strvol() で行う。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


HRESULT DUMCALLTYPE DS8OUT::pcmpan(PDS8PCMUNIT unit,DUMS4B pan)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::panpcm(PDS8OUT ds8,PDS8PCMUNIT unit,DUMS4B pan)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ(NULL=ストリーム用)
pan定位(-16384=左 ~ 0=中央 ~ +16384=右)

処理内容
DirectSoundのセカンダリバッファの定位を変更する。
聴感上の変化量を調整するため、実際の設定値は sgn(pan)*10000*log2(1+abs(pan)*16383/16384)/14 と変換される。
(V0.40以降)
ストリームの定位変更は strpan() で行う。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


HRESULT DUMCALLTYPE DS8OUT::pcmpit(PDS8PCMUNIT unit,DUMS4B pit)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::freqpcm(PDS8OUT ds8,PDS8PCMUNIT unit,DUMS4B freq)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ(NULL=ストリーム用)
pit
freq
音程(-32768 ~ -256= 半音下 ~ 0=原音 ~ +256=半音上 ~ +32767)

処理内容
DirectSoundのセカンダリバッファの音程を変更する。
実際の設定値は原音の再生レートを基に自動的に算出される。
(V0.40以降)
ストリームの音程変更は strpit() で行う。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


HRESULT DUMCALLTYPE DS8OUT::pcmpos(PDS8PCMUNIT unit,DUMU4B pos)(V0.40以降)
HRESULT DUMCALLTYPE DS8OUT::pospcm(PDS8OUT ds8,PDS8PCMUNIT unit,DUMU4B pos)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ
pos再生位置(0=先頭 ~ 16384=最後尾)

処理内容
DirectSoundのセカンダリバッファの再生位置を変更する。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


DUMU4B DUMCALLTYPE DS8OUT::pcmgetsta(PDS8PCMUNIT unit)(V0.40以降)
DUMU4B DUMCALLTYPE DS8OUT::getpcmsta(PDS8OUT ds8,PDS8PCMUNIT unit)(V0.30)

引数
ds8ds8_const() の返値
unitPCM識別タグ

処理内容
DirectSoundのセカンダリバッファの状態を取得する。

返値
以下のフラグの論理和を返す。
DS8_PCMSTA_PLAY再生中
DS8_PCMSTA_LOOPループ再生中
DS8_PCMSTA_TERM(謎; DSBSTATUS_TERMINATEDと同内容)
DS8_PCMSTA_LOSTバッファ消失
DS8_PCMSTA_INVALID関数呼び出しエラー


PDS8PCMSTR DUMCALLTYPE DS8OUT::strnew(PDS8OUT ds8,DUMU4B wait)(V0.40以降)

引数
ds8ds8_const() の返値
waitスレッドのインターバル時間-1(msec)

処理内容
PCMストリーム用のコンテクストを生成する。
コンテクストにはスレッドが含まれ、生成が成功したときから動作し始める。
スレッドが1ループするとき、waitで指定した値に1を加算したものがWindows APIのSleep()に渡される。

返値
NULL処理に失敗
other生成したコンテクストの識別タグ


void DUMCALLTYPE DS8OUT::strfree(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
strnew()で生成したコンテクストを破棄する。


HRESULT DUMCALLTYPE DS8OUT::stropen(PDS8PCMSTR str,DUMCSTR file,DUMCSTR plug,DUMU4B scale,DUMU4B ch,DUMU4B sw)(V0.40以降)

引数
strstrnew() の返値
fileロードするファイル
plugロードに使用するプラグ
scaleストリームバッファ単位時間(msec)
chPCM番号
swPCM制禦スウィッチ

処理内容
ストリーム再生用にDirectSoundのセカンダリバッファを生成し、ファイルをストリームに関連付ける。
scale にはストリームバッファの単位時間を指定する。バッファは作業用に4単位確保するため、実際のメモリ占有量はほぼ4倍となる。
値が小さいほどサイズを小さくできるが、そのぶん正常な再生が期待できなくなる。
値を大きくした場合、バッファサイズが増えるだけでなく終了検知も遅れるという問題が起こる。
マシンパワーにもよるが、50~500あたりを推奨。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


void DUMCALLTYPE DS8OUT::stropennw(PDS8PCMSTR str,DUMCSTR file,DUMCSTR plug,DUMU4B scale,DUMU4B ch,DUMU4B sw)(V0.40以降)

引数
strstrnew() の返値
fileロードするファイル
plugロードに使用するプラグ
scaleストリームバッファ単位時間(msec)
chPCM番号
swPCM制禦スウィッチ

処理内容
stropen()の処理をバックグラウンドで開始する。
リアルタイム性が維持できるが、エラーの検出ができない。
処理の完了は strisready() で検出できる。


HRESULT DUMCALLTYPE DS8OUT::strpreopen(PDS8PCMSTR str,DUMCSTR file,DUMCSTR plug,DUMU4B scale,DUMU4B ch,DUMU4B sw,PDWDECSTA buf,DUMU4B size)(V0.45以降)

引数
strstrnew() の返値
fileロードするファイル
plugロードに使用するプラグ
scaleストリームバッファ単位時間(msec)
chPCM番号
swPCM制禦スウィッチ
bufDWDECSTA書き出し先
sizesizeof(DWDECSTA)

処理内容
stropen()を試行し、正常ならばstrgetdecsta()を実行してすぐstrclose()を行う。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


void DUMCALLTYPE DS8OUT::strclose(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
ストリーム再生を停止し、セカンダリバッファを破棄する。


void DUMCALLTYPE DS8OUT::strclosenw(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
strclose()の処理をバックグラウンドで開始する。


void DUMCALLTYPE DS8OUT::strplay(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
ストリームの再生を開始する。


void DUMCALLTYPE DS8OUT::strstop(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
ストリームの再生を停止する。
処理の完了は strisend() で検出できる。


HRESULT DUMCALLTYPE DS8OUT::strvol(PDS8PCMSTR str,DUMS4B vol)(V0.40以降)

引数
strstrnew() の返値
vol音量(0=ミュート ~ 16384=最大)

処理内容
ストリーム用セカンダリバッファの音量を変更する。
聴感上の変化量を調整するため、実際の設定値は -log2(1+(16384-vol)*16383/16384)/14 と変換される。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


HRESULT DUMCALLTYPE DS8OUT::strpan(PDS8PCMSTR str,DUMS4B pan)(V0.40以降)

引数
strstrnew() の返値
pan定位(-16384=左 ~ 0=中央 ~ +16384=右)

処理内容
ストリーム用セカンダリバッファの定位を変更する。
聴感上の変化量を調整するため、実際の設定値は sgn(pan)*10000*log2(1+abs(pan)*16383/16384)/14 と変換される。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


HRESULT DUMCALLTYPE DS8OUT::strpit(PDS8PCMSTR str,DUMS4B pit)(V0.40以降)

引数
strstrnew() の返値
pit音程(-32768 ~ -256= 半音下 ~ 0=原音 ~ +256=半音上 ~ +32767)

処理内容
ストリーム用セカンダリバッファの音程を変更する。
実際の設定値は原音の再生レートを基に自動的に算出される。

返値
0正常
other異常(DirectSoundのエラーコードと同じ)


void DUMCALLTYPE DS8OUT::strswitch(PDS8PCMSTR str,DUMU4B sw)(V0.40以降)

引数
strstrnew() の返値
swPCM制禦スウィッチ

処理内容
ストリームの途中でPCM制禦スウィッチの内容を変更する。
ただし、設定が反映されるのはディコード前のサンプルであり、既にディコードが完了した部分には適用されない。


DWSETRES DUMCALLTYPE DS8OUT::strsetposd(PDS8PCMSTR str,DUMU8B pos)(V0.45以降)

引数
strstrnew() の返値
pos位置(サンプル単位)

処理内容
次回のディコード開始位置をサンプルベースで設定する。
プラグの仕様に因り、対応していなかったり設定位置がずれたりすることがある。

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


DUMU8B DUMCALLTYPE DS8OUT::strgetposd(PDS8PCMSTR str)(V0.45以降)

引数
strstrnew() の返値

処理内容
次回のディコード開始位置を調べる。

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


DWSETRES DUMCALLTYPE DS8OUT::strsetposs(PDS8PCMSTR str,DUMF4B pos)(V0.45以降)

引数
strstrnew() の返値
pos位置(秒単位)

処理内容
次回のディコード開始位置を時間ベースで設定する。
プラグの仕様に因り、対応していなかったり設定位置がずれたりすることがある。

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


DUMF4B DUMCALLTYPE DS8OUT::strgetposs(PDS8PCMSTR str)(V0.45以降)

引数
strstrnew() の返値

処理内容
次回のディコード開始位置を調べる。

返値
ディコード開始位置を秒単位で返す。
エラーの場合は常に0.0が返る。


DWSETRES DUMCALLTYPE DS8OUT::strsetend(PDS8PCMSTR str,DUMU8B pos)(V0.45以降)

引数
strstrnew() の返値
posディコード終了位置(サンプル単位)

処理内容
ディコード終了位置を設定する。この後、設定位置より1つ手前のサンプルをディコードしたところで終了扱いとなる。
ただし、0を設定した場合に限り設定解除として扱い、本来のサンプルデータ終端と同じ位置となる。
プラグの仕様に因り、対応していなかったり設定位置がずれたりすることがある。

strsetloop()と同時に設定した場合の処理はプラグ依存となり、結果は不定。
確実に動作させるには、strsetloop()の設定を解除する必要がある。

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


DWSETRES DUMCALLTYPE DS8OUT::strsetloop(PDS8PCMSTR str,DUMU8B begin,DUMU8B end)(V0.45以降)

引数
strstrnew() の返値
beginループ始端位置(サンプル単位)
endループ終端位置(サンプル単位)

処理内容
ループ位置を設定する。この後、始端から終端の1つ手前のサンプルを繰り返してディコードするようになる。
ただし、endに0を設定した場合に限り設定解除として扱い、ディコードの繰り返しを中止する。
プラグの仕様に因り、対応していなかったり設定位置がずれたりすることがある。

strsetend()と同時に設定した場合の処理はプラグ依存となり、結果は不定。
確実に動作させるには、strsetend()の設定を解除する必要がある。

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


DWERRCODE DUMCALLTYPE DS8OUT::strgetdecsta(PDS8PCMSTR str,PDWDECSTA buf,DUMU4B size)(V0.45以降)

引数
strstrnew() の返値
buf書き出し先
sizesizeof(DWDECSTA)

処理内容
ストリームが扱うサンプルの仕様を書き出す。

返値
DW_ERR_NONE正常
DW_ERR_FATAL異常


DUMBOOL DUMCALLTYPE DS8OUT::strisready(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
ストリームの再生準備が完了しているか調べる。
便宜上、エラーで中断した場合も完了していると見なされる。

返値
0処理中
1処理完了


DUMBOOL DUMCALLTYPE DS8OUT::strisend(PDS8PCMSTR str)(V0.40以降)

引数
strstrnew() の返値

処理内容
ストリームの再生が完了しているか調べる。
便宜上、エラーで中断した場合も完了していると見なされる。

返値
0再生中
1再生完了


LPDIRECTSOUND DUMCALLTYPE DS8OUT::getds(PDS8OUT ds8)

引数
ds8ds8_const() の返値

処理内容
使用中のDirectSoundのインスタンスを得る。
DirectSoundを他の処理で共用したいときに使える。

返値
NULLDirectXが初期化されていない
otherDirectSoundのインスタンス


LPDIRECTSOUNDBUFFER DUMCALLTYPE DS8OUT::getdspri(PDS8OUT ds8)

引数
ds8ds8_const() の返値

処理内容
使用中のプライマリバッファのインスタンスを得る。
プライマリバッファを外部から操作する場合に使えるが、使い方によっては正常動作しなくなることもあるのであまりおすすめしない。

返値
NULLDirectXが初期化されていないか、インスタンスが存在しない。
otherDirectSoundのインスタンス


LPDIRECTSOUNDBUFFER DUMCALLTYPE DS8OUT::getdssec(PDS8OUT ds8,PDS8PCMUNIT unit)

引数
ds8ds8_const() の返値
unitPCM識別タグ(NULL=ストリーム用)

処理内容
使用中のセカンダリバッファのインスタンスを得る。
プライマリバッファを外部から操作する場合に使えるが、使い方によっては正常動作しなくなることもあるのであまりおすすめしない。
(V0.40以降)
ストリーム用セカンダリバッファは取得できない。

返値
NULLDirectXが初期化されていないか、インスタンスが存在しない。
otherDirectSoundのインスタンス


DWERRCODE DUMCALLTYPE DS8OUT::save(PDS8OUT ds8,DUMCSTR file,DUMCSTR plug,DUMU4B ch,DUMU4B sw,DUMU4B mode,DUMCSTR save,DS8CBSAVETIME cbtime,DS8CBSAVEPRGRS cbprgrs)(V0.40以降)

引数
ds8ds8_const() の返値
fileロードするファイル
plugロードに使用するプラグ
chPCM番号
swPCM制禦スウィッチ
mode処理モード(0=通常,1=ストリーム用)
saveセーブ先ファイル
cbtimePCMの長さを取得するコールバック
cbprgrsセーブ中のプログレス処理を行うコールバック

処理内容
PCMをディコードしてファイルに書き出す。
PCMのサンプルが取得できない場合は cbtime() の返値から計算される。
そのとき、cbtime がNULLだったり cbtime() の返値が0だったときはエラーとなる。

返値
DW_ERR_NONE処理に成功
DW_ERR_FATAL処理に失敗
(V0.45以降)
密かに返値の型名が変わってたりするが、互換性は維持してあるので御安心を。


インポート関数


DUMU4B DUMEXPORTTYPE ds8_version(void)(V0.40以降)

返値
DS8OUT.DLLのヴァージョン情報を32bit値で返す。
これは8bitずつ4つのメンバで区切られ、上位から順にアンオフィシャル識別番号,メジャーヴァージョン,マイナーヴァージョン,リリースカウントとなっている。


PDS8OUT DUMEXPORTTYPE ds8_const(PDUMVOID usr,DS8CBALLOC cballoc,DS8CBFREE cbfree)

引数
usrユーザポインタ
コールバック関数が呼ばれるときに渡される任意の値。
cballocメモリを確保するときのコールバック関数
cbfreeメモリを解放するときのコールバック関数

処理内容
DS8OUTのインスタンスを生成する。
cballocとcbfreeを指定した場合、独自のメモリ管理関数を利用することができる。ただし、どちらか一方でもNULLだと無効になり、ディフォルトの処理が使われるようになる。

返値
NULLインスタンスの生成に失敗
otherインスタンスのポインタ
この値はインスタンス関数を呼び出すときに必要であり、インスタンスが存在している間は保持しておかなければならない。


PDS8OUT DUMEXPORTTYPE ds8_const_utl(PDUMVOID usr,PDS8CBTBL cbtbl,DUMU4B tblsize)(V0.40以降)

引数
usrユーザポインタ
コールバック関数が呼ばれるときに渡される任意の値。
cbtblコールバックテーブル
tblsizeコールバックテーブルのサイズ(sizeof(DS8CBTBL))

処理内容
DS8OUTのインスタンスを生成する。
コールバックテーブルを設定することで、メモリ,ファイル管理を独自の関数に置き換えることができる。ただし、それぞれのカテゴリに関連するコールバックテーブルは全て設定しなければならない。1つでもNULLがあるとそのカテゴリは無効になり、ディフォルトの処理が使われるようになる。

返値
NULLインスタンスの生成に失敗
otherインスタンスのポインタ
この値はインスタンス関数を呼び出すときに必要であり、インスタンスが存在している間は保持しておかなければならない。


[表紙]