Image Acquisition

Acquire images (directly or in callback function), start and stopp acquisition, etc.
Supports performing ISP algorithm processing on images inside the API via the configuration file generated by the ISP tool. Before using the ISP tool, an ISP plug-in library needs to be installed, and a folder named "ISPTool" needs to be created in the personal directory in the C disk (for example, C:\Users(user name)\ISPTool). In addition, the configuration file generated by camera connecting should be placed in a folder named with the camera model or serial No., inside the ISPTool folder. To get the configuration file, please contact technical support. More...

Functions
MV_CAMCTRL_API int __stdcall	MV_CC_RegisterImageCallBackEx (IN void *handle, IN void(__stdcall *cbOutput)(unsigned char *pData, MV_FRAME_OUT_INFO_EX *pFrameInfo, void *pUser), IN void *pUser)
	Register an image data callback, supporting getting chunk information. More...
MV_CAMCTRL_API int __stdcall	MV_CC_StartGrabbing (IN void *handle)
	Start grabbing images. More...
MV_CAMCTRL_API int __stdcall	MV_CC_StopGrabbing (IN void *handle)
	End grabbing images. More...
MV_CAMCTRL_API int __stdcall	MV_CC_GetImageBuffer (IN void *handle, IN OUT MV_FRAME_OUT *pstFrame, IN unsigned int nMsec)
	Get one frame of picture using internal buffer. More...
MV_CAMCTRL_API int __stdcall	MV_CC_FreeImageBuffer (IN void *handle, IN MV_FRAME_OUT *pstFrame)
	Release image buffer. This API is used to release the image buffer which is no longer used, and it should be used with MV_CC_GetImageBuffer() in pairs. More...
MV_CAMCTRL_API int __stdcall	MV_CC_GetOneFrameTimeout (IN void *handle, IN OUT unsigned char *pData, IN unsigned int nDataSize, IN OUT MV_FRAME_OUT_INFO_EX *pstFrameInfo, IN unsigned int nMsec)
	Get one frame of picture, and the SDK waits internally until data is returned. More...
MV_CAMCTRL_API int __stdcall	MV_CC_ClearImageBuffer (IN void *handle)
	Clear the streaming data buffer. More...
MV_CAMCTRL_API int __stdcall	MV_CC_GetValidImageNum (IN void *handle, IN OUT unsigned int *pnValidImageNum)
	Get the number of valid images in the current image buffer. More...
MV_CAMCTRL_API int __stdcall	MV_CC_SetImageNodeNum (IN void *handle, IN unsigned int nNum)
	Set the number of SDK internal image buffer nodes (no less than 1). It should be called before calling MV_CC_StartGrabbing(). More...
MV_CAMCTRL_API int __stdcall	MV_CC_SetGrabStrategy (IN void *handle, IN MV_GRAB_STRATEGY enGrabStrategy)
	Set the streaming strategy. This API is only supported by USB devices. More...
MV_CAMCTRL_API int __stdcall	MV_CC_SetOutputQueueSize (IN void *handle, IN unsigned int nOutputQueueSize)
	Set number of output image buffers, with range of 1 to ImageNodeNum (only valid when MV_GRAB_STRATEGY() is set to MV_GrabStrategy_LatestImages). More...
MV_CAMCTRL_API int __stdcall	MV_CC_GetPayloadSize (IN void *handle, IN OUT uint64_t *pnPayloadSize, IN OUT unsigned int *pnAlignment)
	Get the device payload size (including image data and Chunk data) and memory alignment method, which is used by the application layer to allocate sufficient buffer and correct memory alignment when registering external memory for SDK. More...

Detailed Description

Acquire images (directly or in callback function), start and stopp acquisition, etc.
Supports performing ISP algorithm processing on images inside the API via the configuration file generated by the ISP tool. Before using the ISP tool, an ISP plug-in library needs to be installed, and a folder named "ISPTool" needs to be created in the personal directory in the C disk (for example, C:\Users(user name)\ISPTool). In addition, the configuration file generated by camera connecting should be placed in a folder named with the camera model or serial No., inside the ISPTool folder. To get the configuration file, please contact technical support.

Function Documentation

MV_CC_RegisterImageCallBackEx()

MV_CAMCTRL_API int __stdcall MV_CC_RegisterImageCallBackEx	(	IN void *	handle,
		IN	void__stdcall *cbOutput)(unsigned char *pData, MV_FRAME_OUT_INFO_EX *pFrameInfo, void *pUser,
		IN void *	pUser
	)

Register an image data callback, supporting getting chunk information.

Parameters

handle	[IN] Device handle.
cbOutput	[IN] Image data callback function.
pUser	[IN] User data.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

After calling MV_CC_CreateHandle() , call this API to set image data callback function.
There are two available image data acquisition modes, and cannot be used together:
Mode 1: Call MV_CC_RegisterImageCallBack() to set image data callback function, and then call MV_CC_StartGrabbing() to start acquisition. The acquired image data will be returned in the set callback function.
Mode 2: Call MV_CC_StartGrabbing() to start acquisition, and then call MV_CC_GetOneFrame() repeatedly in application layer to get frame data of specified pixel format. When getting frame data, the frequency of calling this API should be controlled by upper layer application according to frame rate.
This API is not supported by MV_CAMERALINK_DEVICE() device.

Examples

Events_Interface.cpp, Grab_Asynchronous.cpp, GrabImage_Callback.cpp, InterfaceAndDeviceDemo.cpp, ParametrizeCamera_AreaScanIOSettings.cpp, ParametrizeCamera_LineScanIOSettings.cpp, ReconnectDemo.cpp, and Trigger_ImageCallback.cpp.

MV_CC_StartGrabbing()

MV_CAMCTRL_API int __stdcall MV_CC_StartGrabbing

(

IN void *

handle

)

Start grabbing images.

Parameters

handle

[IN] Device handle.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

This API is not supported by CameraLink device.

Examples

ChunkData.cpp, ConnectSpecCamera.cpp, Display.cpp, Events.cpp, Events_Interface.cpp, Grab_Asynchronous.cpp, GrabImage.cpp, GrabImage_Callback.cpp, GrabImage_HighPerformance.cpp, GrabMultipleCamera.cpp, HighBandwidthDecode.cpp, ImageProcess.cpp, ImageSave.cpp, InterfaceAndDeviceDemo.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, ParametrizeCamera_AreaScanIOSettings.cpp, ParametrizeCamera_LineScanIOSettings.cpp, QuickSoftwareTrigger.cpp, ReconnectDemo.cpp, Trigger_Image.cpp, and Trigger_ImageCallback.cpp.

MV_CC_StopGrabbing()

MV_CAMCTRL_API int __stdcall MV_CC_StopGrabbing

(

IN void *

handle

)

End grabbing images.

Parameters

handle

[IN] Device handle.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

This API is not supported by CameraLink device.

Examples

ChunkData.cpp, ConnectSpecCamera.cpp, Display.cpp, Events.cpp, Events_Interface.cpp, Grab_Asynchronous.cpp, GrabImage.cpp, GrabImage_Callback.cpp, GrabImage_HighPerformance.cpp, GrabMultipleCamera.cpp, HighBandwidthDecode.cpp, ImageProcess.cpp, ImageSave.cpp, InterfaceAndDeviceDemo.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, ParametrizeCamera_AreaScanIOSettings.cpp, ParametrizeCamera_LineScanIOSettings.cpp, QuickSoftwareTrigger.cpp, Trigger_Image.cpp, and Trigger_ImageCallback.cpp.

MV_CC_GetImageBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_GetImageBuffer	(	IN void *	handle,
		IN OUT MV_FRAME_OUT *	pstFrame,
		IN unsigned int	nMsec
	)

Get one frame of picture using internal buffer.

Parameters

handle	[IN] Device handle.
pstFrame	[IN][OUT] Image data and information.
nMsec	[IN] Timeout duration, unit: millisecond. Input INFINITE to set unlimited timeout period, and image acquisition will not stop until receiving a frame of picture.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

• Before calling this API to get image data frame, you should call MV_CC_StartGrabbing() to start image acquisition. This API gets frame data actively, so the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, and SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.
• This API and MV_CC_FreeImageBuffer() should be called in pairs, after processing the acquired data, you should call MV_CC_FreeImageBuffer() to release the data pointer permission of pstFrame.
• This API's streaming buffer is allocated by the SDK internally, so it has higher image acquisition efficiency than MV_CC_GetOneFrameTimeout () , whose streaming buffer needs to be manually allocated by the user.
• This API cannot be called to stream after calling MV_CC_Display() .
• This API is not supported by CameraLink device.
• This API is supported by both USB3 vision camera and GigE camera.

Examples

ChunkData.cpp, ConnectSpecCamera.cpp, Display.cpp, GrabImage.cpp, GrabImage_HighPerformance.cpp, GrabMultipleCamera.cpp, HighBandwidthDecode.cpp, ImageProcess.cpp, ImageSave.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, QuickSoftwareTrigger.cpp, and Trigger_Image.cpp.

MV_CC_FreeImageBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_FreeImageBuffer	(	IN void *	handle,
		IN MV_FRAME_OUT *	pstFrame
	)

Release image buffer. This API is used to release the image buffer which is no longer used, and it should be used with MV_CC_GetImageBuffer() in pairs.

Parameters

handle	[IN] Device handle.
pstFrame	[IN] Image data and information.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

• This API and MV_CC_GetImageBuffer() should be called in pairs. Before calling MV_CC_GetImageBuffer() to get image data pstFrame, you should call this API to release the permission.
• Compared with the API MV_CC_GetOneFrameTimeout() , this API has higher efficiency of image acquisition. The max. number of nodes that can be outputted from MV_CC_GetImageBuffer()(without freeing the buffer) is the same as the "nNum" from API MV_CC_SetImageNodeNum() . The default value is 1.
• This API is not supported by CameraLink device.
• This API is supported by both USB3 vision camera and GigE camera.

Examples

ChunkData.cpp, ConnectSpecCamera.cpp, Display.cpp, GrabImage.cpp, GrabImage_HighPerformance.cpp, GrabMultipleCamera.cpp, HighBandwidthDecode.cpp, ImageProcess.cpp, ImageSave.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, QuickSoftwareTrigger.cpp, and Trigger_Image.cpp.

MV_CC_GetOneFrameTimeout()

MV_CAMCTRL_API int __stdcall MV_CC_GetOneFrameTimeout	(	IN void *	handle,
		IN OUT unsigned char *	pData,
		IN unsigned int	nDataSize,
		IN OUT MV_FRAME_OUT_INFO_EX *	pstFrameInfo,
		IN unsigned int	nMsec
	)

Get one frame of picture, and the SDK waits internally until data is returned.

Parameters

handle	[IN] Device handle.
pData	[OUT] Buffer address used to save image data
nDataSize	[IN] Buffer size.
pstFrameInfo	[OUT] Obtained frame information.
nMsec	[IN] Waiting timeout, unit: millisecond.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

• Before calling this API to get image data frame, you should call MV_CC_StartGrabbing() to start image acquisition. This API gets frame data actively, so the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, and SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.
• This API is supported by both the USB3Vision and GIGE camera.
• This API is not supported by CameraLink device.

MV_CC_ClearImageBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_ClearImageBuffer

(

IN void *

handle

)

Clear the streaming data buffer.

Parameters

handle

[IN] Device handle.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

• You can call this API to clear the needless images in the buffer even when the streaming is in progress.
• You can call this API to clear history data when the continuous mode is switched to the trigger mode.
• You can call this API to clear internal image buffer of SDK, and image buffer clearing of frame grabbers is not supported.

MV_CC_GetValidImageNum()

MV_CAMCTRL_API int __stdcall MV_CC_GetValidImageNum	(	IN void *	handle,
		IN OUT unsigned int *	pnValidImageNum
	)

Get the number of valid images in the current image buffer.

Parameters

handle	[IN] Device handle.
pnValidImageNum	[IN][OUT] The number of valid images in the current image buffer.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

This API is only used for internal valid images of SDK, not for those of frame grabbers.

MV_CC_SetImageNodeNum()

MV_CAMCTRL_API int __stdcall MV_CC_SetImageNodeNum	(	IN void *	handle,
		IN unsigned int	nNum
	)

Set the number of SDK internal image buffer nodes (no less than 1). It should be called before calling MV_CC_StartGrabbing().

Parameters

handle	[IN] Device handle.
nNum	[IN] The number of SDK internal image buffer nodes.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

• Call this API to set the number of SDK internal image buffer nodes.
• Image grabbing methods vary from different camera types. If this API is not called, the default buffer node quantity is different. Take a camera with two USB interfaces as an example, there are 3 buffer nodes by default.
• Allocated node quantity for SDK equals to the pre-allocated node quantity for SDK plus node quantity allocated via this API.
  If memory allocated by the system is insufficient, the pre-allocated node quantity for SDK will be calculated again. In that case, the actually allocated node quantity is based on the calculation of the new pre-allocated node quantity.
• This API is not supported for Camera Link devices. Number of buffer nodes can be connected and set via GenTL for Camera Link devices.

MV_CC_SetGrabStrategy()

MV_CAMCTRL_API int __stdcall MV_CC_SetGrabStrategy	(	IN void *	handle,
		IN MV_GRAB_STRATEGY	enGrabStrategy
	)

Set the streaming strategy. This API is only supported by USB devices.

Parameters

handle	[IN] Device handle.
enGrabStrategy	[IN] Streaming strategy.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

There are three defined streaming strategies, from which you can choose the suitable one according to the actual requirement. And this API only supports USB devices.

Macro Definition	Description
OneByOne	Get image frames one by one in the chronological order. It is the default strategy.
LatestImagesOnly	Only get the latest one frame from the output buffer list, and clear the rest images in the list.
LatestImages	Get the latest image from the output buffer list, and the quantity of frames depends on the parameter OutputQueueSize, value range: [1,ImageNodeNum]. If the OutputQueueSize values "1", the strategy is same to "LatestImagesOnly", and if the OutputQueueSize values "ImageNodeNum", the strategy is same to "OneByOne". You can set the OutputQueueSize via API MV_CC_SetOutputQueueSize(), and set the ImageNodeNum via API MV_CC_SetImageNodeNum().

MV_CC_SetOutputQueueSize()

MV_CAMCTRL_API int __stdcall MV_CC_SetOutputQueueSize	(	IN void *	handle,
		IN unsigned int	nOutputQueueSize
	)

Set number of output image buffers, with range of 1 to ImageNodeNum (only valid when MV_GRAB_STRATEGY() is set to MV_GrabStrategy_LatestImages).

Parameters

handle	[IN] Device handle.
nOutputQueueSize	[IN] Number of output image buffers.

Returns

Return MV_OK for success, and return corresponding error code for failure.

Note

 • This API must be used with LatestImages Grab strategy, it is used for setting the maximum allowance queue size of the image under the LatestImages strategy. The user may change the output queue size while grabbing images.  • For a camera with two USB interfaces, the value of nOutputQueueSize should be no less than 2.  • This API only supports cameras with USB interfaces.

MV_CC_GetPayloadSize()

MV_CAMCTRL_API int __stdcall MV_CC_GetPayloadSize	(	IN void *	handle,
		IN OUT uint64_t *	pnPayloadSize,
		IN OUT unsigned int *	pnAlignment
	)

Get the device payload size (including image data and Chunk data) and memory alignment method, which is used by the application layer to allocate sufficient buffer and correct memory alignment when registering external memory for SDK.

Parameters

handle	[IN] Device Handle.
pnPayloadSize	[IN][OUT] Payload size.
pnAlignment	[IN][OUT] Alignment bytes.

Returns

Return MV_OK for success, and return corresponding error code for failure.