Data Transfer & External Synchronization API

API specifications for receiving high-speed image data from INFINICAM (single-frame transfer and continuous streaming transfer), and for controlling external synchronization (SYNC IN / OUT and general-purpose I/O) using GPIO signals.

About error handling

For details on the error codes (PUCRESULT) returned by this API and countermeasures for transfer timeouts, see Error Code List & Handling Guide.

---

1. Single data acquisition

PUC_GetXferDataSize / PUC_GetMaxXferDataSize

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

Retrieves the transfer data size per frame (number of bytes of compressed data) under the current capture conditions, and the maximum size that can be set. Call this before capture to determine the size of the buffer to allocate for receiving data.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
pDataSize	UINT32*	[out] Destination for the transfer data size (in bytes)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

PUC_GetSingleXferData

PUCRESULT WINAPI PUC_GetSingleXferData(PUC_HANDLE hDevice, PPUC_XFER_DATA_INFO pXferData);

Synchronously retrieves one frame’s worth of compressed image data from the camera.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
pXferData	PPUC_XFER_DATA_INFO	[in/out] Specify pData (a pre-allocated receive buffer) and nDataSize (the buffer size); after retrieval, the actual data size, sequence number, and corruption flag are stored here
Return value	PUCRESULT	PUC_SUCCEEDED on success / PUC_ERROR_XFERRING during a transfer

Note

This cannot be run while continuous transfer (PUC_BeginXferData) is in progress. To perform a single capture, first stop streaming with PUC_EndXferData and then run this.

---

2. Continuous data transfer (streaming)

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

Starts and stops continuous image transfer (streaming), and checks whether a transfer is currently in progress. callback is invoked each time one frame’s worth of data has been received.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
callback	RECEIVE_CALLBACK	[in] Callback function invoked when one frame’s reception is complete
arg	void*	[in] Arbitrary user parameter passed to the callback function
pIsXferring	BOOL*	[out] Destination for whether a transfer is in progress
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

Caution

PUC_EndXferData / PUC_CloseDevice cannot be called from within the callback function (doing so returns PUC_ERROR_XFERRING). Always perform stop/close operations from a thread outside the callback. Also, calling a configuration API such as resolution or frame rate while PUC_BeginXferData is active results in a PUC_ERROR_XFERRING error, so always stop the transfer with PUC_EndXferData before changing capture conditions.

---

PUC_SetRingBufferCount / PUC_GetRingBufferCount

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

Sets and retrieves the number of elements in the ring buffer that the SDK internally allocates during continuous transfer. Increasing this number makes dropped frames less likely even if application-side processing is temporarily delayed.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
nCount / pCount	UINT32 / UINT32*	Ring buffer count (PUC_MIN_RING_BUF_COUNT to PUC_MAX_RING_BUF_COUNT)
Return value	PUCRESULT	PUC_SUCCEEDED on success / PUC_ERROR_RING_BUF_COUNT for a value out of range

---

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

Sets and retrieves the timeout duration (in milliseconds) for when there is no response from the device, separately for single transfer and continuous transfer.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
nSingleXferTimeOut / pSingleXferTimeOut	UINT32 / UINT32*	Timeout (ms) for PUC_GetSingleXferData
nContinuousXferTimeOut / pContinuousXferTimeOut	UINT32 / UINT32*	Timeout (ms) during continuous transfer
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

Note

Specify PUC_XFER_TIMEOUT_AUTO (0) for automatic adjustment, or PUC_XFER_TIMEOUT_INFINITE (0xFFFFFFFF) for unlimited. Whether this setting takes effect depends on the model, which you can check with PUC_IsSupported(PUC_CAP_XFER_TIMEOUT).

---

PUC_ResetSequenceNo

PUCRESULT WINAPI PUC_ResetSequenceNo(PUC_HANDLE hDevice);

Resets the sequence number counter for the transferred data.

Argument / Return value	Type	Description
hDevice	PUC_HANDLE	[in] Device handle
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

3. External synchronization signal control (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);

Sets and retrieves the camera’s synchronization input mode (internal operation / external signal synchronization / PTP master clock synchronization) and the polarity of the SYNC IN signal. PUC_GetExternalSyncStatus lets you check the actual synchronization state (not synchronized / synchronizing / no signal input / OverSync) and the frequency.

Argument / Return value	Type	Description
nMode / pMode	PUC_SYNC_MODE / PUC_SYNC_MODE*	PUC_SYNC_INTERNAL / PUC_SYNC_EXTERNAL / PUC_SYNC_EXTERNAL_PTP (GbE-2 only)
nSignal / pSignal	PUC_SIGNAL / PUC_SIGNAL*	Polarity (PUC_SIGNAL_POSI / PUC_SIGNAL_NEGA). Can only be retrieved when external synchronization is configured. Devices with firmware version 1.01 or earlier do not support specifying the polarity
pStatus	UINT32*	[out] Synchronization status (0 = not synchronized, 1 = synchronizing, 2 = no synchronization signal input, 3 = OverSync)
pFrequency	UINT32*	[out] Frequency (Hz)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

Caution

When external device synchronization is configured, the exposure time is automatically adjusted to account for variation in the external device. Change the frame rate and exposure time you want to use before configuring external device synchronization. The setting is reset when the device is restarted.

---

PUC_SetSyncOutSignal / PUC_GetSyncOutSignal

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

Sets and retrieves the polarity of the synchronization signal output (SYNC OUT).

Argument / Return value	Type	Description
nSignal / pSignal	PUC_SIGNAL / PUC_SIGNAL*	Polarity (PUC_SIGNAL_POSI / PUC_SIGNAL_NEGA)
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

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

Sets and retrieves the SYNC OUT signal’s delay amount and output width (both in nsec), output magnification (for example, 2 for 2x, with PUC_SYNC_OUT_MAGNIFICATION_0_5 representing 0.5x), and output count multiplier (PUC_SYNC_OUT_TIMES).

Argument / Return value	Type	Description
nDelay / pDelay, nWidth / pWidth	UINT32 / UINT32*	Delay amount / output width (in nsec; values under 100 nsec are rounded up)
nMagnification / pMagnification	UINT32 / UINT32*	Output magnification
nTimes / pTimes	PUC_SYNC_OUT_TIMES / PUC_SYNC_OUT_TIMES*	Output count multiplier
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

Caution

Changing the frame rate, exposure/non-exposure period, or output width automatically resets the output magnification (PUC_SetSyncOutMagnification) to 1x. All of these settings are also reset when the device is opened or restarted.

---

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

Detailed GPIO configuration APIs that set and retrieve the delay amount/output width (in nsec) for SYNC IN, trigger input, exposure, and PP (Pulse-Per-second) output respectively. Support for each depends on the model, so check with PUC_IsSupported before use (see Common Constants & Enumerations for the corresponding PUC_CAPABILITY values).

Argument / Return value	Type	Description
nDelay / pDelay, nWidth / pWidth	UINT32 / UINT32*	Delay amount / output width (in nsec)
Return value	PUCRESULT	PUC_SUCCEEDED on success / PUC_ERROR_NOTSUPPORT for an unsupported model

---

4. General-purpose I/O (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);

Sets and retrieves the signal type assigned to a general-purpose output port (vertical synchronization, exposure period, recording, trigger detection, etc.; see the list).

Argument / Return value	Type	Description
GenOutType	PUC_GENERAL_OUT_SIGNAL_TYPE	[in] The signal type whose support you want to check
isSupported	bool*	[out] Whether it is supported
portNo	int	[in] The target port number
type / *type	PUC_GENERAL_OUT_SIGNAL_TYPE / PUC_GENERAL_OUT_SIGNAL_TYPE*	The signal type to assign
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

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

Sets and retrieves the signal type assigned to a general-purpose input port (event input, trigger input, external synchronization input, power-off input, etc.). The available types differ by model, so check in advance with PUC_GetSupportedGeneralInSignal.

Argument / Return value	Type	Description
GenInType	PUC_GENERAL_IN_SIGNAL_TYPE	[in] The signal type whose support you want to check
isSupported	bool*	[out] Whether it is supported
portNo	int	[in] The target port number
type / *type	PUC_GENERAL_IN_SIGNAL_TYPE / PUC_GENERAL_IN_SIGNAL_TYPE*	The signal type to assign
Return value	PUCRESULT	PUC_SUCCEEDED on success / see the error code list on failure

---

Related pages

Image Decoding APIAn explanation of the CPU / GPU decoding API that decodes image data from the receive buffer