デバイス接続 & 撮影設定 API

INFINICAM デバイスの接続管理および本体パラメーターを制御する API 仕様です。

1. 初期化 & 接続管理

PUC_Initialize

PUCRESULT WINAPI PUC_Initialize();

SDK ライブラリを初期化します。アプリケーション起動時に 1 度だけ実行してください。

引数 / 戻り値	型	説明
引数	なし	-
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_DetectDevice2 / PUC_OpenDevice2

PUCRESULT WINAPI PUC_DetectDevice2(const PPUC_DETECT_FILTER pFilter, PPUC_DETECT_INFO pDetectInfo);
PUCRESULT WINAPI PUC_OpenDevice2(UINT32 index, PPUC_HANDLE pDeviceHandle);

UC-1.1（USB接続）・GbE-2（Ethernet接続）のいずれにも対応したデバイス検索・オープン関数です。本ドキュメントサイトの C++ / Python サンプルは全てこの組み合わせを使用しています。

引数 / 戻り値	型	説明
`pFilter`	`PPUC_DETECT_FILTER`	`[in]` 検索対象フラグ（`PUC_DETECT_TARGET_UC1` / `PUC_DETECT_TARGET_GBE2` / `PUC_DETECT_TARGET_ALL`）等を指定する構造体。詳細は共通定数・列挙体を参照
`pDetectInfo`	`PPUC_DETECT_INFO`	`[out]` 検出されたデバイス情報（台数・機種・IPアドレス等）の格納先
`index`	`UINT32`	`[in]` `pDetectInfo->nDeviceNoList` のインデックス（検索結果の何台目を開くか）
`pDeviceHandle`	`PPUC_HANDLE`	`[out]` オープンしたデバイスハンドルの格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_CloseDevice

PUCRESULT WINAPI PUC_CloseDevice(PUC_HANDLE hDevice);

指定したデバイスをクローズします。PUC_BeginXferData のコールバック関数内からは呼び出せません（PUC_ERROR_XFERRING が返ります）。

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

PUC_ResetDevice

PUCRESULT WINAPI PUC_ResetDevice(UINT32 nDeviceNo);

デバイスをハードウェアリセットします。PUC_OpenDevice2 に失敗した場合のリカバリーとして使用します。

引数 / 戻り値	型	説明
`nDeviceNo`	`UINT32`	`[in]` リセットするデバイス番号
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_IsSupported

PUCRESULT WINAPI PUC_IsSupported(PUC_HANDLE hDevice, PUC_CAPABILITY cap, bool* pIsSupported);

接続中のカメラが指定した機能に対応しているかを確認します。機種依存のAPIは非対応カメラで PUC_ERROR_NOTSUPPORT を返すため、UC-1.1 / GbE-2 の機種名で分岐する代わりに本関数で事前確認することが推奨されています。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`cap`	`PUC_CAPABILITY`	`[in]` 確認する機能（機能種別一覧）
`pIsSupported`	`bool*`	`[out]` 結果の格納先（`true` = 対応）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

2. デバイス情報取得

PUC_GetColorType

PUCRESULT WINAPI PUC_GetColorType(PUC_HANDLE hDevice, PUC_COLOR_TYPE* pType);

カメラのカラー / モノクロ仕様を取得します。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`pType`	`PUC_COLOR_TYPE*`	`[out]` カラー種別 (`PUC_COLOR_MONO` / `PUC_COLOR_COLOR`)
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_GetDeviceName / PUC_GetDeviceType / PUC_GetDeviceVersion / PUC_GetSerialNo

PUCRESULT WINAPI PUC_GetDeviceName(PUC_HANDLE hDevice, UINT32* pName);
PUCRESULT WINAPI PUC_GetDeviceType(PUC_HANDLE hDevice, UINT32* pType);
PUCRESULT WINAPI PUC_GetDeviceVersion(PUC_HANDLE hDevice, UINT32* pVersion);
PUCRESULT WINAPI PUC_GetSerialNo(PUC_HANDLE hDevice, UINT64* pSerialNo);

デバイスの名前・タイプ・バージョン・シリアル番号を取得します。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`pName` / `pType` / `pVersion`	`UINT32*`	`[out]` それぞれの情報の格納先
`pSerialNo`	`UINT64*`	`[out]` シリアル番号の格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_GetSensorTemperature

PUCRESULT WINAPI PUC_GetSensorTemperature(PUC_HANDLE hDevice, UINT32* pTemp);

デバイスのセンサー温度を取得します。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`pTemp`	`UINT32*`	`[out]` センサー温度の格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_GetIPAddress / PUC_GetMacAddress (GbE-2)

PUCRESULT WINAPI PUC_GetIPAddress(PUC_HANDLE hDevice, UINT32* pIPAddress);
PUCRESULT WINAPI PUC_GetMacAddress(PUC_HANDLE hDevice, UINT8* pMacAddress);

オープン中の GbE-2 デバイスの IP アドレス・MAC アドレスを取得します。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`pIPAddress`	`UINT32*`	`[out]` IPアドレスの格納先
`pMacAddress`	`UINT8*`	`[out]` MACアドレス（`PUC_MAC_ADDRESS_SIZE` = 6バイト）の格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_GetAdaptersInfoList / PUC_DiscoveryDevice (GbE-2)

PUCRESULT WINAPI PUC_GetAdaptersInfoList(UINT32* pNumAdapters, PPUC_NETWORK_INFO pAdaptersInfo);
PUCRESULT WINAPI PUC_DiscoveryDevice(UINT32 nAdapterIPaddress, UINT32* pNumDetectedDevice, PPUC_NETWORK_INFO pDetectedDevicesInfo);

PC側のネットワークアダプタ一覧、および指定アダプタからブロードキャスト探索で見つかる GbE-2 デバイスの詳細情報（IP・サブネット・ゲートウェイ・MACアドレス等）を取得します。オープン前のデバイスのネットワーク設定を確認したい場合に使用します。

引数 / 戻り値	型	説明
`pNumAdapters` / `pNumDetectedDevice`	`UINT32*`	`[out]` 取得できた件数の格納先
`pAdaptersInfo` / `pDetectedDevicesInfo`	`PPUC_NETWORK_INFO`	`[out]` 詳細情報の格納先（配列）
`nAdapterIPaddress`	`UINT32`	`[in]` 探索に使用するアダプタのIPアドレス
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時は `PUC_ERROR_GET_ADAPTER_INFO` / `PUC_ERROR_DETECT_DEVICE`

PUC_ForceSetNetworkSetting / PUC_SetNetworkInfo (GbE-2)

PUCRESULT WINAPI PUC_ForceSetNetworkSetting(UINT32 nAdapterIPaddress, const PPUC_NETWORK_INFO pTargetInfo, UINT32 nForTemporary, PPUC_NETWORK_INFO pResultInfo);
PUCRESULT WINAPI PUC_SetNetworkInfo(PUC_HANDLE hDevice, PUC_NETWORK_INFO_TYPE type, UINT32 value);

GbE-2 デバイスのネットワーク設定（IPアドレス・サブネットマスク・ゲートウェイ・DHCP の有効/無効）を変更します。PUC_ForceSetNetworkSetting はオープン前のデバイスに対しIP未設定などの状態から強制的に設定する場合に、PUC_SetNetworkInfo はオープン済みデバイスの設定変更に使用します。

引数 / 戻り値	型	説明
`type`	`PUC_NETWORK_INFO_TYPE`	`[in]` 変更する設定の種別（一覧）
`value`	`UINT32`	`[in]` 設定値
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時は `PUC_ERROR_SET_NETWORK_SETTING`

PUC_SetEPOCTime / PUC_SetTimeOfDay

PUCRESULT WINAPI PUC_SetEPOCTime(PUC_HANDLE hDevice, UINT32 year, UINT32 month, UINT32 day, UINT32 hour, UINT32 minute, UINT32 second);
PUCRESULT WINAPI PUC_SetTimeOfDay(PUC_HANDLE hDevice, UINT64 epochSeconds);

カメラ内蔵時計を設定します（年月日時分秒指定、またはエポック秒指定）。転送データのタイムコード（PUC_GetTimeCode2EPOC で変換）はこの時計を基準に記録されます。

引数 / 戻り値	型	説明
`year`〜`second`	`UINT32`	`[in]` 設定する日時
`epochSeconds`	`UINT64`	`[in]` 設定するエポック秒
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

3. 解像度 & 撮影条件設定

PUC_SetResolution / PUC_GetResolution

PUCRESULT WINAPI PUC_SetResolution(PUC_HANDLE hDevice, UINT32 nWidth, UINT32 nHeight);
PUCRESULT WINAPI PUC_GetResolution(PUC_HANDLE hDevice, UINT32* pWidth, UINT32* pHeight);

撮影解像度（幅・高さ）を設定・取得します。デバイスのオープン時に設定はリセットされます。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`nWidth` / `pWidth`	`UINT32` / `UINT32*`	横解像度（ピクセル単位）
`nHeight` / `pHeight`	`UINT32` / `UINT32*`	縦解像度（ピクセル単位）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 不正な値は `PUC_ERROR_ILLEGAL_RESOLUTION`

PUC_GetMaxResolution / PUC_GetResolutionLimit

PUCRESULT WINAPI PUC_GetMaxResolution(PUC_HANDLE hDevice, UINT32* pCurMaxWidth, UINT32* pCurMaxHeight);
PUCRESULT WINAPI PUC_GetResolutionLimit(PUC_HANDLE hDevice, PPUC_RESO_LIMIT_INFO pLimitInfo);

現在の撮影速度で設定可能な最大解像度（PUC_GetMaxResolution）、および機種として設定可能な上限・下限・変更単位（PUC_GetResolutionLimit）を取得します。解像度を変更する前に、設定可能範囲の確認に使用します。

引数 / 戻り値	型	説明
`pCurMaxWidth` / `pCurMaxHeight`	`UINT32*`	`[out]` 現在の撮影速度での最大解像度
`pLimitInfo`	`PPUC_RESO_LIMIT_INFO`	`[out]` 最大/最小解像度・変更単位をまとめた構造体
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_SetFramerateShutter / PUC_GetFramerateShutter

PUCRESULT WINAPI PUC_SetFramerateShutter(PUC_HANDLE hDevice, UINT32 nFramerate, UINT32 nShutterSpeedFps);
PUCRESULT WINAPI PUC_GetFramerateShutter(PUC_HANDLE hDevice, UINT32* pFramerate, UINT32* pShutterSpeedFps);

撮影速度 (fps) とシャッター速度 (1/fps) を設定・取得します。

引数 / 戻り値	型	説明
`hDevice`	`PUC_HANDLE`	`[in]` デバイスハンドル
`nFramerate` / `pFramerate`	`UINT32` / `UINT32*`	撮影速度 (fps)
`nShutterSpeedFps` / `pShutterSpeedFps`	`UINT32` / `UINT32*`	シャッター速度 (1/fps 単位)
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 不正な値は `PUC_ERROR_ILLEGAL_FRAME_RATE`

PUC_GetMaxFramerate / PUC_GetFramerateLimit

PUCRESULT WINAPI PUC_GetMaxFramerate(PUC_HANDLE hDevice, UINT32* pFramerate);
PUCRESULT WINAPI PUC_GetFramerateLimit(PUC_HANDLE hDevice, PPUC_FRAMERATE_LIMIT_INFO pLimitInfo);

現在の解像度で設定可能な最大撮影速度、および機種としての撮影速度の上限・下限を取得します。

引数 / 戻り値	型	説明
`pFramerate`	`UINT32*`	`[out]` 現在の解像度での最大撮影速度
`pLimitInfo`	`PPUC_FRAMERATE_LIMIT_INFO`	`[out]` 最大/最小撮影速度をまとめた構造体
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_SetExposeTime / PUC_GetExposeTime / PUC_GetMinExposeTime

PUCRESULT WINAPI PUC_SetExposeTime(PUC_HANDLE hDevice, UINT32 nExpOnTime, UINT32 nExpOffTime);
PUCRESULT WINAPI PUC_GetExposeTime(PUC_HANDLE hDevice, UINT32* pExpOnTime, UINT32* pExpOffTime);
PUCRESULT WINAPI PUC_GetMinExposeTime(PUC_HANDLE hDevice, UINT32* pMinExpOnTime, UINT32* pMinExpOffTime);

露光期間・非露光期間（クロック単位）を直接設定・取得します。PUC_SetFramerateShutter がシャッター速度（1/fps）単位での指定であるのに対し、こちらは露光／非露光クロックを個別に制御する、より詳細な露光時間制御用のAPIです。

引数 / 戻り値	型	説明
`nExpOnTime` / `pExpOnTime`	`UINT32` / `UINT32*`	露光期間（クロック単位）
`nExpOffTime` / `pExpOffTime`	`UINT32` / `UINT32*`	非露光期間（クロック単位）
`pMinExpOnTime` / `pMinExpOffTime`	`UINT32*`	`[out]` 現在の撮影条件で設定可能な最小露光／非露光期間
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 不正な値は `PUC_ERROR_ILLEGAL_EXPOSE_CLOCK`

PUC_SetQuantization / PUC_GetQuantization (/ PUC_SetQuantization2 / PUC_GetQuantization2)

PUCRESULT WINAPI PUC_SetQuantization(PUC_HANDLE hDevice, UINT32 nPoint, USHORT nVal);
PUCRESULT WINAPI PUC_GetQuantization(PUC_HANDLE hDevice, UINT32 nPoint, USHORT* pVal);

// PUC_Q_COUNT 個をまとめて一括取得・設定する版
PUCRESULT WINAPI PUC_GetQuantization2(PUC_HANDLE hDevice, unsigned short* pQvals);
PUCRESULT WINAPI PUC_SetQuantization2(PUC_HANDLE hDevice, unsigned short* pQvals);

デバイスに格納されている量子化テーブル（デコード処理で使用、PUC_Q_COUNT = 64個）を1つずつ、または一括で取得・設定します。デバイスを再起動すると設定はリセットされます。

引数 / 戻り値	型	説明
`nPoint`	`UINT32`	`[in]` 量子化テーブルの位置（0〜`PUC_Q_COUNT`-1）
`nVal` / `pVal`	`USHORT` / `USHORT*`	量子化テーブルデータ
`pQvals`	`unsigned short*`	`[in/out]` `PUC_Q_COUNT` 個分の配列
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_SetFanState / PUC_GetFanState

PUCRESULT WINAPI PUC_SetFanState(PUC_HANDLE hDevice, PUC_MODE nState);
PUCRESULT WINAPI PUC_GetFanState(PUC_HANDLE hDevice, PUC_MODE* pState);

デバイスのファンの状態 (PUC_ON / PUC_OFF) を設定・取得します。デバイスを再起動すると設定はリセットされます。

引数 / 戻り値	型	説明
`nState` / `pState`	`PUC_MODE` / `PUC_MODE*`	ファン状態 (`PUC_ON` / `PUC_OFF`)
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧