Image Decoding API

API specifications for decoding the proprietary DCT-compressed data received from INFINICAM into raster image data (luminance values, or Bayer-pattern data for color) using the CPU or GPU.

About error handling

For error codes on decode failure (such as PUC_ERROR_GPU_DECODE_PROCESS) and troubleshooting, see Error Code List & Handling Guide.

For C++ users: the pucutil namespace

The functions on this page are also available with identical signatures as the pucutil:: namespace (provided by PUCUTIL.h), which can be called from C++ without the PUC_ prefix (for example, PUC_DecodeData ⇔ pucutil::DecodeData). See pucutil Namespace API for details.

---

1. CPU image decoding (standard / ROI / DC extraction)

PUC_DecodeData

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

Decodes compressed image data into luminance value data (monochrome models) or Bayer-pattern color data (color models, after PUC_SetWhiteBalanceGain has been applied). By specifying a partial region rather than the entire image in nX/nY/nWidth/nHeight, you can rapidly decode only the ROI (region of interest).

Argument / Return value	Type	Description
pDst	PUINT8	[out] The destination buffer. Its width must be allocated as a multiple of 4 bytes rounded up (for example, for a width of 1246 px, allocate at least 1248 bytes)
nX / nY	UINT32	[in] The top-left coordinate at which to begin decoding. Must be 0 or a multiple of 8 (use 0, 0 to decode the entire image)
nWidth / nHeight	UINT32	[in] The width and height to decode (the region size when extracting an ROI, or the full image size otherwise)
nLineBytes	UINT32	[in] The width of the destination buffer, in bytes
pSrc	const PUINT8	[in] Compressed image data
pQVals	const PUSHORT	[in] Quantization table (obtained with PUC_GetQuantization2)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

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);

Performs the same decoding process as PUC_DecodeData, but executes it in parallel across multiple threads for speed. Use this for continuous capture at high resolution and high frame rates.

Argument / Return value	Type	Description
(In addition to the same arguments as PUC_DecodeData)
nThreadCount	UINT32	[in] The number of threads to use for processing (maximum PUC_MAX_DECODE_THREAD_COUNT = 32)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

PUC_DecodeDCTData

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

Decodes compressed image data into the DCT coefficients themselves (the frequency components after dequantization, as INT16) rather than luminance values. Use this when you want to perform your own post-processing or analysis.

Argument / Return value	Type	Description
pDst	PINT16	[out] The destination buffer for the DCT coefficients
(All other arguments are the same as PUC_DecodeData)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

PUC_DecodeDCData (1/8 DC fast preview)

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

Extracts only the DC (direct current) component of the DCT-compressed data to decode a fast preview image scaled down to 1/8 resolution in both width and height. This is significantly faster than PUC_DecodeData, which decodes the full image.

Argument / Return value	Type	Description
pDst	PUINT8	[out] The destination buffer; must be allocated for the total number of blocks included in the decode range
nBlockX / nBlockY	UINT32	[in] The block coordinate at which to begin decoding (in units of 8x8 blocks)
nBlockCountX / nBlockCountY	UINT32	[in] The number of blocks to decode (in the X and Y directions)
pSrc	const PUINT8	[in] Compressed image data
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

2. Color processing

PUC_SetWhiteBalanceGain

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

Sets the white balance gain applied to each of the R, G, and B channels during Bayer decoding for GbE-2 color models (held as a process-global setting and applied to subsequent calls to the PUC_DecodeData family of functions).

Argument / Return value	Type	Description
nGainR / nGainG / nGainB	double	[in] The gain for each channel (1.0 = no change)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

3. Header & sequence information extraction

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);

Extracts the sequence number assigned internally by the camera from the header of the compressed image data. This can be used to detect dropped frames. For GbE-2 transfer data, PUC_ExtractGbe2XferHeader can parse the entire 16-byte header (version, model type, each of the packet-loss/no-sync/over-sync/PTP/trigger flags, epoch time, and so on).

Argument / Return value	Type	Description
pData	const PUCHAR	[in] Compressed image data (transfer data)
nWidth / nHeight	UINT32	[in] The image width and height (only required for PUC_ExtractSequenceNo, used for the UC-1.1)
pSeqNo	PUSHORT	[out] Destination for the extracted sequence number
pHeader	PPUC_GBE2_XFER_HEADER	[out] Destination for the parsed result (a PUC_GBE2_XFER_HEADER structure)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

PUC_GetTimeCode2EPOC (GbE-2)

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

Converts the time code embedded in the transfer data into epoch time (seconds). The model is automatically determined from the model code in the transfer data header (the second byte). PUC_ERROR_NOTSUPPORT is returned for models that do not have a time code.

Argument / Return value	Type	Description
pSrc	PUINT8	[in] Transfer data
time	time_t*	[out] Destination for the epoch time (seconds)
Return value	PUCRESULT	PUC_SUCCEEDED on success / PUC_ERROR_NOTSUPPORT for an unsupported model

---

4. GPU (CUDA) accelerated decoding API

A group of APIs that use an NVIDIA GPU (CUDA) to accelerate decoding at large resolutions and ultra-high frame rates.

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);

Checks whether the PC supports GPU processing, initializes and releases the resources for GPU decoding, and checks whether setup has already been performed.

Argument / Return value	Type	Description
param	PUC_GPU_SETUP_PARAM	[in] A structure specifying the image resolution (width / height) to be decoded
status	bool&	[out] true = already set up / false = not yet set up
Return value	PUCRESULT	For PUC_GetAvailableGPUProcess: PUC_SUCCEEDED when GPU use is available / PUC_ERROR_NOTSUPPORT when unavailable. For the others, see the error code list on setup failure

---

PUC_DecodeGPU / PUC_GetGPULastError

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

Rapidly decodes compressed data using the GPU (CUDA). When download is false, the decoded result is left in device (GPU) memory (no host-side buffer allocation is needed); when true, it is copied to host (CPU) memory before returning.

Argument / Return value	Type	Description
download	bool	[in] true: copy to host memory / false: keep the result in device memory
pSrc	unsigned char*	[in] The compressed data to decode (in host memory)
pDst	unsigned char**	[out] When download=true, specify the destination host memory address for the copy. When false, the device memory address of the decoded result is returned here
lineBytes	UINT32	[in] The width of the destination buffer, in bytes (rounded up to a multiple of 4)
errorCode	int&	[out] The error code from the most recent GPU processing
Return value	PUCRESULT	PUC_SUCCEEDED on success / PUC_ERROR_GPU_DECODE_PROCESS, etc. on failure

Requirements for GPU decoding

To use the GPU decoding feature, a CUDA-capable NVIDIA GPU and an appropriate display driver must be set up. Also check whether the camera’s data format supports GPU decoding with PUC_IsSupported(PUC_CAP_GPU_DECODE).

---

Related pages

pucutil Namespace API (C++)An explanation of the C++ namespace that lets you call the same decoding and GPU processing without the PUC_ prefix