画像復号 (デコード) 処理 API

INFINICAM から受信した独自 DCT 圧縮データを、CPU または GPU を使用してラスタ画像データ（輝度値 / カラーは Bayer 構造）へ復号する API 仕様です。

1. CPU 画像復号 (標準 / ROI / DC 抽出)

PUC_DecodeData

PUCRESULT WINAPI PUC_DecodeData(PUINT8 pDst, UINT32 nX, UINT32 nY, UINT32 nWidth, UINT32 nHeight, UINT32 nLineBytes, const PUINT8 pSrc, const PUSHORT pQVals);

圧縮画像データを輝度値データ（モノクロモデル）または Bayer 構造のカラーデータ（カラーモデル、PUC_SetWhiteBalanceGain 適用後）に展開します。nX/nY/nWidth/nHeight に画像全体ではなく部分領域を指定することで、ROI（関心領域）のみを高速に復号できます。

引数 / 戻り値	型	説明
`pDst`	`PUINT8`	`[out]` 展開先バッファ。横幅は4の倍数に切り上げたサイズ分確保が必要（例：横幅1246pxなら1248バイト以上）
`nX` / `nY`	`UINT32`	`[in]` 展開開始する左上座標。0 もしくは 8 の倍数である必要がある（画像全体を復号する場合は `0, 0`）
`nWidth` / `nHeight`	`UINT32`	`[in]` 展開する横幅・高さ（ROI抽出時は領域のサイズ、全体の場合は画像全体のサイズ）
`nLineBytes`	`UINT32`	`[in]` 展開先バッファの横幅のバイト数
`pSrc`	`const PUINT8`	`[in]` 圧縮画像データ
`pQVals`	`const PUSHORT`	`[in]` 量子化テーブル（`PUC_GetQuantization2` で取得）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_DecodeDataMultiThread

PUCRESULT WINAPI PUC_DecodeDataMultiThread(PUINT8 pDst, UINT32 nX, UINT32 nY, UINT32 nWidth, UINT32 nHeight, UINT32 nLineBytes, const PUINT8 pSrc, const PUSHORT pQVals, UINT32 nThreadCount);

PUC_DecodeData と同じ展開処理を、複数スレッドで並列実行して高速化します。高解像度・高フレームレートでの連続キャプチャ時に使用します。

引数 / 戻り値	型	説明
（`PUC_DecodeData` と同じ引数に加えて）
`nThreadCount`	`UINT32`	`[in]` 処理に使用するスレッド数（最大 `PUC_MAX_DECODE_THREAD_COUNT` = 32）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_DecodeDCTData

PUCRESULT WINAPI PUC_DecodeDCTData(PINT16 pDst, UINT32 nX, UINT32 nY, UINT32 nWidth, UINT32 nHeight, UINT32 nLineBytes, const PUINT8 pSrc, const PUSHORT pQVals);

圧縮画像データを、輝度値ではなく DCT係数そのもの（量子化復元後の周波数成分、INT16）に展開します。独自の後処理や解析を行いたい場合に使用します。

引数 / 戻り値	型	説明
`pDst`	`PINT16`	`[out]` DCT係数の展開先バッファ
（その他の引数は `PUC_DecodeData` と同様）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_DecodeDCData (1/8 DC 高速プレビュー)

PUCRESULT WINAPI PUC_DecodeDCData(PUINT8 pDst, UINT32 nBlockX, UINT32 nBlockY, UINT32 nBlockCountX, UINT32 nBlockCountY, const PUINT8 pSrc);

DCT 圧縮データの DC（直流）成分のみを抽出し、解像度が縦横 1/8 に縮小された高速プレビュー画像を復号します。全体を復号する PUC_DecodeData より大幅に高速です。

引数 / 戻り値	型	説明
`pDst`	`PUINT8`	`[out]` 展開先バッファ。デコード範囲に含まれるブロックの総数分確保が必要
`nBlockX` / `nBlockY`	`UINT32`	`[in]` 展開開始するブロック座標（8×8ブロック単位）
`nBlockCountX` / `nBlockCountY`	`UINT32`	`[in]` 展開するブロック数（X・Y方向）
`pSrc`	`const PUINT8`	`[in]` 圧縮画像データ
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

2. カラー処理

PUC_SetWhiteBalanceGain

PUCRESULT WINAPI PUC_SetWhiteBalanceGain(double nGainR, double nGainG, double nGainB);

GbE-2 カラーモデルの Bayer デコード時に適用する R・G・B 各チャンネルのホワイトバランスゲインを設定します（プロセスグローバルに保持され、次回以降の PUC_DecodeData 系呼び出しに適用されます）。

引数 / 戻り値	型	説明
`nGainR` / `nGainG` / `nGainB`	`double`	`[in]` 各チャンネルのゲイン（`1.0` = 無変化）
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

3. ヘッダー & シーケンス情報抽出

PUC_ExtractSequenceNo / PUC_ExtractSequenceNo_GBE2 / PUC_ExtractGbe2XferHeader

PUCRESULT WINAPI PUC_ExtractSequenceNo(const PUCHAR pData, UINT32 nWidth, UINT32 nHeight, PUSHORT pSeqNo);
PUCRESULT WINAPI PUC_ExtractSequenceNo_GBE2(const PUCHAR pData, PUSHORT pSeqNo);
PUCRESULT WINAPI PUC_ExtractGbe2XferHeader(const PUCHAR pData, PPUC_GBE2_XFER_HEADER pHeader);

圧縮画像データのヘッダーから、カメラ内部で付与された連番（シーケンス番号）を抽出します。コマ落ち検知に利用できます。GbE-2 の転送データについては、PUC_ExtractGbe2XferHeader で16バイトヘッダー全体（バージョン・機種種別・パケットロス/no-sync/over-sync/PTP/トリガの各フラグ・エポックタイム等）を解析できます。

引数 / 戻り値	型	説明
`pData`	`const PUCHAR`	`[in]` 圧縮画像データ（転送データ）
`nWidth` / `nHeight`	`UINT32`	`[in]` 画像の幅・高さ（UC-1.1用の `PUC_ExtractSequenceNo` のみ必要）
`pSeqNo`	`PUSHORT`	`[out]` 抽出したシーケンス番号の格納先
`pHeader`	`PPUC_GBE2_XFER_HEADER`	`[out]` 解析結果（`PUC_GBE2_XFER_HEADER` 構造体）の格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時はエラーコード一覧

PUC_GetTimeCode2EPOC (GbE-2)

PUCRESULT WINAPI PUC_GetTimeCode2EPOC(PUINT8 pSrc, time_t* time);

転送データ内のタイムコードをエポックタイム（秒）へ変換します。機種は転送データヘッダの機種コード（2バイト目）で自動判別されます。タイムコードを持たない機種の場合は PUC_ERROR_NOTSUPPORT が返ります。

引数 / 戻り値	型	説明
`pSrc`	`PUINT8`	`[in]` 転送データ
`time`	`time_t*`	`[out]` エポックタイム（秒）の格納先
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 非対応機種は `PUC_ERROR_NOTSUPPORT`

4. GPU (CUDA) 加速デコード API

NVIDIA GPU（CUDA）を利用して大解像度・超高フレームレート時のデコード処理をアクセラレーションする API 群です。

PUC_GetAvailableGPUProcess / PUC_SetupGPUDecode / PUC_TeardownGPUDecode / PUC_IsSetupGPUDecode

PUCRESULT WINAPI PUC_GetAvailableGPUProcess();
PUCRESULT WINAPI PUC_SetupGPUDecode(PUC_GPU_SETUP_PARAM param);
PUCRESULT WINAPI PUC_TeardownGPUDecode();
PUCRESULT WINAPI PUC_IsSetupGPUDecode(bool& status);

PC が GPU 処理に対応しているかの確認、GPU デコード用リソースの初期化・解放、およびセットアップ済みかどうかの確認を行います。

引数 / 戻り値	型	説明
`param`	`PUC_GPU_SETUP_PARAM`	`[in]` デコード対象の画像解像度（`width` / `height`）を指定する構造体
`status`	`bool&`	`[out]` `true` = セットアップ済み / `false` = 未セットアップ
戻り値	`PUCRESULT`	`PUC_GetAvailableGPUProcess` はGPU利用可能時 `PUC_SUCCEEDED` / 不可時 `PUC_ERROR_NOTSUPPORT`。他はセットアップ失敗時エラーコード一覧参照

PUC_DecodeGPU / PUC_GetGPULastError

PUCRESULT WINAPI PUC_DecodeGPU(bool download, unsigned char* pSrc, unsigned char** pDst, UINT32 lineBytes);
PUCRESULT WINAPI PUC_GetGPULastError(int& errorCode);

GPU (CUDA) を使用して圧縮データを高速復号します。download が false の場合はデコード結果をデバイス（GPU）メモリ上に置いたまま（ホスト側バッファ確保は不要）、true の場合はホスト（CPU）メモリへコピーして返します。

引数 / 戻り値	型	説明
`download`	`bool`	`[in]` `true`: ホストメモリへコピー / `false`: デバイスメモリに保持したまま
`pSrc`	`unsigned char*`	`[in]` デコード対象の圧縮データ（ホストメモリ）
`pDst`	`unsigned char**`	`[out]` `download=true` 時はコピー先のホストメモリアドレスを指定。`false` 時はデコード結果のデバイスメモリアドレスが取得される
`lineBytes`	`UINT32`	`[in]` 展開先バッファの横幅のバイト数（4の倍数に切り上げ）
`errorCode`	`int&`	`[out]` 直近のGPU処理で発生したエラーコード
戻り値	`PUCRESULT`	成功時は `PUC_SUCCEEDED` / 失敗時は `PUC_ERROR_GPU_DECODE_PROCESS` 等