PsychPortAudio('AddToSchedule')

[success, freeslots] = PsychPortAudio('AddToSchedule', pahandle [, bufferHandle=0][, repetitions=1][, startSample=0][, endSample=max][, UnitIsSeconds=0][, specialFlags=0]);

'pahandle' で表されるデバイスを使った再生において、現在のスケジュールに新しいアイテム（音）を付け加えます。

あらかじめ、PsychPortAudio('UseSchedule') を使って、スケジュールを作成し有効にしておく必要があります。

返り値'success' はスケジュールへの追加が成功したら１で失敗したら０です。

'freeslots' は追加後にまだ空いているスロットの数です。

スケジュールが一杯であったら新たにアイテムを追加することができません。再生中の場合（で空きスロットがない場合）は、しばらく待つと再生が終了し空きスロットが少なくとも１つはできるので、リトライできます。

再生が停止してアイテムの追加に失敗した場合は、PsychPortAudio('UseSchedule') を使って、より大きなサイズのスケジュールを再設定してください。

スケジュールの再生（または処理）が終了するか、stop関数によって停止したときには、当該スケジュールをクリアするかreactivateして、再度書き込んでください。そうしないと次にStart関数を呼び出したときの動作が、不適切な結果に終わります。

PsychPortAudio('UseSchedule') の enableFlag を２または３にすることで、サイズ変更をすることなく、スケジュールをクリア（reactivate）できます。

以下のパラメーター（引数、オプション）はスケジュールの新しいスロットを設定するために使われます。

'bufferHandle' オーディオバッファへのハンドルです。デフォルトはゼロで、PsychPortAudio('FillBuffer') で作られた標準的なオーディオバッファを再生します。

'repetitions' スロットを何回繰り返し再生するかを指定します。小数の値も可能です。ゼロ（無限の繰り返し）は許可されていません。

'startSample' と 'endSample' は再生ループを定義します。オーディオバッファのなかで再生される部分（subsegment）を厳密に指定します。

'UnitIsSeconds' は、ループする区間が、audio sample framesの単位で表されているのか、秒単位なのかを指定します。

詳しくは'SetLoop' 関数をご覧ください。

'specialFlags' はスロットの処理方法を変更するために使用します。

デフォルトはゼロです。

１のときは、スロットの使用後、スロットは自動的に無効になりませんが、繰り返し回数に応じて再利用されます。

もし、あるスケジュールを手動でリセットコマンドを実行せずに自動的に繰り返したいのであれば、当該スケジュールのすべてのスロットに対して、フラグを設定する必要があります。

（訳注：意味がよく分かっていません）

AddToScheduleを使って特殊なコマンドスロットをスケジュールに組み込むこともできます。

'bufferHandle' に負の整数を指定すると、再生スロットの代わりに、コマンドスロットを定義できます。そして数字がコマンドのコードになります。時間制御に関わる動作については、'repetitions' パラメーターが、 'tWhen' （単位は秒）として扱われます。

以下のコマンドコードが使えます。（数字を足し合わせて、機能を統合することもできます）

1 = Pause audio playback (and capture) immediately, resume it at a given

'tWhen' target time.

2 = (Re-)schedule the end of playback for given 'tWhen' target time.

You must specify the type of 'tWhen' if you specify 1 or 2 as commandCode:+4 =

'tWhen' is an absolute GetSecs() style system time.

+8 = 'tWhen' is a time delta to the last requested start time of playback.

+16 = 'tWhen' is a time delta to the last actual start time of playback.

+32 = 'tWhen' is a time delta to the last requested end time of playback. Broken

& Defective!!

+64 = 'tWhen' is a time delta to the last actual end time of playback. Broken &

Defective!!

E.g., you want to (re)start playback at a certain time, then you'd set

'bufferHandle' to -5, because command code would be 1 + 4 == 5, so negated it is

-5. Then you'd specify the requested time in the 'repetitions' parameter as an

absolute time in seconds.