# NNS_SndArcPlayerStartSeq*

## 構文

      #include <nnsys/snd.h>

      BOOL NNS_SndArcPlayerStartSeq( NNSSndHandle* handle, int seqNo );
      BOOL NNS_SndArcPlayerStartSeqEx(
              NNSSndHandle* handle,
              int playerNo,
              int bankNo,
              int playerPrio,
              int seqNo );

## 引数

`handle` | サウンドハンドルのポインタです。
`seqNo` | シーケンス番号です。
`playerNo` | プレイヤー番号です。
`bankNo` | バンク番号です。
`playerPrio` | プレイヤープライオリティです。値の範囲は0〜127で、大きいほど優先度が高くなります。

## 返り値

再生に成功した場合は、TRUEを返します。失敗すると、FALSEが返ります。

## 説明

シーケンスを再生します。

`NNS_SndArcPlayerStartSeq`関数では、プレイヤー番号などのパラメータは、サウンドデータでの指定に基づいて設定されます。 `NNS_SndArcPlayerStartSeqEx`関数を使うと、プレイヤー番号やバンク番号、プレイヤープライオリティをプログラム側で指定できます。ただし、 `playerNo`、`bankNo`、`playerPrio`の引数のうち、-1を指定したものは、サウンドデータで設定したパラメータが使用されます。

あらかじめ、 `NNS_SndArcInit`関数または、 `NNS_SndArcInitOnMemory`関数で サウンドアーカイブが初期化されている必要があります。

サウンドハンドル`handle`は、あらかじめ、`NNS_SndHandleInit`関数で、１度だけ初期化しておかなければなりません。 この関数を呼びだすと、サウンドハンドルに既に結びつけられていたシーケンスは切り離されます（停止するわけではありません）。 再生に成功すると、サウンドハンドルにシーケンスが結びつけられます。

関数内では、必要なサウンドデータがメモリ上にあるかどうかを確認するために、 `NNS_SndArcGetFileAddress`関数を呼びだします。 データがメモリ上にない場合、プレイヤーヒープへのロードを試みます。 プレイヤーヒープが無いまたは、十分なサイズで無い場合には、シーケンスの再生に失敗します。

後で`NNS_SndPlayerStopSeqBySeqNo`関数を使って、 シーケンス番号を指定してシーケンスを停止できるように、 関数内で`NNS_SndPlayerSetSeqNo`関数を呼びだしています。

サウンドデータで設定されている、発音プライオリティや音量の値を再設定したい場合は、シーケンス開始直後に、 `NNS_SndPlayerSetChannelPriority`関数や、 `NNS_SndPlayerSetInitialVolume`関数を呼びだします。

再生の失敗には、以下の原因が考えられます。

- シーケンス番号が無効
- 既に再生中のシーケンスよりも優先度が低い
- データがメモリ上に無いか、ロードに失敗した

## 参照

NNS_SndArcInit, NNS_SndArcInitOnMemory, NNS_SndHandleInit, NNS_SndArcGetFileAddress, NNS_SndPlayerStopSeqBySeqNo, NNS_SndPlayerSetSeqNo, NNS_SndPlayerSetChannelPriority, NNS_SndPlayerSetInitialVolume

## 履歴

2004/11/30 返り値の型が間違っていたのを修正
2004/06/01 NNS_SndArcPlayerStartSeqWithPlayerNoを拡張して、 NNS_SndArcPlayerStartSeqExに変更。 プレイヤーヒープに関する説明を追加。
2004/04/19 NNS_SndArcPlayerStartSeq, NNS_SndArcPlayerStartSeqWithPlayerNoのマニュアルを統合
2004/04/01 初版