PsychPortAudio('FillBuffer')

[underflow, nextSampleStartIndex, nextSampleETASecs] = PsychPortAudio('FillBuffer', pahandle, bufferdata [, streamingrefill=0][, startIndex=Append]);

PortAudioデバイスの再生用のバッファに音声データを埋め込みます。

'pahandle' はデバイスのハンドルで、そのデバイスのバッファにデータが埋め込まれます。

'bufferdata' は一般的にはdouble()型か、single()型の行列になります。それぞれの行はサウンドチャンネルを表し、それぞれの列は１サンプルを表します。

浮動小数点（floating point values）のみがサポートされています。サンプルのレンジは、-1.0 から +1.0 で、0.0 は無音を表します。これは意図的に制約されたインターフェースです。なるべくlantecyが低くなるように、時間制御がよくなるようにするため、最適なフォーマットとサンプリングレートで音声データを作成してください。so the driver can safe computation time and latency for expensive sample rate conversion, sample format conversion, and bounds checking/clipping.

行列の代わりに、'bufferdata'としてオーディオバッファのハンドルを渡すこともできます。このバッファはPsychPortAudio('CreateBuffer', ...) 関数を使って、あらかじめ作成しておかなくてはいけません。バッファの内容は行列の満たすべき制約を同様に

満たしておかなくてはいけません。

バッファの内容は、与えられたバッファから標準のオーディオバッファにコピーされます。そのため、望むのであれば安全に元のバッファを削除できます。

'streamingrefill' オプションです。１にセットしたとき、再生中、ドライバーによってバッファに再度データが埋め込まれます（refill）。言い換えれば、バッファにすでに存在するオーディオデータに、新しくデータを追加できるということです。これはストリーミング再生や、live audio feedback loopsを作る際に便利です。

しかしながら、現在の実装では本当にオーディオデータを付加するわけではありません。代わりに、すでに再生中のオーディオデータに新しいデータを付け加えて、それと入れ替えるのです。つまり、実際に再生されているもの以上にrefillしようとする場合は、この関数は十分なストレージスペース（空き容量）が利用可能になるまで待ちます。

'streamingrefill' に２をセットしたときは、ただちに（十分なバッファスペースが利用可能になるのを待たずに）refillします。その結果、変なふうに聞こえたり（audible artifacts）、サウンドデータが上書きされたりします。これは非常に特殊な状況（a few very special audio feedback tricks）でのみ使用価値があります。以上のことを理解している場合のみ、使用して下さい。

バッファの許容量をオーバーする形でrefillしたときは失敗するでしょう。

デフォルトでは、ストリーミングrefillはしません。つまり、バッファは、再生が停止している間のin one batchでデータが埋め込まれます。このようなrefillは、'SetLoop' 関数で設定された繰り返し再生（playloop）を、refillされたバッファーの全体のサイズにリセットします。

もし'streamingrefill' がゼロではなく、引数'startIndex' が与えられた場合は、refillは線形サンプルインデックスにおいて実行されます。もし引数'startIndex' が与えられなかった場合は、新しいデータは、現在のサウンドバッファーの最後に付け加えられます。

ストリーミングrefillの条件下でなければ、'startIndex' は無視されます。

返り値 'underflow' について。

１ならば、refillが間に合わず、オーディオバッファーがアンダーフローを起こした。つまり、再生中に不具合が生じており、その後の再生にも支障を来している。

返り値 'nextSampleStartIndex' について。

'FillBuffer' 関数を呼び出しているあいだに付け加えられた最新の（最後の）サンプルのあとに続くサンプルを再生してからの、インデックス（絶対値）です。つまり、継続した'FillBuffer' の、第１番目のサンプルです。

返り値 'nextSampleETASecs' について。

再生中でなければ、未定義（NaN）です。

ストリーミングrefillのあいだ、'nextSampleStartIndex'で指定されるサンプルの、秒単位での予想されるオンセット時刻を含んでいます。この予測は、バッファがかなりあとに再生されるサンプルを含むほどに大きいときは、予期エラーが蓄積されるので注意してください。