Queue Sink

Queue Sinkは、ビデオキャプチャデバイスから受信したすべての画像をプログラムで処理できるようにするSinkの実装です。 詳細...

Data Structures

struct  IC4_QUEUESINK_CALLBACKS

Queue Sinkの動作を指定するために使用される関数ポインタを格納します。 詳細...
struct  IC4_QUEUESINK_CONFIG

Queue Sinkの動作を構成します。 詳細...
struct  IC4_QUEUESINK_QUEUE_SIZES

Queue Sink内の現在のキューの長さに関する情報を格納します。 詳細...

関数

bool ic4_queuesink_create (struct IC4_SINK **ppSink, const struct IC4_QUEUESINK_CONFIG *config)

新しい Queue Sink を作成します。

bool ic4_queuesink_get_output_image_type (const struct IC4_SINK *pSink, struct IC4_IMAGE_TYPE *image_type)

Sinkが受信するように構成されている画像のイメージタイプを照会します。

bool ic4_queuesink_alloc_and_queue_buffers (struct IC4_SINK *pSink, size_t num_buffers)

Sinkのイメージタイプに一致するバッファをメモリ確保し、フリーキューに格納します。
bool ic4_queuesink_pop_output_buffer (struct IC4_SINK *pSink, struct IC4_IMAGE_BUFFER **ppImageBuffer)

Sinkの出力キューから、画像データが格納されたバッファを取得します。
bool ic4_queuesink_is_cancel_requested (const struct IC4_SINK *pSink, bool *cancel_requested)

このSinkが接続されているデータストリームが停止処理中かどうかを確認します。
bool ic4_queuesink_get_queue_sizes (const struct IC4_SINK *pSink, struct IC4_QUEUESINK_QUEUE_SIZES *sizes)

Queue Sinkのキュー内のImageBuffer数に関する情報を照会します。

詳細説明

Queue Sinkは、ビデオキャプチャデバイスから受信したすべての画像をプログラムで処理できるようにするSinkの実装です。

Queue Sinkは、2つのキューに編成された複数のバッファを管理します:

  • デバイスからのデータを格納するためにバッファが取り出されるフリーキュー
  • プログラムが取り出せるように、データが格納されたバッファを保持する出力キュー

Queue Sinkを作成するには、ic4_queuesink_create() を呼び出します。

通常、QueueSink は IC4_QUEUESINK_CALLBACKS に一連のコールバック関数を登録することで操作します。コールバック関数は、QueueSink のライフタイムにおけるさまざまな重要なタイミングで呼び出されます:

  • IC4_QUEUESINK_CALLBACKS::sink_connected は、デバイスからSinkへのデータストリームがセットアップされるときに呼び出されます。このコールバックは、ストリーミングを開始するのに十分なバッファがキューに入っていることを保証する役割を担います。
  • IC4_QUEUESINK_CALLBACKS::frames_queued は、出力キューに画像が利用可能になるたびに呼び出されます。
  • IC4_QUEUESINK_CALLBACKS::sink_disconnected は、以前に作成されたデータストリームが停止されたときに呼び出されます。
  • IC4_QUEUESINK_CALLBACKS::release は、Sinkオブジェクトが破棄されるときに呼び出されます。Sinkや他のコールバック関数が依存しているリソースを解放できます。

出力キューから最も古い利用可能な画像を取得するには、ic4_queuesink_pop_output_buffer() を呼び出します。返された IC4_IMAGE_BUFFER は呼び出し側が所有します。後で ic4_imagebuffer_unref() を呼び出して、バッファをSinkのフリーキューに戻す役割を担います。

プログラムは必ずしもすべてのImageBufferをすぐに再キューイングする必要はありません。一部のバッファへの参照を独自のデータ構造に保持することもできます。ただし、デバイスがフレームを配信しようとしたときにフリーキューにバッファがない場合、そのフレームはドロップされることに注意してください。バッファアンダーランが発生したかどうかを確認するには、ic4_grabber_get_stream_stats() を使用してください。

関数ドキュメント

◆ ic4_queuesink_alloc_and_queue_buffers()

bool ic4_queuesink_alloc_and_queue_buffers ( struct IC4_SINK *  pSink,
size_t  num_buffers 
)

Sinkのイメージタイプに一致するバッファをメモリ確保し、フリーキューに格納します。

パラメータ
[in]pSinkQueue Sinkです
[in]num_buffersメモリ確保するバッファの数です
戻り値
成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。
事前条件
この操作は、Sinkのイメージタイプがわかっている場合にのみ有効です。これは次の場合に該当します:

◆ ic4_queuesink_create()

bool ic4_queuesink_create ( struct IC4_SINK **  ppSink,
const struct IC4_QUEUESINK_CONFIG *  config 
)

新しい Queue Sink を作成します。

パラメータ
[in]ppSink新しいQueue Sinkを受け取るSinkハンドルへのポインタです。
[in]configSink構成を格納する構造体へのポインタです
戻り値
成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。

Sinkが受信する画像のイメージタイプは、ic4_grabber_stream_setup() の呼び出しでSinkへのデータストリームが作成されるときに、次の手順で決定されます:

  • If IC4_QUEUESINK_CONFIG::num_pixel_formats が 0 の場合、デバイスのフォーマットが選択されます。
  • デバイスの出力フォーマットが IC4_QUEUESINK_CONFIG::pixel_formats で渡されたピクセルフォーマットのいずれかに一致する場合、最初に一致したものが選択されます。
  • 直接一致するものがないが、デバイスの出力フォーマットと渡されたピクセルフォーマットのいずれかとの間に変換が存在する場合、変換が可能な最初のフォーマットが選択されます。
  • デバイスの出力フォーマットと IC4_QUEUESINK_CONFIG::pixel_formats の値のいずれかとの間に変換が存在しない場合、ストリームのセットアップは失敗します。

◆ ic4_queuesink_get_output_image_type()

bool ic4_queuesink_get_output_image_type ( const struct IC4_SINK *  pSink,
struct IC4_IMAGE_TYPE *  image_type 
)

Sinkが受信するように構成されている画像のイメージタイプを照会します。

パラメータ
[in]pSinkQueue Sinkです
[out]image_typeイメージタイプ情報を受け取る構造体です
戻り値
成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。
事前条件
この操作は、デバイスからSinkへのデータストリームが存在する場合にのみ有効です。

◆ ic4_queuesink_get_queue_sizes()

bool ic4_queuesink_get_queue_sizes ( const struct IC4_SINK *  pSink,
struct IC4_QUEUESINK_QUEUE_SIZES *  sizes 
)

Queue Sinkのキュー内のImageBuffer数に関する情報を照会します。

パラメータ
[in]pSinkQueue Sinkです
[out]sizesキューの長さを受け取る構造体へのポインタです
事前条件
この操作は、デバイスからSinkへのデータストリームが存在する場合にのみ有効です。
戻り値
成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。

◆ ic4_queuesink_is_cancel_requested()

bool ic4_queuesink_is_cancel_requested ( const struct IC4_SINK *  pSink,
bool *  cancel_requested 
)

このSinkが接続されているデータストリームが停止処理中かどうかを確認します。

この関数は、IC4_QUEUESINK_CALLBACKS::frames_queued コールバック内の長時間実行操作をキャンセルするために使用できます。

パラメータ
[in]pSinkQueue Sinkです
[out]cancel_requestedキャンセル要求を受け取るフラグへのポインタです
戻り値
成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。

◆ ic4_queuesink_pop_output_buffer()

bool ic4_queuesink_pop_output_buffer ( struct IC4_SINK *  pSink,
struct IC4_IMAGE_BUFFER **  ppImageBuffer 
)

Sinkの出力キューから、画像データが格納されたバッファを取得します。

パラメータ
[in]pSinkQueue Sinkです
[out]ppImageBuffer新しくデータが格納された画像を受け取るフレームハンドルへのポインタです
戻り値
バッファのデキューに成功した場合は true、それ以外の場合は false を返します。
エラー情報の取得には ic4_get_last_error() を使用してください。
事前条件
この操作は、Sinkがデータストリーム内でデバイスに接続されている場合にのみ有効です。
注意
バッファは、ビデオキャプチャデバイスから受信した順序で取得され、最も古い画像が最初に返されます。
呼び出しが成功すると、ppImageBuffer が指すハンドルがフレームオブジェクトを所有します。
後で再利用するためにImageBufferをSinkのフリーキューに戻すには、ic4_imagebuffer_unref() の呼び出しが必要です。