pxeasy_ の接頭語を持つ API です。pxtone.dll の API とほぼ同じインターフェースですが、__stdcall 指定がされています。ポインタの概念や、ウィンドウの生成が必要です。
typedef int Result; Result == 1 : 正常終了 Result == 0 : pxtone.dll の API エラー Result == -1 : pxeasy.dll の API エラー
API の処理結果を返します。pxtone.dll では BOOL 型でしたが、pxeasy.dll の独自エラーが発生する可能性があるので、Result 型というものを使います。
typedef int BOOL; Result != 0 : 真 Result == 0 : 偽
真偽を表します。0以外は真、0は偽になります。実体は単なる整数値です。
typedef BOOL (*PXTONEPLAY_CALLBACK)(long clock); @param clock : 再生クロック数 @return : 現在利用されていません (pxtone.dll ver. 0.9.1.4)
ピストンコラージュの再生中、サンプルごとに呼び出されるコールバック関数です。C/C++ で利用する場合は利用可能ですが、他の言語からコールバック関数を渡すのはおそらく難しいです。利用しない場合は NULL を渡してください。
typedef struct { unsigned char* p_buf; int size ; } PXTONENOISEBUFFER; p_buf : PCM WAVE データ size : PCM WAVE データのバイト数
ピストンノイズを PCM WAVE 形式にビルドしたデータバッファです。再生バッファに書き込めば再生ができ、ディスクに書き込めば保存ができます。
Result __stdcall pxeasy_Ready(HWND window_handle, long channel_num, long sample_per_second, long bit_per_sample, float buffer_second, BOOL use_directsound, PXTONEPLAY_CALLBACK play_callback); @param window_handle : ウィンドウハンドル (NULL 不可) @param channel_num : チャンネル数 (1: モノラル, 2: ステレオ) @param sample_per_second : 秒間サンプルレート (44100, 22050, 11025 Hz) @param bit_per_sample : サンプル量子化数 (16, 8 bit) @param buffer_second : バッファリング時間 (1.0 秒を推奨) @param use_directsound : DirectSound を利用するかどうか @param play_callback : 再生サンプルごとのコールバック @return : API 処理結果
ピストンコラージュを生成します。
Result __stdcall pxeasy_Reset(HWND window_handle, long channel_num, long sample_per_second, long bit_per_sample, float buffer_second, BOOL use_directsound, PXTONEPLAY_CALLBACK play_callback); @param window_handle : ウィンドウハンドル (NULL 不可) @param channel_num : チャンネル数 (1: モノラル, 2: ステレオ) @param sample_per_second : 秒間サンプル数 (44100, 22050, 11025 Hz) @param bit_per_sample : サンプル量子化数 (16, 8 bit) @param buffer_second : バッファリング時間 (1.0 秒を推奨) @param use_directsound : DirectSound を利用するかどうか @param play_callback : 再生サンプルごとのコールバック @return : API 処理結果
すでに生成されているピストンコラージュを再設定します。
Result __stdcall pxeasy_Release(void); @return : API 処理結果
ピストンコラージュを開放します。
void* __stdcall pxeasy_GetDirectSound(void); @return : DirectSound コンポーネントへのポインタ
ピストンコラージュが利用している DirectSound へのポインタを取得します。ピストンコラージュ生成・再設定時に DirectSound を利用しない設定にしている場合は、NULL が返されます。
この API は、ユーザが DirectSound を共有することができますが、開放はピストンコラージュが行うので、開放作業などは行ってはいけません。
const char* __stdcall pxeasy_GetLastError(void); @return : pxtone.dll の API エラー詳細文字列
pxtone.dll の API がエラーした時、この関数で最新のエラー詳細文字列を取得できます。API がエラーした直後に、詳細な情報を知ることができます。
この API は pxtone.dll の API エラーのみを扱います。また、文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_CopyLastError を利用してください。
void __stdcall pxeasy_GetQuality(long* channel_num_destination, long* sample_per_second_destination, long* bit_per_sample_destination, long* sample_per_buffer_destination); @param channel_num_destination : チャンネル数情報格納先 @param sample_per_second_destination : 秒間サンプル数情報格納先 @param bit_per_sample_destination : サンプル量子化数情報格納先 @param sample_per_buffer_destination : バッファリングするサンプル数情報格納先
ピストンコラージュの音質設定を取得します。
Result __stdcall pxeasy_Tune_Load(HMODULE module_handle, const char* resource_typename, const char* source_name); @param module_handle モジュールハンドル @param resource_typename リソースタイプ名 @param source_name ソース名
ファイル・リソースから楽曲データを読み込みます。
モジュールハンドルは、アプリケーション (DLL) のエントリポイントで取得できるインスタンスハンドルでも可能です。NULL でも問題ないそうですが、リソースがうまく読み込めない場合は正確な値を渡してみてください。
リソースタイプ名は、リソースをアプリケーションに組み込む際に設定したタイプ名です。ファイルを読み込む際は NULL になります。
ソース名はファイルならファイル名、リソースならリソース名です。
// ファイルから読み込む場合 pxeasy_Tune_Load(NULL, NULL, filepath); // カスタムリソースを次のように設定する MUSIC_001 PTTUNE "music_001.pttune" // リソースから読み込む場合 pxeasy_Tune_Load(instance_handle, "PTTUNE", "MUSIC_001");
Result __stdcall pxeasy_Tune_Read(void* memory_block, long bytecount); @param memory_block : メモリブロックへのポインタ @param bytecount : メモリブロックのバイト数 @return : API 処理結果
メモリから楽曲データを読み込みます。
楽曲データと同等のものがメモリ上にあれば、読み込みが可能です。簡単な例では、ファイルから全てのデータをメモリ上にコピーしたものが相当します。
Result __stdcall pxeasy_Tune_Release(void); @return : API 処理結果
読み込まれている楽曲データを開放します。
Result __stdcall pxeasy_Tune_Start(long start_sample, long fadein_milisecond); @param start_sample : 再生開始サンプル数 @param fadein_milisecond : フェードイン時間 (ミリ秒) @return : API 処理結果
読み込まれた楽曲データの演奏を開始します。
long __stdcall pxeasy_Tune_Fadeout(long fadeout_milisecond); @param fadeout_milisecond : フェードアウト時間 (ミリ秒) @return : 再生サンプル数
演奏のフェードアウトを開始し、再生サンプル数を取得します。
void __stdcall pxeasy_Tune_SetVolume(float volume); @param volume : 音量 (0.0f - 1.0f)
楽曲データの音量を設定します。
long __stdcall pxeasy_Tune_Stop(void); @return : 再生サンプル数
楽曲データの演奏を停止し、再生サンプル数を取得します。
BOOL __stdcall pxeasy_Tune_IsStreaming(void); @return : 現在再生中かどうか
楽曲データが現在再生中かどうかを取得します。
void __stdcall pxeasy_Tune_SetLoop(BOOL enable_loop); @param enable_loop : ループ再生を有効にするかどうか
楽曲データのループ再生を設定します。
void __stdcall pxeasy_Tune_GetInformation(long* beat_num_destination, float* beat_tempo_destination, long* beat_clock_destination, long* meas_num_destination); @param beat_num_destination : 拍子数情報格納先 @param beat_tempo_destination : 拍子テンポ情報格納先 @param beat_clock_destination : 拍子クロック情報格納先 @param meas_num_destination : 小節数情報格納先
楽曲データの情報を取得します。
long __stdcall pxeasy_Tune_GetRepeatMeas(void); @return : リピート小節
楽曲データのリピート小節を取得します。
ピストンコラージュはループ再生がゲーム用に特化しています (REPEAT イベント)。例えば16小節の楽曲で、4小節から16小節をループさせるということが可能です。その場合のリピート位置を取得します (例では4小節)。
long __stdcall pxeasy_Tune_GetPlayMeas(void); @return : 有効演奏小節
楽曲データの有効演奏小節を取得します。
楽曲データによっては、最終小節まで演奏されるとは限りません (LAST イベント)。この関数で、実際に演奏される小節数を正しく得ることが可能です。
const char* __stdcall pxeasy_Tune_GetName(void); @return : 楽曲名
楽曲データの楽曲名を取得します。
文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_Tune_CopyName を利用してください。
const char* __stdcall pxeasy_Tune_GetComment(void); @return : 楽曲のコメント
楽曲データのコメントを取得します。
文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_Tune_CopyComment を利用してください。また、コメントは何も書いていない場合は NULL を返します。
BOOL __stdcall pxeasy_Tune_Vomit (void* write_point, long sample_num); @param write_point : PCM WAVE データ書き込み位置へのポインタ @param sample_num : 書き込むサンプル数 @return : 終了するまで真を返す
楽曲データを PCM WAVE データとして書き込み位置にコピーします。
これは、独自の再生エンジンで楽曲データを利用する際のデコーダ、ファイル保存のための出力関数として利用できます。この関数の利用にはいくらか条件があります。
まず、ピストンコラージュ生成時にバッファリング時間を 0 秒に設定してください。そして、この関数が実行される前に再生を開始していなければなりません。
書き込む PCM WAVE データサイズはバイト数ではなくサンプル数で指定します。これは、サンプルが PCM WAVE データの再生可能な最小単位だからです。
PXTONENOISEBUFFER* __stdcall pxeasy_Noise_Create(const char* source_name, const char* resource_typename, long channel_num, long sample_per_second, long bit_per_sample); @param source_name : ソース名 @param resource_typename : リソースタイプ名 @param channel_num : チャンネル数 (1: モノラル, 2: ステレオ) @param sample_per_second : 秒間サンプル数 (44100, 22050, 11025 Hz) @param bit_per_sample : サンプル量子化数 (16, 8 bit) @return : ピストンノイズバッファ
ピストンノイズを読み込み、バッファを返します。
ソース名はファイル名、リソース名のどちらかです。リソースを読み込む場合はリソースタイプ名も指定します。
ファイルが見つからないなどのエラー発生時は戻り値に NULL を返します。また、ピストンコラージュが生成されていないなどの場合は無音が書き込まれます。
void __stdcall pxeasy_Noise_Release(PXTONENOISEBUFFER* ptnoise_buffer); @param ptnoise_buffer : ピストンノイズバッファ
ピストンノイズバッファを開放します。