FrameSnapSink.SnapSingle Method

１枚のイメージの到着を待ち、結果を返します。

構文

[C#]
public IFrameQueueBuffer SnapSingle( TimeSpan timeout );
public IFrameQueueBuffer SnapSingle( IFrameQueueBuffer bufferToSnapInto, TimeSpan timeout );

timeout : 新しいイメージが到着するのを待つ時間を指定します。この時間経過後、ICExceptionクラスライブラリリファレンス＞クラス＞ICExceptionが発生します。
bufferToSnapInto:到着したデータをコピーするターゲットバッファ。 このバッファはSinkと同じ FrameTypeクラスライブラリリファレンス＞クラス＞FrameTypeである必要があります。そうでない場合、ICExceptionクラスライブラリリファレンス＞クラス＞ICExceptionが発生します。

戻り値

成功すると、入ってきたばかりのフレームデータが入ったIFrameQueueBufferクラスライブラリリファレンス＞クラス＞IFrameQueueBufferが返されます。
IFrameQueueBufferクラスライブラリリファレンス＞クラス＞IFrameQueueBufferが引き渡されていない場合も、SinkはFrameQueueBufferクラスライブラリリファレンス＞クラス＞FrameQueueBufferを作成します。

情報

ICImagingControl3.5より実装

どういう時にエラーやデバイスロストイベントが発生するか

カメラ・ケーブル・NICカード・PCの故障や処理負荷などの様々な要因でソフトウェアはエラーやデバイスロストイベントを発生させることがあります。
ICImagingControlではこのような通信トラブルをユーザーレベルで認識できるようにするために、エラーやデバイスロストのイベントハンドラーを用意しています。例えば、画像を１枚取得するためのAPI：SnapSingleで設定したタイムアウト時間までに画像が取得できない場合には例外エラーを出力します。また、PCとカメラが接続通信ができなくなるタイミングでDeviceLostのイベントハンドラーが発生します。下記ではカメラ・ケーブル・NICカード・PCとったハードウェアに起因する通信トラブルの際に、どのような場面でソフトウェア側はDevice Lostのイベントハンドラー（DeviceLost Event）やSnapSingleメソッドの例外エラー（ICExceptionエラー）を発生させる可能性があるのかをまとめています。

原因・事象 DeviceLost Eventが発生するか FrameHandlerSink.SnapSingle Methodで
ICExceptionエラーが起きるのか
カメラ カメラのハングアップした場合
〇

熱暴走によってデバイスが切断された状態になりPCとの接続が切れる。
〇

設定したタイムアウト時間までにPCのバッファにフレームが入ってこない。
故障した場合
〇

通信が途切れる、あるいは電源が入っていないためデバイスが無効になる。
〇

カメラがフレームを出力し続けずに、タイムアウトになる。
ケーブル ノイズが多い場合
〇

PCとカメラの接続の有効性を確認するハートビートのパケットが制限時間内にPCまで届かず、PCがデバイスリリースし、その結果カメラの通信接続が切れる。
〇

通信品質が悪く、フレームを構成するパケットがPCで受信する前に壊れてしまい、その結果、何度もカメラから再送され、1枚のフレームを構成するまで長い時間がかかり、その間にタイムアウトしてしまうことがある。
NIC PoEの給電能力が原因の場合
〇

NICの特定ポートの給電能力が低い場合、カメラへ十分に給電できないためデバイスが無効になる。
×

デバイスが無効な状態（DeviceLostした状態）で画像が送信されることはない。
NICに搭載されたLANコントローラーの
パケット処理性能が足りない場合
×

PCとカメラの接続の有効性を確認するハートビートは極小のパケットのやり取りなので、NIC側のパケット処理能力が足りないということはほぼあり得ない。
〇

フレームを構成するパケットをPC側でうまく受信できず、その間に送信されたパケットがPC側でロストするため、そのロスト分のパケットを再送命令を行い、その結果、フレームを構成する時間がかかり、タイムアウトになる。
PC CPU負荷が原因の場合
△

GigEカメラの画像取り込みはCPUを使うので、PC内での処理（画像処理、描画、録画）が重すぎると、接続有効性が保てずにデバイスが無効になることがたまにある。
〇

SigleSnapのメソッドの呼び出しから画像取込の間に処理時間の長いプログラムを入れていると、CPU性能が低い場合は時間が間に合わず、タイムアウトが起きる。

関連項目

FrameSnapSinkクラスライブラリリファレンス＞クラス＞FrameSnapSink, IFrameQueueBufferクラスライブラリリファレンス＞クラス＞IFrameQueueBuffer, ICExceptionクラスライブラリリファレンス＞クラス＞ICException