DualMusik: DS8OUT.DLL

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

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_RDWR DW_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の長さを取得する必要が生じたときに呼ばれる。

・返値

0 PCMの書き出しを行わない。

other PCMの長さを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)

・引数

ds8 ds8_const() の返値

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

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

・引数

ds8 ds8_const() の返値

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

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

・引数

ds8 ds8_const() の返値

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

・返値

DW_ERR_NONE ロック成功

DW_ERR_FATAL ロック失敗

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

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

・引数

ds8 ds8_const() の返値

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

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

・引数

ds8 ds8_const() の返値

side 0=ミュート解除,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)

・引数

ds8 ds8_const() の返値

name WAVEディヴァイス名(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)

・引数

ds8 ds8_const() の返値

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

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

・引数

ds8 ds8_const() の返値

plug ロードに使用するプラグ

buf 文字列を格納するバッファ(NULL=調査用)

size バッファサイズ

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

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

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

・引数

ds8 ds8_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以降)

・引数

ds8 ds8_const() の返値

file 対象のデータファイル

plug ロードに使用するプラグ

ch PCM番号

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以降)

・引数

ds8 ds8_const() の返値

file 対象のデータファイル

plug ロードに使用するプラグ

ch PCM番号

・処理内容
対象の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以降)

・引数

ds8 ds8_const() の返値

file 対象のデータファイル

plug ロードに使用するプラグ

ch PCM番号

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以降)

・処理内容
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以降)

・処理内容
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)

・引数

ds8 ds8_const() の返値

file ロードするファイル

plug ロードに使用するプラグ

ch PCM番号

sw PCM制禦スウィッチ

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

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

・返値

NULL 処理に失敗

other 生成したPCMの識別タグ

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

・引数

~~ds8~~ ~~ds8_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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ

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

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

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ

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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ

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

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

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ~~(NULL=ストリーム用)~~

vol 音量(0=ミュート～ 16384=最大)

・処理内容
DirectSoundのセカンダリバッファの音量を変更する。
聴感上の変化量を調整するため、実際の設定値は -log₂(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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ~~(NULL=ストリーム用)~~

pan 定位(-16384=左～ 0=中央～ +16384=右)

・処理内容
DirectSoundのセカンダリバッファの定位を変更する。
聴感上の変化量を調整するため、実際の設定値は sgn(pan)*10000*log₂(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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ~~(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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ

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)

・引数

~~ds8~~ ~~ds8_const() の返値~~

unit PCM識別タグ

・処理内容
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以降)

・引数

ds8 ds8_const() の返値

wait スレッドのインターバル時間-1(msec)

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

・返値

NULL 処理に失敗

other 生成したコンテクストの識別タグ

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

・引数

str strnew() の返値

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

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

・引数

str strnew() の返値

file ロードするファイル

plug ロードに使用するプラグ

scale ストリームバッファ単位時間(msec)

ch PCM番号

sw PCM制禦スウィッチ

・処理内容
ストリーム再生用に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以降)

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

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

・引数

str strnew() の返値

file ロードするファイル

plug ロードに使用するプラグ

scale ストリームバッファ単位時間(msec)

ch PCM番号

sw PCM制禦スウィッチ

buf DWDECSTA書き出し先

size sizeof(DWDECSTA)

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

・返値

0 正常

other 異常(DirectSoundのエラーコードと同じ)

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

・引数

str strnew() の返値

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

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

・引数

str strnew() の返値

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

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

・引数

str strnew() の返値

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

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

・引数

str strnew() の返値

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

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

・引数

str strnew() の返値

vol 音量(0=ミュート～ 16384=最大)

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

・返値

0 正常

other 異常(DirectSoundのエラーコードと同じ)

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

・引数

str strnew() の返値

pan 定位(-16384=左～ 0=中央～ +16384=右)

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

・返値

0 正常

other 異常(DirectSoundのエラーコードと同じ)

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

・引数

str strnew() の返値

pit 音程(-32768 ～ -256= 半音下～ 0=原音～ +256=半音上～ +32767)

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

・返値

0 正常

other 異常(DirectSoundのエラーコードと同じ)

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

・引数

str strnew() の返値

sw PCM制禦スウィッチ

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

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

・引数

str strnew() の返値

pos 位置(サンプル単位)

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

・返値

DW_SET_SUCCESS 処理成功

DW_SET_UNSTABLE 処理成功だが動作が不正確

DW_SET_FATAL 処理失敗

DW_SET_UNSUPPORT 未対応

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

・引数

str strnew() の返値

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

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

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

・引数

str strnew() の返値

pos 位置(秒単位)

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

・返値

DW_SET_SUCCESS 処理成功

DW_SET_UNSTABLE 処理成功だが動作が不正確

DW_SET_FATAL 処理失敗

DW_SET_UNSUPPORT 未対応

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

・引数

str strnew() の返値

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

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

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

・引数

str strnew() の返値

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以降)

・引数

str strnew() の返値

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以降)

・引数

str strnew() の返値

buf 書き出し先

size sizeof(DWDECSTA)

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

・返値

DW_ERR_NONE 正常

DW_ERR_FATAL 異常

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

・引数

str strnew() の返値

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

・返値

0 処理中

1 処理完了

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

・引数

str strnew() の返値

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

・返値

0 再生中

1 再生完了

LPDIRECTSOUND DUMCALLTYPE DS8OUT::getds(PDS8OUT ds8)

・引数

ds8 ds8_const() の返値

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

・返値

NULL DirectXが初期化されていない

other DirectSoundのインスタンス

LPDIRECTSOUNDBUFFER DUMCALLTYPE DS8OUT::getdspri(PDS8OUT ds8)

・引数

ds8 ds8_const() の返値

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

・返値

NULL DirectXが初期化されていないか、インスタンスが存在しない。

other DirectSoundのインスタンス

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

・引数

ds8 ds8_const() の返値

unit PCM識別タグ~~(NULL=ストリーム用)~~

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

・返値

NULL DirectXが初期化されていないか、インスタンスが存在しない。

other DirectSoundのインスタンス

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

・引数

ds8 ds8_const() の返値

file ロードするファイル

plug ロードに使用するプラグ

ch PCM番号

sw PCM制禦スウィッチ

mode 処理モード(0=通常,1=ストリーム用)

save セーブ先ファイル

cbtime PCMの長さを取得するコールバック

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があるとそのカテゴリは無効になり、ディフォルトの処理が使われるようになる。

[表紙]

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

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

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

usr	ユーザポインタ ds8_constの引数がそのまま
file	ファイル名
f	フラグ

DW_FILE_READ	読み取り可で開くことを示す
DW_FILE_WRITE	書き込み可で開くことを示す
DW_FILE_RDWR	DW_FILE_READ\|DW_FILE_WRITE と同等
DW_FILE_NEW	ファイルを新規に生成することを示す DW_FILE_EXCLが指定されていない場合、既存のファイルは削除される
DW_FILE_EXCL	ファイルが既存であるときは新規に生成できないことを示す
DW_FILE_APPEND	既存のファイルに追記されることを示す

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

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

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

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

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

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

ds8	ds8_const() の返値
side	0=ミュート解除,1=ミュート開始

ds8	ds8_const() の返値
name	WAVEディヴァイス名(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~~	~~ストリーム再生レート~~

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

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

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

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

DW_PCM_TITLE	タイトル
DW_PCM_RIGHT	著作権情報
DW_PCM_ALBUM	アルバム名
DW_PCM_ARTIST	アーティスト名
DW_PCM_YEAR	公表日
DW_PCM_NUMBER	トラックナンバ
DW_PCM_GENRE	ジャンル
DW_PCM_SUBJECT	内容説明(タイトルとは似て非なるもの)

~~ds8~~	~~ds8_const() の返値~~
unit	複製元PCM識別タグ

DS8_PCMSTA_PLAY	再生中
DS8_PCMSTA_LOOP	ループ再生中
DS8_PCMSTA_TERM	(謎; DSBSTATUS_TERMINATEDと同内容)
DS8_PCMSTA_LOST	バッファ消失
DS8_PCMSTA_INVALID	関数呼び出しエラー

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

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

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

str	strnew() の返値
vol	音量(0=ミュート～ 16384=最大)

str	strnew() の返値
pan	定位(-16384=左～ 0=中央～ +16384=右)

str	strnew() の返値
pit	音程(-32768 ～ -256= 半音下～ 0=原音～ +256=半音上～ +32767)

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

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

str	strnew() の返値
begin	ループ始端位置(サンプル単位)
end	ループ終端位置(サンプル単位)

NULL	DirectXが初期化されていない
other	DirectSoundのインスタンス