Class Grabber

開かれたビデオキャプチャデバイスを表し、デバイスの設定やストリームの構成を行うことができます。

継承

object
HandleObject
Grabber

実装

IDisposable

継承されたメンバ

Namespace: ic4
Assembly: ic4dotnet.dll

構文

public class Grabber : HandleObject, IDisposable

解説

Grabberオブジェクトは、ビデオキャプチャデバイスを操作する際の中核コンポーネントです。
Grabberオブジェクトは、コンストラクタ Grabber() を使って作成します。
作成後、grabberで最も一般的な操作はデバイスのオープンです。デバイスは以下の方法で直接オープンできます。

デバイスは、以前保存したデバイス状態から選択・設定することもできます。

オープンしたビデオキャプチャデバイスからデータストリームを確立するには、StreamSetup(Sink, IDisplay, StreamSetupOption) を呼び出します。

プログラムで画像データにアクセス、処理、または保存する場合、Sink が必要です。アプリケーションに応じて選択可能な複数のSinkタイプがあり、例として QueueSink や SnapSink があります。

IDisplay を使用すると、ビデオキャプチャデバイスからの全ての画像を自動的に表示できます。

データストリームの設定後、AcquisitionStart() を呼び出して画像転送を開始します。

grabberオブジェクトのライフサイクル中の内部状態については、Grabberの状態 を参照してください。

一部のオブジェクト参照、例えば ImageBuffer は、デバイスドライバのメモリを指しているため、存在する限りデバイスやドライバを開いたままにすることがあります。すべてのデバイス関連リソースを解放するには、すべてのオブジェクト参照を解放する必要があります。

コンストラクタ

Grabber()

新しいgrabberを作成します。

宣言

public Grabber()

例外

型 条件
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

Grabber(string)

新しいgrabberを作成し、指定した識別子に一致するビデオキャプチャデバイスを即座にオープンします。

宣言

public Grabber(string identifier)

パラメータ

型 名前 説明
string identifier 接続されたビデオキャプチャデバイスを即座に開くためのモデル名、ユニーク名、シリアル、ユーザーID、IPv4アドレス、またはMACアドレス
備考

指定した識別子に一致するデバイスが複数存在する場合、コンストラクタは失敗し、エラーコードが Ambiguous に設定された IC4Exception をスローします。
指定した識別子に一致するデバイスが存在しない場合、コンストラクタは失敗し、エラーコードが DeviceNotFound に設定された IC4Exception をスローします。

例外

型 条件
ArgumentNullException deviceInfo が null の場合
IC4Exception 詳細は ErrorCode と ToString() を確認してください。

Grabber(DeviceInfo)

新しいgrabberを作成し、渡された DeviceInfo オブジェクトで表されるビデオキャプチャデバイスを即座にオープンします。

宣言

public Grabber(DeviceInfo deviceInfo)

パラメータ

型 名前 説明
DeviceInfo deviceInfo 即座に開くビデオキャプチャデバイスを表すデバイス情報オブジェクト

例外

型 条件
ArgumentNullException deviceInfo が null の場合
IC4Exception 詳細は ErrorCode と ToString() を確認してください。

プロパティ

DeviceInfo

現在オープンされているビデオキャプチャデバイスに関する情報を返します。

宣言

public DeviceInfo DeviceInfo { get; }

プロパティ値

型 説明
DeviceInfo 現在オープンされているビデオキャプチャデバイスの DeviceInfo オブジェクト

例外

型 条件
InvalidOperationException デバイスは開かれていません
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

DevicePropertyMap

現在オープンされているビデオキャプチャデバイスのプロパティマップを返します。

宣言

public PropertyMap DevicePropertyMap { get; }

プロパティ値

型 説明
PropertyMap
備考

この関数から返されるプロパティマップは、すべてのデバイス機能操作の基点となります。

例外

型 条件
InvalidOperationException デバイスは開かれていません
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

Display

現在確立されているデータストリームの設定時に、StreamSetup(IDisplay, StreamSetupOption) または StreamSetup(Sink, IDisplay, StreamSetupOption) に渡された display オブジェクトを返します。

宣言

public IDisplay Display { get; }

プロパティ値

型 説明
IDisplay 現在の display。display が設定されていない場合は null です。

DriverPropertyMap

現在オープンされているビデオキャプチャデバイスのドライバー用プロパティマップを返します。

宣言

public PropertyMap DriverPropertyMap { get; }

プロパティ値

型 説明
PropertyMap
備考

この関数から返されるプロパティマップは、ドライバー関連の機能操作の基点となります。

例外

型 条件
InvalidOperationException デバイスは開かれていません
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

IsAcquisitionActive

このgrabberのビデオキャプチャデバイスで、画像取得が現在有効かどうかを確認します。

宣言

public bool IsAcquisitionActive { get; }

プロパティ値

型 説明
bool 画像取得が現在アクティブな場合は true、それ以外の場合は false です。
備考

IsStreaming と異なり、デバイスに画像取得の開始指示が出されているかも確認します。
grabberオブジェクトのライフサイクル中の内部状態については、Grabberの状態 を参照してください。

IsDeviceOpen

grabberが現在ビデオキャプチャデバイスをオープンしているかどうかを確認します。

宣言

public bool IsDeviceOpen { get; }

プロパティ値

型 説明
bool grabberがビデオキャプチャデバイスをオープンしている場合は true、それ以外の場合は false です。
備考

grabberオブジェクトのライフサイクル中の内部状態については、Grabberの状態 を参照してください。

IsDeviceValid

grabberで現在オープンされているビデオキャプチャデバイスが使用可能かどうかを確認します。

宣言

public bool IsDeviceValid { get; }

プロパティ値

型 説明
bool grabberが使用可能なビデオキャプチャデバイスをオープンしている場合は true、それ以外の場合は false です。
備考

この関数が false を返す理由はいくつかあります:

  • デバイスが開かれていない
  • デバイスが切断された
  • ハードウェア接続が緩んでいる
  • ビデオキャプチャデバイス内部でエラーが発生した
  • ドライバーエラーが発生した

現在オープンされているデバイスが無効になった場合、DeviceLost イベントが発生します。
grabberオブジェクトのライフサイクル中の内部状態については、Grabberの状態 を参照してください。

IsStreaming

このgrabberのビデオキャプチャデバイスからデータストリームが確立されているかどうかを確認します。

宣言

public bool IsStreaming { get; }

プロパティ値

型 説明
bool データストリームが以前に確立されている場合は true。それ以外、またはデータストリームが停止された場合は false です。
備考

grabberオブジェクトのライフサイクル中の内部状態については、Grabberの状態 を参照してください。

Sink

現在確立されているデータストリームの設定時に、StreamSetup(Sink, IDisplay, StreamSetupOption) または StreamSetup(Sink, StreamSetupOption) に渡された sink オブジェクトを返します。

宣言

public Sink Sink { get; }

プロパティ値

型 説明
Sink 現在の sink。sink が設定されていない場合は null です。

StreamStatistics

現在実行中または以前に停止したデータストリームの統計カウンターを取得します。

宣言

public StreamStatistics StreamStatistics { get; }

プロパティ値

型 説明
StreamStatistics StreamStatistics オブジェクト。ストリームの統計カウンターを含みます。
備考

この操作は、一度データストリームが確立された後でのみ有効です。

例外

型 条件
InvalidOperationException

データストリームがまだ設定されていない場合に発生します。
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

メソッド

AcquisitionStart()

ビデオキャプチャデバイスからの画像取得を開始します。

宣言

public void AcquisitionStart()
備考

この関数を呼び出す前に、StreamSetup(Sink, IDisplay, StreamSetupOption) またはそのオーバーロードのいずれかを使用して、データストリームを確立しておく必要があります。
この操作は、デバイスの PropertyMap 上で AcquisitionStart コマンドを実行するのと同等です。

例外

型 条件
InvalidOperationException データストリームがまだ設定されていない場合、またはすでに取得が開始されている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

AcquisitionStop()

ビデオキャプチャデバイスからの画像取得を停止します。

宣言

public void AcquisitionStop()
備考

この関数を呼び出す前に、画像取得を開始しておく必要があります。例えば、AcquisitionStart() を呼び出すか、ストリーム設定時に AcquisitionStart を指定します。
この操作は、デバイスの PropertyMap 上で AcquisitionStop コマンドを実行するのと同等です。

例外

型 条件
InvalidOperationException デバイスが開かれていない場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceClose()

この Grabber インスタンスで現在開かれているビデオキャプチャデバイスを閉じます。

宣言

public void DeviceClose()
備考

デバイスを閉じると、すべてのリソースが解放されます。

  • 画像取得がアクティブな場合は停止されます。
  • データストリームが設定されていた場合は停止されます。
  • データストリーム関連オブジェクトへの参照は解放され、Sink や Display が破棄される場合があります。
  • DevicePropertyMap から取得したプロパティオブジェクトは無効になります。

ImageBuffer オブジェクトとそのメモリは、破棄されるまで保持されます。ImageBuffer がドライバメモリを指している場合、その参照によってビデオキャプチャデバイスが開いたままになることがあります。

例外

型 条件
InvalidOperationException デバイスコールバックなど、操作を実行できないスレッドから関数が呼び出された場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceOpen(string)

指定した識別子に一致するビデオキャプチャデバイスを開きます。

宣言

public void DeviceOpen(string identifier)

パラメータ

型 名前 説明
string identifier 接続されているビデオキャプチャデバイスのモデル名、一意の名前、シリアル番号、ユーザーID、IPV4アドレス、またはMACアドレス
備考

指定された識別子に一致するデバイスが複数存在する場合、この関数は失敗し、エラーコードがAmbiguousに設定されたIC4Exceptionをスローします。
指定された識別子に一致するデバイスが存在しない場合、関数は失敗し、エラーコードが DeviceNotFoundに設定されたIC4Exceptionをスローします。

例外

型 条件
ArgumentNullException identifier が null の場合に発生します。
InvalidOperationException すでにデバイスが開かれている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceOpen(DeviceInfo)

渡されたデバイス情報オブジェクトで指定されたビデオキャプチャデバイスを開きます。

宣言

public void DeviceOpen(DeviceInfo deviceInfo)

パラメータ

型 名前 説明
DeviceInfo deviceInfo 開くビデオキャプチャデバイスを表すデバイス情報オブジェクト

例外

型 条件
ArgumentNullException deviceInfo が null の場合に発生します。
InvalidOperationException すでにデバイスが開かれている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceOpenFromState(byte[])

以前に DeviceSaveState() で書き出されたデータを含むメモリバッファから、開いていたデバイスとその設定を復元します。

宣言

public void DeviceOpenFromState(byte[] deviceState)

パラメータ

型 名前 説明
byte[] deviceState DeviceSaveState() で書き出されたデータを含むバッファ
備考

メモリバッファに書き込みできなかったプロパティの設定が含まれている場合、この関数は失敗し、IC4Exception が発生し、エラーコードは Incomplete に設定されます。

例外

型 条件
ArgumentNullException deviceState が null の場合に発生します。
InvalidOperationException すでにデバイスが開かれている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceOpenFromState(Stream)

Stream に含まれるデバイス状態データから、開いていたデバイスとその設定を復元します。

宣言

public void DeviceOpenFromState(Stream strm)

パラメータ

型 名前 説明
Stream strm デバイス状態データを含む Stream

例外

型 条件
ArgumentNullException strm が null の場合に発生します。
InvalidOperationException すでにデバイスが開かれている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceOpenFromState(string)

以前に DeviceSaveState(string) で書き出されたファイルから、開いていたデバイスとその設定を復元します。

宣言

public void DeviceOpenFromState(string fileName)

パラメータ

型 名前 説明
string fileName デバイス状態情報を含むファイルのパス

例外

型 条件
ArgumentNullException fileName が null の場合に発生します。
InvalidOperationException すでにデバイスが開かれている場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceSaveState()

現在開かれているビデオキャプチャデバイスとそのすべての設定をメモリバッファに保存します。

宣言

public byte[] DeviceSaveState()

戻り値

型 説明
byte[] デバイス状態データを含むバイト配列
備考

後でデバイス状態を復元するには、DeviceOpenFromState(byte[]) を使用します。
この関数は、デバイスのプロパティをシリアライズする（Serialize() のように）だけでなく、現在開かれているビデオキャプチャデバイス自体も保存するため、後でデバイスをすべての設定とともに再度開くことが可能です。

例外

型 条件
InvalidOperationException デバイスが開かれていない場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

DeviceSaveState(string)

現在開かれているビデオキャプチャデバイスとそのすべての設定をファイルに保存します。

宣言

public void DeviceSaveState(string fileName)

パラメータ

型 名前 説明
string fileName デバイス状態が書き込まれるファイルのパス
備考

後でデバイス状態を復元するには、DeviceOpenFromState(string) を使用します。
この関数は、デバイスのプロパティをシリアライズする（Serialize(string) のように）だけでなく、現在開かれているビデオキャプチャデバイス自体も保存するため、後でデバイスをすべての設定とともに再度開くことが可能です。

例外

型 条件
ArgumentNullException fileName が null の場合に発生します。
InvalidOperationException デバイスが開かれていない場合に発生します。
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

StreamSetup(IDisplay, StreamSetupOption)

デバイスからデータストリームを確立します。

宣言

public void StreamSetup(IDisplay display, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

パラメータ

型 名前 説明
IDisplay display 画像を表示するためのディスプレイ
StreamSetupOption setupOption データストリームの設定が成功した後、取得をすぐに開始するかどうかを指定します
備考

この関数を呼び出す前にデバイスを開く必要があります。
Grabberは渡されたディスプレイへの参照を保持し、データストリームが停止されるまでその寿命をGrabberに結びつけます。
後でデータストリームを停止するには、StreamStop() を呼び出してください。

例外

型 条件
ArgumentNullException display が null の場合に発生します。
InvalidOperationException 操作が実行できない場合に発生します。主な理由は以下の通りです：
  • デバイスが開かれていない
  • データストリームがすでにアクティブ
  • 関数が操作を実行できないスレッドから呼び出された（例：シンクのコールバック）
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

StreamSetup(Sink, IDisplay, StreamSetupOption)

デバイスからデータストリームを確立します。

宣言

public void StreamSetup(Sink sink, IDisplay display, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

パラメータ

型 名前 説明
Sink sink 画像を受信するシンク
IDisplay display 画像を表示するディスプレイ
StreamSetupOption setupOption データストリームの設定が成功した後、取得をすぐに開始するかどうかを指定します
備考

この関数を呼び出す前にデバイスを開く必要があります。
Grabberは渡されたシンクおよびディスプレイへの参照を保持し、データストリームが停止されるまでその寿命をGrabberに結びつけます。
後でデータストリームを停止するには、StreamStop() を呼び出してください。

例外

型 条件
ArgumentNullException sink または display が null の場合に発生します。
InvalidOperationException 操作が実行できない場合に発生します。主な理由は以下の通りです。
  • デバイスが開かれていない
  • データストリームがすでにアクティブ
  • 関数が操作を実行できないスレッドから呼び出された（例：シンクのコールバック）
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

StreamSetup(Sink, StreamSetupOption)

デバイスからデータストリームを確立します。

宣言

public void StreamSetup(Sink sink, StreamSetupOption setupOption = StreamSetupOption.AcquisitionStart)

パラメータ

型 名前 説明
Sink sink 画像を受信するシンク
StreamSetupOption setupOption データストリーム設定後に取得をすぐ開始するかどうかを指定します
備考

この関数を呼び出す前にデバイスを開く必要があります。
Grabberは渡されたシンクへの参照を保持し、データストリームが停止されるまでその寿命をGrabberに結びつけます。
後でデータストリームを停止するには、StreamStop() を呼び出してください。

例外

型 条件
ArgumentNullException sink が null の場合に発生します。
InvalidOperationException 操作が実行できない場合に発生します。主な理由は以下の通りです：
  • デバイスが開かれていない
  • データストリームがすでにアクティブ
  • 関数が操作を実行できないスレッドから呼び出された（例：シンクのコールバック）
IC4Exception 詳細は ErrorCode および ToString() を参照してください。

StreamStop()

StreamSetup(Sink, IDisplay, StreamSetupOption) またはそのオーバーロードで設定されたデータストリームを停止します。

宣言

public void StreamStop()
備考

この関数は、データストリーム設定時に使用されたシンクおよびディスプレイへの参照を解放します。 シンクやディスプレイへの追加参照がなければ、シンクまたはディスプレイは破棄されます。

例外

型 条件
InvalidOperationException 操作を実行できないスレッド（例：シンクのコールバック）から呼び出された場合に発生します。
IC4Exception 詳細については ErrorCode および ToString() を確認してください。

イベント

DeviceLost

現在開かれているビデオキャプチャデバイスが無効になったときに発生します。

宣言

public event EventHandler DeviceLost

イベントの型

型 説明
EventHandler
備考

このイベントが発生する理由はいくつかあります。

  • デバイスが切断された
  • ハードウェア接続が緩んでいる
  • ビデオキャプチャデバイス内部でエラーが発生した
  • ドライバーでエラーが発生した

実装

IDisposable