Class QueueSink
ビデオキャプチャデバイスから受信したすべての画像を、プログラム側で処理できるようにするシンク実装です。
実装
継承されたメンバ
Namespace: ic4
Assembly: ic4dotnet.dll
構文
public class QueueSink : Sink, IDisposable備考
キューシンクは、2つのキューで構成された複数のバッファを管理します。
- デバイスからのデータを書き込むために使用される、空きバッファを保持するフリーキュー
- データが格納され、プログラムが取得可能な状態となったバッファを保持する出力キュー
キューシンクを作成するには、いずれかのコンストラクタ （QueueSink(PixelFormat, IBufferAllocator, int) または QueueSink(IEnumerable<PixelFormat>, IBufferAllocator, int)） を使用します。
作成したシンクは、StreamSetup(Sink, IDisplay, StreamSetupOption) またはStreamSetup(Sink, StreamSetupOption) に渡すことで、画像データがシンクへ送られるようになります。
通常、キューシンクとのやり取りは、シンクのイベントに対してハンドラを登録することで行います。これらのイベントは、キューシンクのライフサイクルにおける重要なタイミングで発生します。
- SinkConnected： デバイスからシンクへのデータストリームが設定される際に発生します。 このイベントハンドラでは、ストリーミングを開始できるよう、十分な数のバッファがキューに投入されていることを保証する必要があります。
- FramesQueued： 出力キューに利用可能な画像が存在するたびに発生します。
- SinkDisconnected： 以前に作成されたデータストリームが停止した際に発生します。
出力キューから最も古い画像を取得するには、PopOutputBuffer() またはTryPopOutputBuffer(out ImageBuffer) を呼び出します。返されるイメージバッファはプログラム側の所有物となります。そのバッファが不要になった場合は、Dispose() を呼び出して、シンクのフリーキューへ返却する必要があります。
プログラムは、すべてのイメージバッファを直ちに再キューイングする必要はなく、一部を独自のデータ構造内で保持することも可能です。ただし、デバイスがフレームを配信しようとした際にフリーキュー内にバッファが存在しない場合、そのフレームは破棄されます。 バッファアンダーランが発生したかどうかは、StreamStatisticsで確認できます。
コンストラクタ
QueueSink(IEnumerable<PixelFormat>, IBufferAllocator, int)
新しいキューシンクを作成します。
宣言
public QueueSink(IEnumerable<PixelFormat> acceptedPixelFormats = null, IBufferAllocator customAllocator = null, int maxOutputBuffers = 0)パラメータ
| 型 | 名前 | 説明 |
|---|---|---|
| IEnumerable<PixelFormat> | acceptedPixelFormats | このシンクへの入力を制限するための、ピクセルフォーマットの任意のリストです。この指定により、デバイスのピクセルフォーマットから、シンクで使用可能なピクセルフォーマットへの自動変換を強制できます。 |
| IBufferAllocator | customAllocator | 任意で指定可能なカスタムバッファアロケータです。 |
| int | maxOutputBuffers | シンクの出力キューに格納されるバッファの最大数を定義します。0を指定した場合、バッファ数は無制限となります。新しいフレームがシンクに到着し、出力キューのサイズがこの数を超える場合、最も古い画像が破棄され、そのバッファはフリーキューに追加されます。 |
例外
| 型 | 条件 |
|---|---|
| ArgumentException | maxOutputBuffers が 0 未満の場合 |
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
QueueSink(PixelFormat, IBufferAllocator, int)
新しいキューシンクを作成します。
宣言
public QueueSink(PixelFormat acceptedPixelFormat, IBufferAllocator customAllocator = null, int maxOutputBuffers = 0)パラメータ
| 型 | 名前 | 説明 |
|---|---|---|
| PixelFormat | acceptedPixelFormat | このシンクへの入力を制限するピクセルフォーマット。 デバイスのピクセルフォーマットから、シンクで使用可能なピクセルフォーマットへ自動変換を強制するために使用できます。 |
| IBufferAllocator | customAllocator | 任意のカスタムバッファアロケータ。 |
| int | maxOutputBuffers | シンクの出力キューに保持されるバッファの最大数を定義します。 0 を指定した場合、バッファ数は無制限となります。 新しいフレームがシンクに到着し、出力キューのサイズがこの数を超える場合、最も古い画像は破棄され、そのバッファはフリーキューに戻されます。 |
例外
| 型 | 条件 |
|---|---|
| ArgumentException | maxOutputBuffers が 0 未満の場合 |
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
プロパティ
IsCancelRequested
このシンクが接続されているデータストリームが、停止処理中かどうかを示します。
宣言
public bool IsCancelRequested { get; }プロパティ値
| 型 | 説明 |
|---|---|
| bool | true：このシンクへのデータストリームが停止処理中の場合、false：それ以外の場合。 |
例外
| 型 | 条件 |
|---|---|
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
OutputImageType
このシンクが受信するように設定されている画像の種類。
宣言
public ImageType OutputImageType { get; }プロパティ値
| 型 | 説明 |
|---|---|
| ImageType | このシンクが受信するように設定されている画像の種類 |
例外
| 型 | 条件 |
|---|---|
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
QueueSizes
シンク内の各キューの長さ。
宣言
public QueueSinkQueueSizes QueueSizes { get; }プロパティ値
| 型 | 説明 |
|---|---|
| QueueSinkQueueSizes | シンクの現在のキューサイズに関する情報を含む構造体 |
例外
| 型 | 条件 |
|---|---|
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
メソッド
AllocAndQueueBuffers(int)
シンクのイメージタイプに一致する数のバッファを割り当て、フリーキューに追加します。
宣言
public void AllocAndQueueBuffers(int count)パラメータ
| 型 | 名前 | 説明 |
|---|---|---|
| int | count | 割り当てるバッファの数 |
例外
| 型 | 条件 |
|---|---|
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
PopOutputBuffer()
シンクの出力キューから、画像データで満たされたバッファを取得します。
宣言
public ImageBuffer PopOutputBuffer()戻り値
| 型 | 説明 |
|---|---|
| ImageBuffer | 画像データが格納されたイメージバッファ |
備考
この操作は、シンクがデータストリーム内でデバイスに接続されている間のみ有効です。
バッファはビデオキャプチャデバイスから受信した順に取得され、最も古い画像が最初に返されます。
正常に呼び出された後、プログラムは ImageBuffer 参照を通じてイメージバッファの所有権を持ちます。後で再利用するためにシンクのフリーキューへ戻すには、イメージバッファオブジェクトを Dispose する必要があります。
例外
| 型 | 条件 |
|---|---|
| IC4Exception | 詳細については ErrorCode および ToString() を確認してください。 |
TryPopOutputBuffer(out ImageBuffer)
シンクの出力キューから、画像データで満たされたバッファの取得を試みます。
PopOutputBuffer() と異なり、この関数はエラー発生時に例外をスローしません。
宣言
public bool TryPopOutputBuffer(out ImageBuffer buffer)パラメータ
| 型 | 名前 | 説明 |
|---|---|---|
| ImageBuffer | buffer | 成功時にイメージバッファの参照を受け取る出力パラメータ |
戻り値
| 型 | 説明 |
|---|---|
| bool | 画像データが格納されたイメージバッファを取得できた場合は true、それ以外は false |
備考
この操作は、シンクがデータストリーム内でデバイスに接続されている間のみ有効です。
バッファはビデオキャプチャデバイスから受信した順に取得され、最も古い画像が最初に返されます。
正常に呼び出された後、プログラムは ImageBuffer 参照を通じてイメージバッファの所有権を持ちます。後で再利用するためにシンクのフリーキューへ戻すには、イメージバッファオブジェクトを Dispose する必要があります。
イベント
FramesQueued
画像データが格納されたバッファがシンクのキューに新たに追加されたときに発生します。
宣言
public event EventHandler<QueueSinkEventArgs> FramesQueuedイベントの型
| 型 | 説明 |
|---|---|
| EventHandler<QueueSinkEventArgs> |
備考
イベントハンドラでは通常、PopOutputBuffer() を呼び出して、画像データが格納されたイメージバッファにアクセスします。
このコールバック関数で時間のかかる処理を行う場合は、データストリームが停止中かどうかを判断するため、IsCancelRequested を定期的に確認することを推奨します。
この関数は、シンクによって管理される専用スレッド上で実行されます。
シンクへのデータストリームが停止される際、StreamStop() の呼び出しは、このイベントハンドラが戻るまで待機します。イベントハンドラ内のコードが、StreamStop() を呼び出したスレッドでの処理を無条件に必要とする操作を実行すると、容易にデッドロックが発生する可能性があります。
SinkConnected
シンクへのデータストリームが作成されたときに発生します。
宣言
public event EventHandler<QueueSinkConnectedEventArgs> SinkConnectedイベントの型
| 型 | 説明 |
|---|---|
| EventHandler<QueueSinkConnectedEventArgs> |
備考
イベントハンドラでは、AbortConnect を true に設定することで、データストリームの作成を中止できます。
MinBuffersRequired は、データストリームを動作させるために必要な最小バッファ数を示します。イベントハンドラでバッファが確保されなかった場合、シンクは必要な最小数のバッファを自動的に割り当てます。
この関数は、StreamSetup(Sink, StreamSetupOption) を呼び出したスレッド上で実行されます。
SinkDisconnected
シンクへのデータストリームが停止されたときに発生します。
宣言
public event EventHandler<QueueSinkEventArgs> SinkDisconnected
