Snap Sink（SnapSink）
Snap Sinkは、すべての画像を表示するDisplayを維持しながら、必要に応じて1枚の画像または連続した画像を取得できるようにするSinkの実装です。 詳細...
データ構造
| struct | IC4_SNAPSINK_CONFIG Snap Sinkの動作を設定します。 詳細... |
列挙型
| enum | IC4_SNAPSINK_ALLOCATION_STRATEGY { IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT = 0
, IC4_SNAPSINK_ALLOCATION_STRATEGY_CUSTOM
} バッファ確保ストラテジーは、事前に確保されるバッファの数、追加のバッファが作成されるタイミング、余分なバッファが回収されるタイミングを定義します。 詳細... |
関数
| bool | ic4_snapsink_create (struct IC4_SINK **ppSink, const struct IC4_SNAPSINK_CONFIG *config) 新しい Snap Sink を作成します。 |
| bool | ic4_snapsink_get_output_image_type (const struct IC4_SINK *pSink, struct IC4_IMAGE_TYPE *image_type) Sinkが受信するよう設定されている画像の画像タイプを問い合わせます。 |
| bool | ic4_snapsink_snap_single (const struct IC4_SINK *pSink, struct IC4_IMAGE_BUFFER **ppImageBuffer, int64_t timeout_ms) ビデオキャプチャデバイスから受信したビデオストリームから1枚の画像を取得します。 |
| size_t | ic4_snapsink_snap_sequence (const struct IC4_SINK *pSink, struct IC4_IMAGE_BUFFER **pImageBufferList, size_t count, int64_t timeout_ms) ビデオキャプチャデバイスから受信したビデオストリームから連続した画像を取得します。 |
詳細説明
Snap Sinkは、すべての画像を表示するDisplayを維持しながら、必要に応じて1枚の画像または連続した画像を取得できるようにするSinkの実装です。
Snap Sinkを作成するには、ic4_snapsink_create() を呼び出します。
ストリームから1枚の画像を取得するには、ic4_snapsink_snap_single() を呼び出します。連続した画像を取得するには、ic4_snapsink_snap_sequence() を呼び出します。
Snap Sinkは、バックグラウンドでの画像取得に使用するバッファと、取得した画像用のバッファを管理します。ストリームのセットアップ時に、設定された確保ストラテジーに応じて一定数のバッファが確保されます。確保ストラテジーが許可していれば、必要に応じて追加のバッファが自動的に作成されます。同様に、未使用のImageBufferが余剰となった場合は、未使用のバッファが自動的に回収・解放されます。
snap 系関数のいずれかによって返されたImageBufferは、それぞれの呼び出し元が所有し、ic4_imagebuffer_unref() が呼び出されるまでその所有権を保持します。ImageBufferオブジェクトが解放されると、再利用のために自動的にSnap Sinkへ返却されます。
デバイスがフレームを引き渡そうとしたときにSinkに利用可能なバッファがない場合、そのフレームは破棄されますのでご注意ください。バッファアンダーランが発生したかどうかを確認するには、ic4_grabber_get_stream_stats() を使用します。
デフォルトでは、Sinkはデバイスドライバまたは暗黙的に作成された変換フィルタが提供するバッファを使用します。IC4_SNAPSINK_CONFIG::allocator にアロケータコールバック関数を設定することで、プログラム定義のバッファを使用することもできます。
列挙型ドキュメント
◆ IC4_SNAPSINK_ALLOCATION_STRATEGY
バッファ確保ストラテジーは、事前に確保されるバッファの数、追加のバッファが作成されるタイミング、余分なバッファが回収されるタイミングを定義します。
| 列挙子 | |
|---|---|
| IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT | デフォルトのストラテジーを使用します。 このストラテジーは、データストリームの要件と画像サイズに応じて自動的に選択された数のバッファを事前に確保します。 IC4_SNAPSINK_CONFIG 設定内のカスタムストラテジーパラメータは無視されます。 |
| IC4_SNAPSINK_ALLOCATION_STRATEGY_CUSTOM | カスタム確保ストラテジーです。 IC4_SNAPSINK_CONFIG::num_buffers_alloc_on_connect、IC4_SNAPSINK_CONFIG::num_buffers_allocation_threshold、IC4_SNAPSINK_CONFIG::num_buffers_free_threshold、IC4_SNAPSINK_CONFIG::num_buffers_max の各パラメータが、Sinkの確保動作を決定します。 |
関数ドキュメント
◆ ic4_snapsink_create()
| bool ic4_snapsink_create | ( | struct IC4_SINK ** | ppSink, |
| const struct IC4_SNAPSINK_CONFIG * | config | ||
| ) |
新しい Snap Sink を作成します。
- パラメータ
-
[in] ppSink 新しいSnap Sinkを受け取るSinkハンドルへのポインタ。 [in] config Sinkの構成を格納した構造体へのポインタ。
このパラメータは省略可能です。NULLを渡すとデフォルトの構成が使用されます。
- 戻り値
- 成功した場合は
true、それ以外の場合はfalse。
エラー情報を問い合わせるには ic4_get_last_error() を使用します。
Sinkが受信する画像の画像タイプは、ic4_grabber_stream_setup() の呼び出しによってSinkへのデータストリームが作成される際に、次の手順で決定されます。
- IC4_SNAPSINK_CONFIG::num_pixel_formats が
0の場合は、デバイスのフォーマットが選択されます。 - デバイスの出力フォーマットが IC4_SNAPSINK_CONFIG::pixel_formats に渡されたピクセルフォーマットのいずれかと一致する場合は、最初に一致したものが選択されます。
- 直接の一致がない場合でも、デバイスの出力フォーマットと渡されたピクセルフォーマットのいずれかとの間に変換が存在する場合は、変換が存在する最初のフォーマットが選択されます。
- デバイスの出力フォーマットと IC4_SNAPSINK_CONFIG::pixel_formats 内のいずれの値との間にも変換が存在しない場合は、ストリームのセットアップは失敗します。
◆ ic4_snapsink_get_output_image_type()
| bool ic4_snapsink_get_output_image_type | ( | const struct IC4_SINK * | pSink, |
| struct IC4_IMAGE_TYPE * | image_type | ||
| ) |
Sinkが受信するよう設定されている画像の画像タイプを問い合わせます。
- パラメータ
-
[in] pSink QueueSink [out] image_type 画像タイプ情報を受け取る構造体
- 戻り値
- 成功した場合は
true、それ以外の場合はfalse。
エラー情報を問い合わせるには ic4_get_last_error() を使用します。
- 事前条件
- この操作は、デバイスからSinkへのデータストリームが存在する間のみ有効です。
◆ ic4_snapsink_snap_sequence()
| size_t ic4_snapsink_snap_sequence | ( | const struct IC4_SINK * | pSink, |
| struct IC4_IMAGE_BUFFER ** | pImageBufferList, | ||
| size_t | count, | ||
| int64_t | timeout_ms | ||
| ) |
ビデオキャプチャデバイスから受信したビデオストリームから連続した画像を取得します。
この関数は、count 枚の画像が取得されるか、timeout_ms ミリ秒が経過するまで待機します。タイムアウトが発生した場合、関数は取得した画像の枚数を返し、エラー値は IC4_ERROR_TIMEOUT に設定されます。
- パラメータ
-
[in] pSink Snap Sink [out] pImageBufferList 新しく取り込まれた画像を受け取るフレームハンドルの配列へのポインタ [in] count 取得する画像の枚数 [in] timeout_ms すべての画像が到着するのを待機する時間
- 戻り値
- 正常に取得できた画像の枚数。
エラーが発生した場合、関数は0を返します。エラー情報を問い合わせるには ic4_get_last_error() を使用します。
- 事前条件
- この操作は、Sinkがデータストリーム内でデバイスに接続されている間のみ有効です。
- 注意
- 呼び出しが成功すると、
pImageBufferListが指すハンドルがフレームオブジェクトを所有します。
各ImageBufferを再利用のためにSinkへ返却するには、ic4_imagebuffer_unref() を呼び出す必要があります。
◆ ic4_snapsink_snap_single()
| bool ic4_snapsink_snap_single | ( | const struct IC4_SINK * | pSink, |
| struct IC4_IMAGE_BUFFER ** | ppImageBuffer, | ||
| int64_t | timeout_ms | ||
| ) |
ビデオキャプチャデバイスから受信したビデオストリームから1枚の画像を取得します。
この関数は、ビデオキャプチャデバイスから次のバッファを受信するか、timeout_ms ミリ秒が経過するまで待機します。タイムアウトが発生した場合、関数は失敗し、エラー値は IC4_ERROR_TIMEOUT に設定されます。
- パラメータ
-
[in] pSink Snap Sink [out] ppImageBuffer 新しく取り込まれた画像を受け取るフレームハンドルへのポインタ [in] timeout_ms 新しい画像が到着するのを待機する時間
- 戻り値
- 成功した場合は
true、それ以外の場合はfalse。
エラー情報を問い合わせるには ic4_get_last_error() を使用します。
- 事前条件
- この操作は、Sinkがデータストリーム内でデバイスに接続されている間のみ有効です。
- 注意
- 呼び出しが成功すると、
ppImageBufferが指すハンドルがフレームオブジェクトを所有します。
ImageBufferを再利用のためにSinkへ返却するには、ic4_imagebuffer_unref() を呼び出す必要があります。
