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  一回の転送サイズがリングバッファのサイズよりも
                                 大きくなっています。

★構造体の仕様
○mpHn構造体の中身
  ch          各チャネルに関する個別の情報
  Hn          PCMストリームハンドル
  Status      ハンドルの状態(再生ステータス等)
  NumOfCh     チャネル数
  Size        PCMデータのデータサイズ
  Current     メインメモリ側にある波形データの次にサウンドRAMに転送する
              転送開始位置(先頭からのオフセットで単位バイト)
  OctFns      サンプリングレート(OCT/FNS)
  Freq        サンプリングレート(Hz)
  Time        再生時間(タイマカウンタ値)
  StartTime   再生開始時のタイマカウンタ値
  Bit         量子化ビット数(単位ビット)
  BaseVol     ベースボリューム
  FxChn       FX Inputチャネル番号
  TrnsSize    mpTask一回の転送サイズ
  Prio        再生プライオリティ(sdPstmPlayの第三引数)
  LoopStart   ループスタート位置(先頭からのオフセットで単位バイト)
  LoopEnd     ループエンド位置(先頭からのオフセットで単位バイト)
  NumOfCopy   mpCopyHandleでハンドルがコピーされた時にインクリメントされる。
              そのハンドルの波形データが他のハンドルと共用されているのに、
              そのハンドルで管理している、メインRAM用の波形用に確保されている
              メモリが開放されているのを防ぐためにあります。
  Parent      他のハンドルにコピーされていたら、そのハンドルのポインタ
  LFOStart    コールバック呼び出し時のタイマカウンタ値
  LFOcb       コールバック関数のポインタ
  LFO         コールバックを呼び出すか否かを示すフラグ
  Loop        ループするか否かを示すフラグ
  Malloc      syMallocを使ってサウンドデータエリアを確保したか(メインRAM側)
              syMallocを使っていたら、ハンドル消去時にメインRAMの波形データ
              領域はsyFreeを使用して開放されます。

○_PortInfo_構造体の中身
  port    リングバッファ番号(サウンドRAM側)
  start   波形データの先頭アドレス(メインRAM側)
  vol     カレントボリューム
  pan     再生定位
  baddr   リングバッファの先頭アドレス(サウンドRAMの先頭からのオフセット)
  bsize   リングバッファのサイズ(単位バイト)
