データ転送 & 外部同期 API

INFINICAM からの高速画像データ受信（1コマ転送・連続ストリーミング転送）、および GPIO 信号を使用した外部同期（SYNC IN / OUT・汎用入出力）を制御する API 仕様です。

エラーハンドリングについて

本 API の戻り値として返されるエラーコード（PUCRESULT）の詳細一覧や転送タイムアウト時の対策については エラーコード一覧 & ハンドリングガイド を参照してください。

---

1. シングルデータ取得

PUC_GetXferDataSize / PUC_GetMaxXferDataSize

PUCRESULT WINAPI PUC_GetXferDataSize(PUC_HANDLE hDevice, UINT32* pDataSize);
PUCRESULT WINAPI PUC_GetMaxXferDataSize(PUC_HANDLE hDevice, UINT32* pDataSize);

現在の撮影条件での1フレームあたりの転送データサイズ（圧縮データのバイト数）、および設定しうる最大サイズを取得します。受信用バッファの確保サイズを決定するために、キャプチャ前に呼び出します。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
pDataSize	UINT32*	[out] 転送データサイズ（バイト単位）の格納先
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

---

PUC_GetSingleXferData

PUCRESULT WINAPI PUC_GetSingleXferData(PUC_HANDLE hDevice, PPUC_XFER_DATA_INFO pXferData);

カメラから 1 フレーム分の圧縮画像データを同期的に取得します。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
pXferData	PPUC_XFER_DATA_INFO	[in/out] pData（事前に確保した受信バッファ）・nDataSize（バッファサイズ）を指定し、取得後は実データサイズ・シーケンス番号・破損フラグが格納される
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 転送中は PUC_ERROR_XFERRING

ノート

連続転送 (PUC_BeginXferData) が開始されている状態では実行できません。単体キャプチャを行いたい場合は、先に PUC_EndXferData でストリーミングを停止してから実行してください。

---

2. 連続データ転送 (ストリーミング)

PUC_BeginXferData / PUC_EndXferData / PUC_IsXferring

typedef void (*RECEIVE_CALLBACK)(PPUC_XFER_DATA_INFO pXferData, void* pArg);

PUCRESULT WINAPI PUC_BeginXferData(PUC_HANDLE hDevice, RECEIVE_CALLBACK callback, void* arg);
PUCRESULT WINAPI PUC_EndXferData(PUC_HANDLE hDevice);
PUCRESULT WINAPI PUC_IsXferring(PUC_HANDLE hDevice, BOOL* pIsXferring);

連続画像転送 (ストリーミング) の開始・停止、および転送中かどうかの確認を行います。1 フレーム分のデータ受信が完了するたびに callback が呼び出されます。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
callback	RECEIVE_CALLBACK	[in] 1フレーム受信完了時に呼び出されるコールバック関数
arg	void*	[in] コールバック関数へ引き渡す任意のユーザーパラメータ
pIsXferring	BOOL*	[out] 転送中かどうかの格納先
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

注意

コールバック関数の中から PUC_EndXferData / PUC_CloseDevice は呼び出せません（PUC_ERROR_XFERRING が返ります）。停止・クローズは必ずコールバックの外側のスレッドから行ってください。また PUC_BeginXferData 実行中に解像度やフレームレートなどの設定 API を呼び出すと PUC_ERROR_XFERRING エラーとなるため、撮影条件を変更する場合は必ず PUC_EndXferData で転送を停止させてください。

---

PUC_SetRingBufferCount / PUC_GetRingBufferCount

PUCRESULT WINAPI PUC_SetRingBufferCount(PUC_HANDLE hDevice, UINT32 nCount);
PUCRESULT WINAPI PUC_GetRingBufferCount(PUC_HANDLE hDevice, UINT32* pCount);

連続転送時に SDK 内部で確保するリングバッファの要素数を設定・取得します。数を増やすことで、アプリ側の処理が一時的に遅延してもコマ落ちしにくくなります。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
nCount / pCount	UINT32 / UINT32*	リングバッファ数 (PUC_MIN_RING_BUF_COUNT ～ PUC_MAX_RING_BUF_COUNT)
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 範囲外指定は PUC_ERROR_RING_BUF_COUNT

---

PUC_SetXferTimeOut / PUC_GetXferTimeOut

PUCRESULT WINAPI PUC_SetXferTimeOut(PUC_HANDLE hDevice, UINT32 nSingleXferTimeOut, UINT32 nContinuousXferTimeOut);
PUCRESULT WINAPI PUC_GetXferTimeOut(PUC_HANDLE hDevice, UINT32* pSingleXferTimeOut, UINT32* pContinuousXferTimeOut);

デバイスから応答がない場合のタイムアウト時間 (ミリ秒) を、シングル転送・連続転送それぞれ個別に設定・取得します。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
nSingleXferTimeOut / pSingleXferTimeOut	UINT32 / UINT32*	PUC_GetSingleXferData のタイムアウト (ms)
nContinuousXferTimeOut / pContinuousXferTimeOut	UINT32 / UINT32*	連続転送時のタイムアウト (ms)
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

ノート

自動調整は PUC_XFER_TIMEOUT_AUTO (0)、無制限は PUC_XFER_TIMEOUT_INFINITE (0xFFFFFFFF) を指定します。本設定が反映されるかは機種に依存するため、PUC_IsSupported(PUC_CAP_XFER_TIMEOUT) で確認できます。

---

PUC_ResetSequenceNo

PUCRESULT WINAPI PUC_ResetSequenceNo(PUC_HANDLE hDevice);

転送データのシーケンス番号カウンタをリセットします。

引数 / 戻り値	型	説明
hDevice	PUC_HANDLE	[in] デバイスハンドル
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

---

3. 外部同期信号制御 (SYNC IN / OUT)

PUC_SetSyncInMode / PUC_GetSyncInMode / PUC_GetExternalSyncStatus

PUCRESULT WINAPI PUC_SetSyncInMode(PUC_HANDLE hDevice, PUC_SYNC_MODE nMode, PUC_SIGNAL nSignal);
PUCRESULT WINAPI PUC_GetSyncInMode(PUC_HANDLE hDevice, PUC_SYNC_MODE* pMode, PUC_SIGNAL* pSignal);
PUCRESULT WINAPI PUC_GetExternalSyncStatus(PUC_HANDLE hDevice, UINT32* pStatus, UINT32* pFrequency);

カメラの同期信号入力モード（内部動作 / 外部信号同期 / PTPマスタークロック同期）と、SYNC IN 信号の極性を設定・取得します。PUC_GetExternalSyncStatus で実際の同期状態（同期無し/同期中/信号未入力/OverSync）と周波数を確認できます。

引数 / 戻り値	型	説明
nMode / pMode	PUC_SYNC_MODE / PUC_SYNC_MODE*	PUC_SYNC_INTERNAL / PUC_SYNC_EXTERNAL / PUC_SYNC_EXTERNAL_PTP（GbE-2専用）
nSignal / pSignal	PUC_SIGNAL / PUC_SIGNAL*	極性（PUC_SIGNAL_POSI / PUC_SIGNAL_NEGA）。外部同期設定時のみ取得可。バージョン1.01以前のデバイスでは極性指定非対応
pStatus	UINT32*	[out] 同期ステータス（0=同期無し、1=同期中、2=同期信号未入力、3=OverSync）
pFrequency	UINT32*	[out] 周波数 (Hz)
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

注意

外部機器同期設定時は、外部機器のばらつきを考慮した露光時間へ自動調整されます。あらかじめ撮影したい露光時間と撮影速度に変更してから、外部機器同期を設定してください。デバイスを再起動すると設定はリセットされます。

---

PUC_SetSyncOutSignal / PUC_GetSyncOutSignal

PUCRESULT WINAPI PUC_SetSyncOutSignal(PUC_HANDLE hDevice, PUC_SIGNAL nSignal);
PUCRESULT WINAPI PUC_GetSyncOutSignal(PUC_HANDLE hDevice, PUC_SIGNAL* pSignal);

同期信号出力 (SYNC OUT) の極性を設定・取得します。

引数 / 戻り値	型	説明
nSignal / pSignal	PUC_SIGNAL / PUC_SIGNAL*	極性（PUC_SIGNAL_POSI / PUC_SIGNAL_NEGA）
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

---

PUC_SetSyncOutDelay/Width/Magnification/Times

PUCRESULT WINAPI PUC_SetSyncOutDelay(PUC_HANDLE hDevice, UINT32 nDelay);
PUCRESULT WINAPI PUC_GetSyncOutDelay(PUC_HANDLE hDevice, UINT32* pDelay);

PUCRESULT WINAPI PUC_SetSyncOutWidth(PUC_HANDLE hDevice, UINT32 nWidth);
PUCRESULT WINAPI PUC_GetSyncOutWidth(PUC_HANDLE hDevice, UINT32* pWidth);

PUCRESULT WINAPI PUC_SetSyncOutMagnification(PUC_HANDLE hDevice, UINT32 nMagnification);
PUCRESULT WINAPI PUC_GetSyncOutMagnification(PUC_HANDLE hDevice, UINT32* pMagnification);

PUCRESULT WINAPI PUC_SetSyncOutTimes(PUC_HANDLE hDevice, PUC_SYNC_OUT_TIMES nTimes);
PUCRESULT WINAPI PUC_GetSyncOutTimes(PUC_HANDLE hDevice, PUC_SYNC_OUT_TIMES* pTimes);

SYNC OUT 信号の遅延量・出力幅（共に nsec 単位）・出力倍率（例：2 で x2倍、0.5倍は PUC_SYNC_OUT_MAGNIFICATION_0_5）・出力回数倍率（PUC_SYNC_OUT_TIMES）を設定・取得します。

引数 / 戻り値	型	説明
nDelay / pDelay、nWidth / pWidth	UINT32 / UINT32*	遅延量・出力幅 (nsec単位、100nsec未満は切り上げ)
nMagnification / pMagnification	UINT32 / UINT32*	出力倍率
nTimes / pTimes	PUC_SYNC_OUT_TIMES / PUC_SYNC_OUT_TIMES*	出力回数倍率
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

注意

撮影速度や露光・非露光期間、出力幅を変更すると、出力倍率 (PUC_SetSyncOutMagnification) は自動的に x1倍にリセットされます。いずれもデバイスのオープン時または再起動時に設定がリセットされます。

---

PUC_SetSyncInDelay / PUC_SetTrigInDelay / PUC_SetTrigOutWidth / PUC_SetExposeDelay / PUC_SetPPOutWidth / PUC_SetPPOutDelay

PUCRESULT WINAPI PUC_SetSyncInDelay(PUC_HANDLE hDevice, UINT32 nDelay);
PUCRESULT WINAPI PUC_GetSyncInDelay(PUC_HANDLE hDevice, UINT32* pDelay);

PUCRESULT WINAPI PUC_SetTrigInDelay(PUC_HANDLE hDevice, UINT32 nDelay);
PUCRESULT WINAPI PUC_GetTrigInDelay(PUC_HANDLE hDevice, UINT32* pDelay);

PUCRESULT WINAPI PUC_SetTrigOutWidth(PUC_HANDLE hDevice, UINT32 nWidth);
PUCRESULT WINAPI PUC_GetTrigOutWidth(PUC_HANDLE hDevice, UINT32* pWidth);

PUCRESULT WINAPI PUC_SetExposeDelay(PUC_HANDLE hDevice, UINT32 nDelay);
PUCRESULT WINAPI PUC_GetExposeDelay(PUC_HANDLE hDevice, UINT32* pDelay);

PUCRESULT WINAPI PUC_SetPPOutWidth(PUC_HANDLE hDevice, UINT32 nWidth);
PUCRESULT WINAPI PUC_GetPPOutWidth(PUC_HANDLE hDevice, UINT32* pWidth);

PUCRESULT WINAPI PUC_SetPPOutDelay(PUC_HANDLE hDevice, UINT32 nDelay);
PUCRESULT WINAPI PUC_GetPPOutDelay(PUC_HANDLE hDevice, UINT32* pDelay);

SYNC IN・トリガ入力・露光・PP (Pulse-Per-second) 出力それぞれの遅延量／出力幅（nsec単位）を設定・取得する、GPIO周りの詳細設定APIです。いずれも対応可否が機種に依存するため、使用前に PUC_IsSupported で確認してください（対応する PUC_CAPABILITY は 共通定数・列挙体 を参照）。

引数 / 戻り値	型	説明
nDelay / pDelay、nWidth / pWidth	UINT32 / UINT32*	遅延量・出力幅 (nsec単位)
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 非対応機種は PUC_ERROR_NOTSUPPORT

---

4. 汎用入出力 (GPIO)

PUC_GetSupportedGeneralOutSignal / PUC_SetGeneralOutSignal / PUC_GetGeneralOutSignal

PUCRESULT WINAPI PUC_GetSupportedGeneralOutSignal(PUC_HANDLE hDevice, PUC_GENERAL_OUT_SIGNAL_TYPE GenOutType, bool* isSupported);
PUCRESULT WINAPI PUC_SetGeneralOutSignal(PUC_HANDLE hDevice, int portNo, PUC_GENERAL_OUT_SIGNAL_TYPE type);
PUCRESULT WINAPI PUC_GetGeneralOutSignal(PUC_HANDLE hDevice, int portNo, PUC_GENERAL_OUT_SIGNAL_TYPE* type);

汎用出力ポートへ割り当てる信号種別（垂直同期・露光期間・記録中・トリガ検出など、一覧）を設定・取得します。

引数 / 戻り値	型	説明
GenOutType	PUC_GENERAL_OUT_SIGNAL_TYPE	[in] 対応確認したい信号種別
isSupported	bool*	[out] 対応可否
portNo	int	[in] 対象のポート番号
type / *type	PUC_GENERAL_OUT_SIGNAL_TYPE / PUC_GENERAL_OUT_SIGNAL_TYPE*	割り当てる信号種別
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

---

PUC_GetSupportedGeneralInSignal / PUC_SetGeneralInSignal / PUC_GetGeneralInSignal

PUCRESULT WINAPI PUC_GetSupportedGeneralInSignal(PUC_HANDLE hDevice, PUC_GENERAL_IN_SIGNAL_TYPE GenInType, bool* isSupported);
PUCRESULT WINAPI PUC_SetGeneralInSignal(PUC_HANDLE hDevice, int portNo, PUC_GENERAL_IN_SIGNAL_TYPE type);
PUCRESULT WINAPI PUC_GetGeneralInSignal(PUC_HANDLE hDevice, int portNo, PUC_GENERAL_IN_SIGNAL_TYPE* type);

汎用入力ポートに割り当てる信号種別（イベント入力・トリガ入力・外部同期入力・電源オフ入力など）を設定・取得します。使用可能な種別は機種によって異なるため、PUC_GetSupportedGeneralInSignal で事前確認してください。

引数 / 戻り値	型	説明
GenInType	PUC_GENERAL_IN_SIGNAL_TYPE	[in] 対応確認したい信号種別
isSupported	bool*	[out] 対応可否
portNo	int	[in] 対象のポート番号
type / *type	PUC_GENERAL_IN_SIGNAL_TYPE / PUC_GENERAL_IN_SIGNAL_TYPE*	割り当てる信号種別
戻り値	PUCRESULT	成功時は PUC_SUCCEEDED / 失敗時は エラーコード一覧

---

関連ページ

画像復号 (デコード) 処理 API受信用バッファから画像データを復号する CPU / GPU デコード API の解説