pxeasy.dll::pxeasy_API

pxeasy_API

pxeasy_ の接頭語を持つ API です。pxtone.dll の API とほぼ同じインターフェースですが、__stdcall 指定がされています。ポインタの概念や、ウィンドウの生成が必要です。

Result 型

typedef  int  Result;

Result ==  1 : 正常終了
Result ==  0 : pxtone.dll の API エラー
Result == -1 : pxeasy.dll の API エラー

API の処理結果を返します。pxtone.dll では BOOL 型でしたが、pxeasy.dll の独自エラーが発生する可能性があるので、Result 型というものを使います。

BOOL 型

typedef  int  BOOL;

Result != 0 : 真
Result == 0 : 偽

真偽を表します。0以外は真、0は偽になります。実体は単なる整数値です。

PXTONEPLAY_CALLBACK

typedef  BOOL  (*PXTONEPLAY_CALLBACK)(long  clock);

@param  clock  : 再生クロック数
@return        : 現在利用されていません (pxtone.dll ver. 0.9.1.4)

ピストンコラージュの再生中、サンプルごとに呼び出されるコールバック関数です。C/C++ で利用する場合は利用可能ですが、他の言語からコールバック関数を渡すのはおそらく難しいです。利用しない場合は NULL を渡してください。

PXTONENOISEBUFFER

typedef struct {
    unsigned char*  p_buf;
    int             size ;
} PXTONENOISEBUFFER;

p_buf  : PCM WAVE データ
size   : PCM WAVE データのバイト数

ピストンノイズを PCM WAVE 形式にビルドしたデータバッファです。再生バッファに書き込めば再生ができ、ディスクに書き込めば保存ができます。

pxeasy_Ready

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 処理結果

ピストンコラージュを生成します。

pxeasy_Ready

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 処理結果

すでに生成されているピストンコラージュを再設定します。

pxeasy_Release

Result  __stdcall pxeasy_Release(void);

@return  : API 処理結果

ピストンコラージュを開放します。

pxeasy_GetDirectSound

void*  __stdcall pxeasy_GetDirectSound(void);

@return  : DirectSound コンポーネントへのポインタ

ピストンコラージュが利用している DirectSound へのポインタを取得します。ピストンコラージュ生成・再設定時に DirectSound を利用しない設定にしている場合は、NULL が返されます。

この API は、ユーザが DirectSound を共有することができますが、開放はピストンコラージュが行うので、開放作業などは行ってはいけません。

pxeasy_GetLastError

const char*  __stdcall pxeasy_GetLastError(void);

@return  : pxtone.dll の API エラー詳細文字列

pxtone.dll の API がエラーした時、この関数で最新のエラー詳細文字列を取得できます。API がエラーした直後に、詳細な情報を知ることができます。

この API は pxtone.dll の API エラーのみを扱います。また、文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_CopyLastError を利用してください。

pxeasy_GetQuality

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  : バッファリングするサンプル数情報格納先

ピストンコラージュの音質設定を取得します。

pxeasy_Tune_Load

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");

pxeasy_Tune_Read

Result  __stdcall pxeasy_Tune_Read(void*  memory_block,
                                   long   bytecount);

@param  memory_block  : メモリブロックへのポインタ
@param  bytecount     : メモリブロックのバイト数
@return               : API 処理結果

メモリから楽曲データを読み込みます。

楽曲データと同等のものがメモリ上にあれば、読み込みが可能です。簡単な例では、ファイルから全てのデータをメモリ上にコピーしたものが相当します。

pxeasy_Tune_Release

Result  __stdcall pxeasy_Tune_Release(void);

@return  : API 処理結果

読み込まれている楽曲データを開放します。

pxeasy_Tune_Start

Result  __stdcall pxeasy_Tune_Start(long  start_sample,
                                    long  fadein_milisecond);

@param  start_sample       : 再生開始サンプル数
@param  fadein_milisecond  : フェードイン時間 (ミリ秒)
@return                    : API 処理結果

読み込まれた楽曲データの演奏を開始します。

pxeasy_Tune_Fadeout

long  __stdcall pxeasy_Tune_Fadeout(long  fadeout_milisecond);

@param  fadeout_milisecond  : フェードアウト時間 (ミリ秒)
@return                     : 再生サンプル数

演奏のフェードアウトを開始し、再生サンプル数を取得します。

pxeasy_Tune_SetVolume

void  __stdcall pxeasy_Tune_SetVolume(float  volume);

@param  volume  : 音量 (0.0f - 1.0f)

楽曲データの音量を設定します。

pxeasy_Tune_Stop

long  __stdcall pxeasy_Tune_Stop(void);

@return  : 再生サンプル数

楽曲データの演奏を停止し、再生サンプル数を取得します。

pxeasy_Tune_IsStreaming

BOOL  __stdcall pxeasy_Tune_IsStreaming(void);

@return  : 現在再生中かどうか

楽曲データが現在再生中かどうかを取得します。

pxeasy_SetLoop

void  __stdcall pxeasy_Tune_SetLoop(BOOL  enable_loop);

@param  enable_loop : ループ再生を有効にするかどうか

楽曲データのループ再生を設定します。

pxeasy_Tune_GetInformation

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   : 小節数情報格納先

楽曲データの情報を取得します。

pxeasy_Tune_GetRepeatMeas

long  __stdcall pxeasy_Tune_GetRepeatMeas(void);

@return  : リピート小節

楽曲データのリピート小節を取得します。

ピストンコラージュはループ再生がゲーム用に特化しています (REPEAT イベント)。例えば16小節の楽曲で、4小節から16小節をループさせるということが可能です。その場合のリピート位置を取得します (例では4小節)。

pxeasy_Tune_GetPlayMeas

long  __stdcall pxeasy_Tune_GetPlayMeas(void);

@return  : 有効演奏小節

楽曲データの有効演奏小節を取得します。

楽曲データによっては、最終小節まで演奏されるとは限りません (LAST イベント)。この関数で、実際に演奏される小節数を正しく得ることが可能です。

pxeasy_Tune_GetName

const char*  __stdcall pxeasy_Tune_GetName(void);

@return  : 楽曲名

楽曲データの楽曲名を取得します。

文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_Tune_CopyName を利用してください。

pxeasy_Tune_GetComment

const char*  __stdcall pxeasy_Tune_GetComment(void);

@return  : 楽曲のコメント

楽曲データのコメントを取得します。

文字列は言語ごとに扱いが違うので、戻り値で取得することができない場合もよくあります。その場合は pxeasyHelper_Tune_CopyComment を利用してください。また、コメントは何も書いていない場合は NULL を返します。

pxeasy_Tune_Vomit

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 データの再生可能な最小単位だからです。

pxeasy_Noise_Create

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 を返します。また、ピストンコラージュが生成されていないなどの場合は無音が書き込まれます。

pxeasy_Noise_Release

void  __stdcall pxeasy_Noise_Release(PXTONENOISEBUFFER*  ptnoise_buffer);

@param  ptnoise_buffer  : ピストンノイズバッファ

ピストンノイズバッファを開放します。

return pxeasy.dll