ホーム > 技術資料 > ezds.dllファイル解析資料(このページ)

ezds.dllファイル解析資料

このページは、XOPSの動作に必要な「ezds.dll」ファイルの解析資料です。

個人利用の範囲であれば構いませんが、データの無断転載は固くお断りします。

本ページに記載されている内容の正確性は保証しませんし、私・管理人は一切の責任を負いません。
このDLLファイルをXOPSとは無関係の他のソフトウェアに転用することは、開発元のnine-two氏の
意向に反する可能性があります。
 ※XOPSの説明書に『データの無断流用はご遠慮ください』という記載がされています。
ezds.dllファイルを‘再配布’する場合は、開発元のnine-two氏へご確認ください。


■ DLLの概要

XOPS本体のexeファイルと同じディレクトリにあるezds.dllファイルは、nine-two氏が独自に開発した
と思われるDLL(ダイナミックリンクライブラリ)で、XOPSのサウンド再生を担っているDLLです。
バージョンを取得(後述)した際に返される情報からして、本DLLの正式名称は「EASY DIRECT SOUND
だと思われます。

サウンド再生には、DirectXの一部であるDirectSoundを用いており、ファイルの読み込みには
Windows Multimedia Extensions(WinMM)を使用しています。

本家XOPSではezds.dllを明示的・動的リンクで利用しています。
ご存じの通り、これがないと「dll load failed」とエラーが出て起動できません。


■ バージョンの採用状況

2013年10月時点でXOPSではバージョンは[0.3]と[0.4]の存在が確認されています。

使用状況は以下の通りです。
 オフライン版
   ・0.90 : ver0.3
   ・0.93 : ver0.3
   ・0.96 : [ver0.4]
 オンライン版
   ・1.6 : ver0.3
   ・1.7 : ver0.3
   ・1.8 : ver0.3
   ・1.9 : ver0.3

なお余談ですが、同じくnine-two氏が開発したゲームである「EA HOCKEY(ver:0.8)」にはver0.3、
「REPULSION ENGINE(ver:0.28)」はver0.4、そして「FEBA:TANX(ver:0.22)」にはXOPSよりも
新しいver0.5が使われています。


■ 関数一覧と仕様

今回は、XOPS 0.96で使われているバージョン[0.4]を調査しました。

ver0.4のDLLで定義されている関数と、その動作は以下の通りです。
  DSinit :DLL初期化
  DSend :DLL解放
  DSload :サウンドファイル個別読み込み
  DSplay :サウンド再生
  DSrelease :サウンドファイル個別解放
  DSver :DLLバージョン情報

なおver0.3では、これらに加えて「DSloadL」と「DSloopOPE」が定義されていますが、「DSrelease」が
ありません。他の関数が同一かどうかは不明です。

サウンドをループ再生させることはできません。
(再生時間を考慮し連続で再生させることで、ループ再生を擬似的に表現可能かもしれません。)
また、サウンドデータを解放することで再生中のサウンドを停止することができますが、解放せずに
停止することはできません。

このDLLは、仕様ともバグ・不具合とも考えられる制限がいくつかあるので、注意が必要です。

サウンドファイルは最大で同時に28個までしか読み込めません。
また、同じ音は同時に3個までしか再生できません。

読み込む各サウンドデータは固有の識別番号(以下「認識番号」と呼びます)で管理しますが、
番号は 0〜27 しか使用することができません。
範囲を超えた番号を使用すると、サウンドの再生に失敗したり、内部で読み込みに失敗し半永久的に
制御を返さなくなる場合があるので注意が必要です。

DSinit()関数でDLL初期化後、最初に実行するDSplay()関数は 数十ミリ秒 程度掛かります。
すなわち、DSplay()関数を初回実行時は、サウンドが再生され制御返ってくるまで一瞬停止します。
 (OS:Win7 64bitで実測 約15〜50ms 程度)
2回目以降 DSplay()関数を呼び出した際には影響ありません。認識番号にも影響しません。


■ 各関数の詳細仕様

それぞれの関数の詳細仕様です。


 宣言:int DSinit(HWND hWnd);
 概略:DLL初期化
 引数:HWND hWnd  ウインドウハンドル
 戻り値:1=成功 0=失敗

DLLを初期化します。
DSver()関数を除く、全ての関数を使用する前に呼び出す必要があります。
有効なサウンド再生デバイスが存在しないと、この関数は失敗します。
この関数が失敗するとDSver()関数以外は使用できません。
ウインドウにDirectXの初期化状況は問いません。
本関数が成功(=1)を返した場合でも、引数に有効なウインドウハンドルを指定しなかった場合、
後述のDSplay()関数の実行には失敗します。


 宣言:void DSend(void);
 概略:DLL解放
 引数:なし
 戻り値:なし

DLLを解放します。
再生中のサウンドはすべて停止します。DSload()関数でサウンドファイルを読み込んでいる場合、
本関数を呼び出すことで自動的に全てのサウンドデータを解放します。
本関数でDLLを解放した後は、再度DSinit()関数で初期化するまで、DSver()関数以外の全ての関数を
呼び出すことができません。


 宣言:int DSload(char* filename, int id);
 概略:サウンドファイル個別読み込み
 引数:char* filename ファイル名
    int id     認識番号(0〜27)
 戻り値:1=成功 0=失敗

指定されたサウンドファイルを読み込み、認識番号に割り当てます。
対応しているファイルはwave形式(.wav)です。
既に使用中の認識番号を再利用する場合は、先にDSrelease()関数で解放してください。
未解放の認識番号を再度指定した場合、元のデータを正しく解放せずデータが上書きされる可能性も
あるため、推奨しません。
無意味ですが、同じサウンドファイルを異なる認識番号に割り当てて読み込むこともできます。


 宣言:int DSplay(int id, int volume, int pan);
 概略:サウンド再生
 引数:int id     認識番号(0〜27)
    int volume   再生音量
    int pan     左右のパン(バランス)
 戻り値:1〜3=成功  0(または 1〜3以外)=失敗

指定した認識番号のサウンドを再生します。
再生音量(volume)は-100〜100が有効です。
100は減衰なし、-100で無音になります。増幅(音量アップ)はできません。
左右のパン(バランス)は、0を基準に 1〜100が右、-1〜-100が左に聞こえます。
本家XOPSでは、常に 0 が指定されています。
(範囲外の値を指定すると、DLLは成功を返しますが前回の音量・パン設定で再生されます。)
サウンド再生中に同じ認識番号のサウンドを再度指定した場合は、重ねて再生されます。


 宣言:void DSrelease(int id);
 概略:サウンドファイル個別解放
 引数:int id     認識番号(0〜27)
 戻り値:なし

指定された認識番号のサウンドデータを解放します。
指定認識番号で再生中のサウンドは停止されますが、同関数で正しく解放せずにDSload()関数で
データを上書きした場合は、サウンドが停止しない場合があります。


 宣言:char* DSver(void);
 概略:DLLバージョン情報
 引数:なし
 戻り値:バージョン情報が書かれた文字列のポインタ

本DLLのバージョン情報を取得します。
ver0.4のDLLの場合「EASY DIRECT SOUND / ver 0.4 / by nine-two」が返されます。
この関数のみ、DSinit()関数を呼び出して初期化する前から利用できます。
なお本家XOPSでは、この関数は使用していません。


⇒ このページを「印刷」する

Copyright (C) 2006-2017 みかん箱. All rights reserved.                ◆ TOPへ 戻る