pxeasy.dll::pxplain_API

pxplain_API

pxplain_ の接頭語を持つ API です。整数型 (int) と文字列型 (char*) のみで構成されたインターフェースで、ポインタ概念のない言語でも利用できる可能性が高いです。

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は偽になります。実体は単なる整数値です。

BufferId 型

typedef  int  BufferId;

Result >   0 : 再生バッファ ID
Result ==  0 : pxtone.dll の API エラー
Result == -1 : pxeasy.dll の API エラー

ピストンノイズを再生するための再生バッファへの ID です。実体は単なる整数値です。

pxplain_Ready

Result  __stdcall pxplain_Ready(int   channel_num,
                                int   sample_per_second,
                                int   bit_per_sample,
                                int   buffer_milisecond,
                                BOOL  use_directsound);

@param  channel_num        : チャンネル数       (1: モノラル, 2: ステレオ)
@param  sample_per_second  : 秒間サンプルレート (44100, 22050, 11025 Hz)
@param  bit_per_sample     : サンプル量子化数   (16, 8 bit)
@param  buffer_milisecond  : バッファリング時間 (100 ミリ秒を推奨)
@param  use_directsound    : DirectSound を利用するかどうか
@return                    : API 処理結果

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

pxplain_Ready

Result  __stdcall pxplain_Reset(int   channel_num,
                                int   sample_per_second,
                                int   bit_per_sample,
                                int   buffer_milisecond,
                                BOOL  use_directsound);

@param  channel_num        : チャンネル数       (1: モノラル, 2: ステレオ)
@param  sample_per_second  : 秒間サンプル数     (44100, 22050, 11025 Hz)
@param  bit_per_sample     : サンプル量子化数   (16, 8 bit)
@param  buffer_milisecond  : バッファリング時間 (1.0 秒を推奨)
@param  use_directsound    : DirectSound を利用するかどうか
@return                    : API 処理結果

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

pxplain_Release

Result  __stdcall pxplain_Release(void);

@return  : API 処理結果

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

pxplain_GetLastError

const char*  __stdcall pxplain_GetLastError(void);

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

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

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

pxplain_CopyLastError

BOOL  __stdcall pxplain_CopyLastError(char*  destination,
                                      int    bytecount);

@param  destination  : pxtone.dll の API エラー詳細文字列格納先
@param  bytecount    : 書き込み可能な文字列のバイト数 (0バイトなら十分なサイズがあると解釈)
@return              : バイト数不足で書き込み切れなかったら偽を返す

pxplain_GetLastError をコピーで取得します。

利用側で文字列の格納先を作成し、そこにコピーしてもらうことで pxplain_GetLastError の情報を取得します。データをコピーするだけの処理なので、文字列の扱いが C/C++ と異なる他の言語でも利用できる可能性があります。

pxplain_GetChannelNum

int  __stdcall pxplain_GetChannelNum(void);

@return  : チャンネル数

ピストンコラージュが設定しているチャンネル数を取得します。

pxplain_GetSamplePerSecond

int  __stdcall pxplain_GetSamplePerSecond(void);

@return  : 秒間サンプル数

ピストンコラージュが設定している秒間サンプル数を取得します。

pxplain_GetBitPerSample

int  __stdcall pxplain_GetBitPerSample(void);

@return  : サンプル量子化数

ピストンコラージュが設定しているサンプル量子化数を取得します。

pxplain_GetSamplePerBuffer

int  __stdcall pxplain_GetSamplePerBuffer(void);

@return  : バッファリングのサンプル数

ピストンコラージュがバッファするサンプル数を取得します。

pxplain_Tune_Load

Result  __stdcall pxplain_Tune_Load(const char*  filepath);

@param  filepath  : ファイルパス

ファイルから楽曲データを読み込みます。

pxplain_Tune_Release

Result  __stdcall pxplain_Tune_Release(void);

@return  : API 処理結果

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

pxplain_Tune_Start

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

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

再生開始サンプル数を渡すことで、その位置から再生を開始します。「サンプル」とは、PCM データの最小単位です。秒間サンプルレートから逆算もできますが、pxplain_Tune_Stop, pxplain_Tune_Fadeout から停止位置として取得することもできます。

pxplain_Tune_Fadeout

int  __stdcall pxplain_Tune_Fadeout(int  fadeout_milisecond);

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

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

pxplain_Tune_SetVolume

void  __stdcall pxplain_Tune_SetVolume(int  volume_percentage);

@param  volume  : 音量 (0 - 100)

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

pxplain_Tune_Stop

int  __stdcall pxplain_Tune_Stop(void);

@return  : 再生サンプル数

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

pxplain_Tune_IsStreaming

BOOL  __stdcall pxplain_Tune_IsStreaming(void);

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

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

pxplain_SetLoop

void  __stdcall pxplain_Tune_SetLoop(BOOL  enable_loop);

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

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

pxplain_Tune_GetBeatNum

int __stdcall pxplain_Tune_GetBeatNum(void);

@return  拍子数

楽曲データの拍子数を取得します。

pxplain_Tune_GetBeatTempoPercentage

int  __stdcall pxplain_Tune_GetBeatTempoPercentage(void);

@return  拍子のテンポ

楽曲データの拍子のテンポを取得します。

pxplain_Tune_GetBeatClock

int  __stdcall pxplain_Tune_GetBeatClock(void);

@return  拍子のクロック

楽曲データの拍子のクロックを取得します。

pxplain_Tune_GetMeasNum

int  __stdcall pxplain_Tune_GetMeasNum(void);

@return  全体の小節数

楽曲全体の小節数を取得します。

pxplain_Tune_GetRepeatMeas

long  __stdcall pxplain_Tune_GetRepeatMeas(void);

@return  : リピート小節

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

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

pxplain_Tune_GetPlayMeas

long  __stdcall pxplain_Tune_GetPlayMeas(void);

@return  : 有効演奏小節

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

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

pxplain_Tune_GetName

const char*  __stdcall pxplain_Tune_GetName(void);

@return  : 楽曲名

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

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

pxplain_Tune_CopyName

BOOL  __stdcall pxplain_Tune_CopyName(char*  destination,
                                      int    bytecount);

@param  destination  : 楽曲名文字列格納先
@param  bytecount    : 書き込み可能な文字列のバイト数 (0バイトなら十分なサイズがあると解釈)
@return              : バイト数不足で書き込み切れなかったら偽を返す

pxplain_Tune_GetName をコピーで取得します。

利用側で文字列の格納先を作成し、そこにコピーしてもらうことで pxplain_Tune_GetName の情報を取得します。データをコピーするだけの処理なので、文字列の扱いが C/C++ と異なる他の言語でも利用できる可能性があります。

pxplain_Tune_GetComment

const char*  __stdcall pxplain_Tune_GetComment(void);

@return  : 楽曲のコメント

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

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

pxplain_Tune_CopyComment

BOOL  __stdcall pxplain_Tune_CopyComment(char*  destination,
                                         int    bytecount);
@param  destination  : コメント文字列格納先
@param  bytecount    : 書き込み可能な文字列のバイト数 (0バイトなら十分なサイズがあると解釈)
@return              : バイト数不足で書き込み切れなかったら偽を返す

pxplain_Tune_GetComment をコピーで取得します。

利用側で文字列の格納先を作成し、そこにコピーしてもらうことで pxplain_Tune_GetComment の情報を取得します。データをコピーするだけの処理なので、文字列の扱いが C/C++ と異なる他の言語でも利用できる可能性があります。

もし、コメントに何も書いていなければ空文字をコピーして返します。

pxplain_Tune_GetPlayClock

int  __stdcall pxplain_Tune_GetPlayClock(void);

@return  : 再生クロック数

現在の再生クロック数を取得します。これは本来 PXTONEPLAY_CALLBACK 内で取得できる情報ですが、コールバックの利用が不可能なのでこの関数で代わりに取得することができます。

楽曲データが再生中でなければ意味のない不定な値です。

pxplain_Noise_Create

BufferId  __stdcall pxplain_Noise_Create(const char*  filepath,
                                         int          channel_num,
                                         int          sample_per_second,
                                         int          bit_per_sample);

@param  filepath           : ファイルパス
@param  channel_num        : チャンネル数       (1: モノラル, 2: ステレオ)
@param  sample_per_second  : 秒間サンプル数     (44100, 22050, 11025 Hz)
@param  bit_per_sample     : サンプル量子化数   (16, 8 bit)
@return                    : ピストンノイズ再生バッファ ID

ピストンノイズから再生可能なサウンドバッファを生成し、その ID を返します。

pxtone.dll とは異なり、再生可能なサウンドバッファを生成するため、そのまま効果音再生として利用できます。

ファイルが見つからないなどのエラー発生時は戻り値に 0, -1 を返します。また、ピストンコラージュが生成されていないなどの場合は無音が書き込まれます。

pxplain_Noise_Play

Result  __stdcall pxplain_Noise_Play(BufferId  buffer_id,
                                     int       priority,
                                     BOOL      enable_loop);

@param  buffer_id    : ピストンノイズ再生バッファ ID
@param  priority     : 再生優先度 (32bit の符号なし整数値範囲内)
@param  enable_loop  : ループ再生を有効にするかどうか
@return              : API 処理結果

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

pxplain_Noise_Stop

Result  __stdcall pxplain_Noise_Stop(BufferId  buffer_id);

@param  buffer_id  : ピストンノイズ再生バッファ ID
@return            : API 処理結果

ピストンノイズ再生バッファを停止します。

pxplain_Noise_Release

Result  __stdcall pxplain_Noise_Release(BufferId  buffer_id);

@param  buffer_id  : ピストンノイズ再生バッファ ID
@return            : API 処理結果

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

return pxeasy.dll