On Memory PCM Streamサンプル(onmempcm.c)関数仕様

【関数名】
  mpInit - オンメモリPCMサンプルの初期化
【書式】
  void mpInit( void );
【入力】
  なし
【出力】
  なし
【返値】
  なし
【機能】
  内部変数を初期化します。
  このサンプル関数群を用いる時には、一番始めにこの関数を実行してください。
【注意】
  なし
【用例】

---------

【関数名】
  mpOpen - PCMファイルを開きハンドルを取得する。
【書式】
  mpHn *mpOpen( const char *name[], Sint32 num );
【入力】
  name - ファイル名の配列
  num  - チャネル数(nameで指定したファイルの数)
【出力】
  なし
【返値】
  ハンドルのアドレス。もしファイルがないなどの理由で正常終了しなかった場合、
  エラーシグナルとしてNULLが返ります。
【機能】
  指定したPCMファイルを開き、メモリ上に格納します。
  メモリの確保はsyMallocで確保しますので、ある程度の連続した空きメモリ領域を
  必要とします。
  ファイルのオープンに失敗した、メモリが足りないなどの場合、ハンドルの代わりに
  NULLポインタを返します。
【注意】
  本関数は、内部でsyMallocを呼びます。
【用例】
  mpHn *hn;
  char *name[] = { "TEST_L.PCM", "TEST_R.PCM" };

  mpInit();
  hn = mpOpen( name, ( sizeof( name ) / sizeof( name[ 0 ] ) ) );
  if ( hn == NULL ) /* ハンドルのオープンに失敗 */

---------

【関数名】
  mpOpenStatic - PCMファイルを開きハンドルを取得する。
【書式】
  mpHn *mpOpenStatic( const char *name[], void *addr[], Sint32 num );
【入力】
  name - ファイル名の配列
  addr - データを確保するアドレス(ファイル数分だけ別々に用意します)
  num  - チャネル数(nameで指定したファイルの数)
【出力】
  なし
【返値】
  ハンドルのアドレス。もしファイルがないなどの理由で正常終了しなかった場合、
  エラーシグナルとしてNULLが返ります。
【機能】
  指定したPCMファイルを開き、指定されたメモリ上に格納します。
  メモリの管理は、アプリケーション自身で行います。関数内では、特別な
  メモリアロケーションは行いません。
【用例】
  mpHn *hn;
  char *name[] = { "TEST_L.PCM", "TEST_R.PCM" };
  void *addr[] = { ( void * )( 0x8c400000 ), ( void * )( 0x8c480000 ) };
  mpInit();
  hn = mpOpenStatic( name, addr, 2 );
  if ( hn == NULL ) /* ハンドルのオープンに失敗 */

---------

【関数名】
  mpCopyHandle - ハンドルを取得し、別のハンドルからパラメータをコピーする
【書式】
  mpHn *mpCopyHandle( mpHn *hn )
【入力】
  hn - コピー元のハンドル
【出力】
  なし
【返値】
  ハンドルのアドレス。もしファイルがないなどの理由で正常終了しなかった場合、
  エラーシグナルとしてNULLが返ります。
【機能】
  新しいハンドルを取得し、別のハンドルから、パラメータをコピーします。
  コピーされたハンドルが、mpOpenで作成されたものである場合、ここで取得した
  ハンドルがmpCloseされない限りmpCloseすることは出来なくなります。(波形
  データを共有するため)
【注意】
  PCMストリームバッファ番号の設定は必ず行ってください。
【用例】
  mpHn *hn1, *hn2;
  Sint32 port[] = { 1 };
            ;
  hn2 = mpCopyHandle( hn1 );
  mpSetPort( hn2, port, 1 );
  mpPlay( hn2 );

---------

【関数名】
  mpSetPort - サウンドRAM上のPCM Streamバッファの指定
【書式】
  MPE_ERR mpSetPort( mpHn hn*, Sint32 *buffer, Sint32 num );
【入力】
  hn     - PCMハンドルのポインタ
  buffer - PCMストリームバッファ番号を記した配列
  num    - 配列の個数
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  mpOpen、mpOpenStaticで取得したハンドルの各チャネルにサウンドRAMの
  PCMストリームバッファ番号を割り当てます。
  PCMストリームバッファの確保はサウンドクリエイタ側で行い、確保した
  バッファをどのストリームに割り当てるのかを行うのがこの関数の仕事です。
  ここで指定するバッファの数(num)はOpen時に指定したファイルの数と
  同じでなければなりません。
  同じでない場合エラーコードを返します。
【注意】
  本関数を実行しないと、PCMストリームは再生されません。
【用例】
  mpHn   *hn;
  char   *name[] = { "TEST_L.PCM", "TEST_R.PCM" };
  Sint32 *buf[] = { 0, 1 };

  mpInit();
  hn = mpOpen( name, ( sizeof( name ) / sizeof( name[ 0 ] ) ) );
  if ( hn == NULL ) /* ハンドルのオープンに失敗 */
  mpSetPort( hn, buf, 2 );

---------

【関数名】
  mpSetPrm - サンプリング周波数、量子化ビット数の設定
【書式】
  MPE_ERR mpSetPrm( mpHn *hn, Sint32 rate, Sint32 bit );
【入力】
  hn   - PCMハンドルのポインタ
  rate - サンプリング周波数(単位[Hz])
  bit  - 量子化ビット数(単位[Bit])
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  サンプリング周波数および量子化ビット数を設定します。
  サンプリング周波数は単位[Hz]で指定します。内部でOCT/FNSというサウンド
  ブロックの利用する単位系に変換します。
  量子化ビット数に4を入れた場合はADPCMとなります。
  又、本関数を省略すると44.1kHz、16BitのリニアPCMがデフォルト値と
  して利用されます。
  本サンプルではADPCMのループ再生には対応しておりません。予めご了承ください。
【注意】
  本関数ではサンプリング周波数の変換のためにnjLogおよび、njPowの数学関数を
  利用しています。
【用例】
  mpHn   *hn;
  char   *name[] = { "TEST_L.PCM", "TEST_R.PCM" };

  mpInit();
  hn = mpOpen( name, ( sizeof( name ) / sizeof( name[ 0 ] ) ) );
  if ( hn == NULL ) /* ハンドルのオープンに失敗 */
  mpSetPrm( hn, 22050, 8 );

---------

【関数名】
  mpSetBaseVol - 基準音量の設定
【書式】
  MPE_ERR mpSetBaseVol( mpHn *hn, Sint32 vol );
【入力】
  hn  - PCMハンドルのポインタ
  vol - 基準音量値(0〜127)
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  指定したハンドルの基準音量を設定します。デフォルトでは127で最大音量になります。
  この設定値と、mpSetVolの設定値の和が実際の再生音量になります。
【用例】
  mpHn *hn;

  mpSetBaseVol( hn, 90 );
  mpSetVol( hn, 10, 100 ); /* 実際の音量は100になる */

---------

【関数名】
  mpSetPan - 再生定位の設定
【書式】
  MPE_ERR mpSetPan( mpHn *hn, Sint32 pan, Sint32 fade );
【入力】
  hn   - PCMハンドルのポインタ
  pan  - 再生定位値(-127〜127)
  fade - フェード値(0〜32767) 単位 ms
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  指定したハンドルの再生定位を設定します。デフォルトでは0です。
【用例】
  mpHn *hn;

  mpSetPan( hn, -100, 0 ); /* かなり左寄りに再生する。 */

---------

【関数名】
  mpSetVol - 相対音量の設定
【書式】
  MPE_ERR mpSetVol( mpHn *hn, Sint32 vol, Sint32 fade );
【入力】
  hn  - PCMハンドルのポインタ
  vol - 相対音量値(-127〜127)
  fade - フェード値(0〜32767) 単位 ms
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  指定したハンドルの相対音量を設定します。デフォルトでは0です。
  この設定値と、mpSetBaseVolの設定値の和が実際の再生音量になります。
【用例】
  mpHn *hn;

  mpSetVol( hn, -100, 0 ); /* 基準音量はデフォルトなので実際の音量は27になる */

---------

【関数名】
  mpPlay - PCMデータの再生
【書式】
  MPE_ERR mpPlay( mpHn *hn, Sint32 prio );
【入力】
  hn   - PCMハンドルのポインタ
  prio - 再生プライオリティ
【出力】
  なし
【返値】
  エラーコード。正常終了の場合0
【機能】
  指定したPCMハンドルの再生を開始します。
  mpSetPortでPCMストリームバッファ番号の指定をしていない場合は、
  再生されません。
  プライオリティについてはsdPstmPlayに従います。
【用例】
  mpHn   *hn;
  char   *name[] = { "TEST_L.PCM", "TEST_R.PCM" };
  Sint32 *buf[] = { 0, 1 };

  mpInit();
  hn = mpOpen( name, ( sizeof( name ) / sizeof( name[ 0 ] ) ) );
  if ( hn == NULL ) /* ハンドルのオープンに失敗 */
  mpSetPort( hn, buf, 2 );
  mpPlay( hn, 0 )

---------

【関数名】
  mpTask - 定期処理
【書式】
  void mpTask( void );
【入力】
  なし
【出力】
  なし
【返値】
  なし
【機能】
  PCMストリーム処理のための定期処理を行います。
  本関数は、再生したいハンドルの分だけ実行することはありません。
  1Vに一回程度の頻度で実行してください。
【用例】
  while ( -1 ) {
        ;
    mpTask();
        ;
    njWaitVSync();
  }

---------

【関数名】
  mpStop - 再生中のPCMストリームの停止
【書式】
  MPE_ERR mpStop( mpHn *hn );
【入力】
  hn - 再生を止めたいPCMストリームのハンドル
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  再生中のPCMストリームを再生停止します。(ポーズではありません)

---------

【関数名】
  mpClose - ハンドルの開放
【書式】
  MPE_ERR mpClose( mpHn *hn );
【入力】
  hn - 開放するPCMストリームのハンドル
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  PCMストリームハンドルを開放します。
  又、mpOpen関数でハンドルの確保を行っていた場合はデータ用に確保していた
  メモリ空間も併せて開放します。
  mpCopyHandleで、ハンドルがコピーされていた場合、そのハンドルがClose
  されるまではハンドルの開放が行われません。

---------

【関数名】
  mpSetFx - FXの設定
【書式】
  MPE_ERR mpSetFx( mpHn *hn, Sint32 ch, Sint32 lev, Sint32 dep );
【入力】
  hn  - 対象になるPCMストリームのハンドル
  ch  - 入力FXチャネル番号
  lev - FXモジュールへの入力レベル
  dep - FXの深さ
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  PCMストリームにFXをかける場合の諸設定(入力チャネル、入力レベル、深さ)を
  行います。
  本関数で、FXの設定を行い、sdSndSetFx関数でFXプログラムとFXアウト番号を
  かけることで始めてFXをかけることが可能になります。
【用例】
  mpSetFX( hn, 0, 60, 30 );

---------

【関数名】
  mpSetDry - FXのかかっていない音の音量レベルを設定
【書式】
  MPE_ERR mpSetDry( mpHn *hn, Sint32 lev );
【入力】
  hn  - 対象になるPCMストリームのハンドル
  lev - FXのかかっていない音の音量レベル
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  FXをかけた場合、FXのかかった音とかかっていない音がミックスされて出力
  されますが、この時のFXのかかっていない音の音量レベルを設定するのが、
  本関数です。
【用例】
  mpSetDry( hn, 70 );

---------

【関数名】
  mpSetLoop - ループをするしないの設定
【書式】
  MPE_ERR mpSetLoop( mpHn *hn, Bool flag );
【入力】
  hn   - 対象になるPCMストリームのハンドル
  flag - ループをかけるか否か(trueの場合ループをかける)
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  ループをかけるかかけないのかを設定します。
  trueでループONの設定にした場合、ループスタートポイント(指定していない場合
  曲の先頭)からループエンドポイント(指定していない場合曲の最後)までループ
  します。
【用例】
  /* ループする */
  mpSetLoop( hn, true );
  /* ループしない */
  mpSetLoop( hn, false );

---------

【関数名】
  mpSetTransferSize - サウンドRAMへの転送サイズの設定
【書式】
  MPE_ERR mpSetTransferSize( mpHn *hn, Sint32 size );
【入力】
  hn   - 対象になるPCMストリームのハンドル
  size - 転送サイズ(単位バイト)
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  一回のmpTaskでサウンドRAMに転送されるデータサイズを指定します。
  転送サイズは、800Hで割り切れるような値に設定してください。
  もし、800hで割り切れる数でない値が入った場合、強制的に切り捨てられます。
  デフォルト値は1000Hです。
【用例】
  mpSetTransferSize( hn, 0x800 );

---------

【関数名】
  mpChangePlaySample - 再生位置の変更
【書式】
  MPE_ERR mpChangePlaySample( mpHn *hn, Sint32 sample );
【入力】
  hn   - 対象になるPCMストリームのハンドル
  size - 再生位置(単位サンプル)
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  再生位置を変更します。引数はサンプルで実際のメモリアドレスは本関数が
  計算します。
  但し、サンプル数は必ず32サンプルバウンダリでなければなりません。
  もし、32サンプルバウンダリでない値を指定した場合、関数内部で切り捨て
  補正をします。
【注意】
  ADPCMでは再生位置の変更は出来ません。
【用例】
  mpChangePlaySize( hn, 5467 );

---------

【関数名】
  mpSetLoopStart - ループスタートポイントの設定
【書式】
  MPE_ERR mpSetLoopStart( mpHn *hn, Sint32 sample );
【入力】
  hn   - 対象になるPCMストリームのハンドル
  size - ループスタートポイント(単位サンプル)
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  ループスタートポイントをサンプル単位で指定します。
  但し、内部転送ロジック(DMAなど)の仕様により32サンプルバウンダリで
  指定しなければなりません。
  実際にループさせるには、mpSetLoop関数でループ設定をしてください。
  デフォルトは曲の先頭です。
【注意】
  ADPCMではループは出来ません。
【用例】
  mpSetLoopStart( hn, 256 );
  mpSetLoop( hn, true );

---------

【関数名】
  mpSetLoopEnd - ループエンドポイントの設定
【書式】
  MPE_ERR mpSetLoopEnd( mpHn *hn, Sint32 sample );
【入力】
  hn   - 対象になるPCMストリームのハンドル
  size - ループスタートポイント(単位サンプル)
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  ループエンドポイントをサンプル単位で指定します。
  但し、内部転送ロジック(DMAなど)の仕様により32サンプルバウンダリで
  指定しなければなりません。
  実際にループさせるには、mpSetLoop関数でループ設定をしてください。
  デフォルトは曲の先頭です。
【注意】
  ADPCMではループは出来ません。
【用例】
  mpSetLoopEnd( hn, 256 );
  mpSetLoop( hn, true );

---------

【関数名】
  mpSetLoopEndToBottom - ループエンドをデフォルト値に戻す
【書式】
  MPE_ERR mpSetLoopEndToBottom( mpHn *hn );
【入力】
  hn   - 対象になるPCMストリームのハンドル
【出力】
  エラーコード。正常終了の場合0
【返値】
  なし
【機能】
  ループエンドポイントをデフォルト値に戻します。
【注意】
  ADPCMではループは出来ません。

---------

【関数名】
  mpGetStatus - 再生ステータスを取得する
【書式】
  Sint32 mpGetStatus( mpHn *hn );
【入力】
  hn   - 対象になるPCMストリームのハンドル
【出力】
  MP_STAT_IDLE    未使用のハンドル
  MP_STAT_RESERB  まだ、mpSetPort関数が実行されていない
  MP_STAT_STANDBY 再生可能
  MP_STAT_PLAY    再生中
  MP_STAT_PAUSE   ポーズ中
  MP_STAT_STOP    再生停止中
  MP_STAT_END     全波形データ転送終了。曲の再生終了待ち

【返値】
  なし
【機能】
  ループエンドポイントをデフォルト値に戻します。
【注意】
  ADPCMではループは出来ません。

---------------------------------
★MPE_ERRの意味
MPE_ERR_NONE                     エラーはありません。
MPE_ERR_NULL_HANDLE              ハンドルにNULLポインタを渡しています。
MPE_ERR_CHANNEL_NUMBER_MISMATCH  チャネル数はmpSetPortとmpOpenHandleで同じで
                                 なければいけません。
MPE_ERR_UNUSED_HANDLE            未使用のハンドルを指定しています。
MPE_ERR_BUFFER_ATTRIBUTE         指定したPCMストリームリングバッファは存在して
                                 いません。
MPE_ERR_BUFFER_SIZE              ステレオ再生の時は左右のバッファサイズは同じで
                                 なくてはいけません。
MPE_ERR_ILLEGAL_BITRATE          量子化ビット数は16bit、8ビット、4ビット(ADPCM)
                                 以外は再生できません。
MPE_ERR_NOT_PREPARE_TO_PLAY      再生準備が出来ていません。
MPE_ERR_CANT_TO_TRANSFER         リングバッファにデータを送ることが出来ません。
MPE_ERR_CANT_TO_PLAY             何らかの理由で再生が出来ません。
MPE_ERR_BUFFER_IS_USED           このハンドルをコピーし、コピーしたハンドルが
                                 まだバッファを開放していません。
MPE_ERR_ILLEGAL_VOLUME           ボリューム値に規定範囲外の値を入れました。
MPE_ERR_ILLEGAL_FADE             フェード値に規定範囲外の値を入れました。
MPE_ERR_ILLEGAL_PAN              再生定位値に規定範囲外の値を入れました。
MPE_ERR_ILLEGAL_FX_CHANNEL       FXチャネル値に規定範囲外の値を入れました。
MPE_ERR_ADPCM_NOT_FOR_LOOP       ADPCMはループ再生させることは出来ません。
MPE_ERR_SAMPLE_POINT_OVER        ループポイントが、サンプル数を超えています。
MPE_ERR_REGISTER_NULL_FUNCTION   コールバック関数にNULLポインタを指定しようと
                                 しています。
MPE_ERR_TOO_LARGE_TRANSFER_SIZE  一回の転送サイズがリングバッファのサイズよりも
                                 大きくなっています。
