图像采集

包含图像获取（回调取图、主动取图）、开始/结束取流接口等。 更多...

函数
MV_CAMCTRL_API int __stdcall	MV_CC_RegisterImageCallBackEx (IN void *handle, IN MvImageCallbackEx cbOutput, IN void *pUser)
	注册图像数据回调 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_RegisterImageCallBackEx2 (IN void *handle, IN MvImageCallbackEx2 cbOutput, IN void *pUser, IN bool bAutoFree)
	注册图像数据回调 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_StartGrabbing (IN void *handle)
	开始取流 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_StopGrabbing (IN void *handle)
	停止取流 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_GetImageBuffer (IN void *handle, IN OUT MV_FRAME_OUT *pstFrame, IN unsigned int nMsec)
	获取一帧图片（与 MV_CC_Display() 不能同时使用） 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_FreeImageBuffer (IN void *handle, IN MV_FRAME_OUT *pstFrame)
	释放图像缓存（此接口用于释放不再使用的图像缓存，与 MV_CC_GetImageBuffer() 配套使用） 更多...
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)
	采用超时机制获取一帧图片，SDK内部等待直到有数据时返回 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_ClearImageBuffer (IN void *handle)
	清除取流数据缓存 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_GetValidImageNum (IN void *handle, IN OUT unsigned int *pnValidImageNum)
	获取当前图像缓存区的有效图像个数 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_SetImageNodeNum (IN void *handle, IN unsigned int nNum)
	设置SDK内部图像缓存节点个数，大于等于1，在抓图前调用 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_SetGrabStrategy (IN void *handle, IN MV_GRAB_STRATEGY enGrabStrategy)
	设置取流策略 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_SetOutputQueueSize (IN void *handle, IN unsigned int nOutputQueueSize)
	设置输出缓存个数（只有在 MV_GrabStrategy_LatestImages 策略下才有效，范围：1-ImageNodeNum） 更多...
MV_CAMCTRL_API void *__stdcall	MV_CC_AllocAlignedBuffer (IN uint64_t nBufSize, IN unsigned int nAlignment)
	分配对齐内存 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_FreeAlignedBuffer (IN void *pBuffer)
	对齐内存释放 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_GetPayloadSize (IN void *handle, IN OUT uint64_t *pnPayloadSize, IN OUT unsigned int *pnAlignment)
	获取设备payload大小（payload包含图像数据和Chunk数据）和内存对其方式，用于SDK外部注册缓存时，应用层分配足够的缓存及正确的内存对齐方式 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_RegisterBuffer (IN void *handle, IN void *pBuffer, IN uint64_t nBufSize, IN void *pUser)
	将应用程序分配缓存注册到SDK内部，供SDK使用 更多...
MV_CAMCTRL_API int __stdcall	MV_CC_UnRegisterBuffer (IN void *handle, IN void *pBuffer)
	外部内存取消SDK内部注册 更多...

详细描述

包含图像获取（回调取图、主动取图）、开始/结束取流接口等。

支持通过ISP工具生成的配置文件在取图接口内部对图像进行ISP算法处理。
使用时需要先安装ISP插件库，创建“ISPTool”文件夹，并将连接相机生成的配置文件以相机型号或序列号命名的文件夹形式放置在ISPTool下。 具体配置文件请联系技术支持获取。

函数说明

MV_CC_RegisterImageCallBackEx()

MV_CAMCTRL_API int __stdcall MV_CC_RegisterImageCallBackEx	(	IN void *	handle,
		IN MvImageCallbackEx	cbOutput,
		IN void *	pUser
	)

注册图像数据回调

参数

handle	[IN] 设备句柄
cbOutput	[IN] 回调函数指针
pUser	[IN] 用户自定义变量

返回

成功，返回MV_OK；失败，返回状态码。

备注

通过该接口可以设置图像数据回调函数，在 MV_CC_CreateHandle() 之后即可调用。

图像数据采集有两种方式，两种方式不能复用：

• 调用 MV_CC_RegisterImageCallBackEx() 设置图像数据回调函数，然后调用 MV_CC_StartGrabbing() 开始采集，采集的图像数据在设置的回调函数中返回。
  
• 调用 MV_CC_StartGrabbing() 开始采集，然后在应用层循环调用 MV_CC_GetImageBuffer() 和 MV_CC_FreeImageBuffer() 获取指定像素格式的帧数据，获取帧数据时上层应用程序需要根据帧率控制好调用该接口的频率。
  

注解

该接口不支持M MV_CAMERALINK_DEVICE() 的设备。

示例

ParametrizeCamera_AreaScanIOSettings.cpp.

MV_CC_RegisterImageCallBackEx2()

MV_CAMCTRL_API int __stdcall MV_CC_RegisterImageCallBackEx2	(	IN void *	handle,
		IN MvImageCallbackEx2	cbOutput,
		IN void *	pUser,
		IN bool	bAutoFree
	)

注册图像数据回调

参数

handle	[IN] 设备句柄
cbOutput	[IN] 回调函数指针
bAutoFree	[IN] 图像缓存自动回收标记 true：回调结束后，图像缓存会被SDK回收 false：回调结束后，需要调用 MV_CC_FreeImageBuffer() 接口才能回收图像缓存
pUser	[IN] 用户自定义变量

返回

成功，返回MV_OK；失败，返回状态码

备注

• 通过该接口可以设置图像数据回调函数，在 MV_CC_CreateHandle() 之后即可调用。
• 该接口不支持 MV_CAMERALINK_DEVICE 类型的设备。
• 该方式与 MV_CC_RegisterImageCallBackEx() 等注册图像回调函数的接口互斥；
• 该接口与 MV_CC_GetImageBuffer() 、 MV_CC_GetOneFrameTimeout() 等主动取流接口互斥；
• 该接口中 MvImageCallbackEx2 的“MV_FRAME_OUT* pstFrame”为SDK内部变量。如需在回调函数外使用，您需浅拷贝pstFrame结构体(不需要拷贝图像数据)。

示例

Events_Interface.cpp, Grab_Asynchronous.cpp, GrabImage_Callback.cpp, InterfaceAndDeviceDemo.cpp, LineScanSoftwareTrigger.cpp, ParametrizeCamera_LineScanIOSettings.cpp, ReconnectDemo.cpp , 以及 Trigger_ImageCallback.cpp.

MV_CC_StartGrabbing()

MV_CAMCTRL_API int __stdcall MV_CC_StartGrabbing

(

IN void *

handle

)

开始取流

参数

handle

[IN] 设备句柄

返回

成功，返回MV_OK；失败，返回状态码。

备注

该接口不支持 MV_CAMERALINK_DEVICE 类型的设备。

示例

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, LineScanSoftwareTrigger.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, ParametrizeCamera_AreaScanIOSettings.cpp, ParametrizeCamera_LineScanIOSettings.cpp, QuickSoftwareTrigger.cpp, ReconnectDemo.cpp, Trigger_Image.cpp , 以及 Trigger_ImageCallback.cpp.

MV_CC_StopGrabbing()

MV_CAMCTRL_API int __stdcall MV_CC_StopGrabbing

(

IN void *

handle

)

停止取流

参数

handle

[IN] 设备句柄

返回

成功，返回MV_OK；失败，返回状态码。

备注

该接口不支持 MV_CAMERALINK_DEVICE 类型的设备。

示例

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, LineScanSoftwareTrigger.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, ParametrizeCamera_AreaScanIOSettings.cpp, ParametrizeCamera_LineScanIOSettings.cpp, QuickSoftwareTrigger.cpp, Trigger_Image.cpp , 以及 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
	)

获取一帧图片（与 MV_CC_Display() 不能同时使用）

参数

handle	[IN] 设备句柄
pstFrame	[IN][OUT] 图像数据和图像信息
nMsec	[IN] 等待超时时间，输入INFINITE时表示无限等待，直到收到一帧数据或者停止取流

返回

成功，返回MV_OK；失败，返回状态码。

备注

• 调用该接口获取图像数据帧之前需要先调用 MV_CC_StartGrabbing() 启动图像采集。该接口为主动式获取帧数据，上层应用程序需要根据帧率，控制好调用该接口的频率。该接口支持设置超时时间，SDK内部等待直到有数据时返回，可以增加取流平稳性，适合用于对平稳性要求较高的场合。
  
• 该接口与 MV_CC_FreeImageBuffer() 配套使用，当处理完取到的数据后，需要用 MV_CC_FreeImageBuffer() 接口将pstFrame内的数据指针权限进行释放。
  
• 该接口与 MV_CC_GetOneFrameTimeout() 相比，有着更高的效率。且其取流缓存的分配由sdk内部自动分配或者外部注册，而 MV_CC_GetOneFrameTimeout() 接口是需要客户自行分配。
  
• 该接口在调用 MV_CC_Display() 后无法取流。
  
• 该接口对于U3V、GIGE设备均可支持。
  
• 该接口不支持CameraLink设备。
  

示例

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 , 以及 Trigger_Image.cpp.

MV_CC_FreeImageBuffer()

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

释放图像缓存（此接口用于释放不再使用的图像缓存，与 MV_CC_GetImageBuffer() 配套使用）

参数

handle	[IN] 设备句柄
pstFrame	[IN] 图像数据和图像数据

返回

成功，返回MV_OK；失败，返回状态码。

备注

• 该接口与 MV_CC_GetImageBuffer() 配套使用，使用 MV_CC_GetImageBuffer() 接口取到的图像数据pstFrame，需要用 MV_CC_FreeImageBuffer() 接口进行权限释放。
  
• 该接口对于取流效率高于 MV_CC_GetOneFrameTimeout() 接口，且 MV_CC_GetImageBuffer() 在不进行Free的情况下，最大支持输出的节点数与 MV_CC_SetImageNodeNum() 接口所设置的节点数相等，默认节点数是1。
  
• 该接口对于U3V、GIGE设备均可支持。
  
• 该接口不支持CameraLink设备。
  

示例

ChunkData.cpp, ConnectSpecCamera.cpp, Display.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, LineScanSoftwareTrigger.cpp, MultiCast.cpp, MultiLightCtrl_ImageStitching.cpp, ParametrizeCamera_LineScanIOSettings.cpp, QuickSoftwareTrigger.cpp, ReconnectDemo.cpp, Trigger_Image.cpp , 以及 Trigger_ImageCallback.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
	)

采用超时机制获取一帧图片，SDK内部等待直到有数据时返回

参数

handle	[IN] 设备句柄
pData	[IN][OUT] 图像数据接收指针
nDataSize	[IN] 接收缓存大小
pstFrameInfo	[IN][OUT] 图像信息结构体
nMsec	[IN] 等待超时时间

返回

成功，返回MV_OK；失败，返回状态码。

备注

调用该接口获取图像数据帧之前需要先调用 MV_CC_StartGrabbing() 启动图像采集。该接口为主动式获取帧数据，上层应用程序需要根据帧率，控制好调用该接口的频率。该接口支持设置超时时间，SDK内部等待直到有数据时返回，可以增加取流平稳性，适合用于对平稳性要求较高的场合。

注解

• 该接口对于U3V、GigE设备均可支持。
  
• 该接口不支持CameraLink设备。
  

MV_CC_ClearImageBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_ClearImageBuffer

(

IN void *

handle

)

清除取流数据缓存

参数

handle

[IN] 设备句柄

返回

成功，返回MV_OK；失败，返回状态码。

备注

• 该接口允许用户在不停止取流的时候，就能清除缓存中不需要的图像。
  
• 该接口在连续模式切触发模式后，可以清除历史数据。
  
• 该接口当前仅支持清除SDK内部的图像缓存，暂不支持清除采集卡内的缓存。

MV_CC_GetValidImageNum()

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

获取当前图像缓存区的有效图像个数

参数

handle	[IN] 设备句柄
pnValidImageNum	[IN][OUT] 当前图像缓存区中有效图像个数的指针

返回

成功，返回MV_OK；失败，返回状态码。

备注

该接口只统计SDK内部的有效图像个数，不包括采集卡缓存内的有效图像个数

MV_CC_SetImageNodeNum()

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

设置SDK内部图像缓存节点个数，大于等于1，在抓图前调用

参数

handle	[IN] 设备句柄
nNum	[IN] 缓存节点个数

返回

成功，返回MV_OK；失败，返回状态码。

备注

• 调用该接口可以设置SDK内部图像缓存节点个数，在调用 MV_CC_StartGrabbing() 开始抓图前调用。
  
• 由于不同相机的取流方式不同，在不调用 MV_CC_SetImageNodeNum() 情况下，不同相机的默认缓存节点个数不同。比如双U内部默认分配3个节点。
  
• SDK实际分配的节点个数 = SDK内部预分配的个数 + 通过调用该接口分配的节点；若系统内存资源不够，SDK内部将重新计算预分配的缓存节点个数，在该情况下，SDK实际分配的节点个数以重新计算的节点个数为准。
  
• 该接口不支持CameraLink设备。CameraLink设备可以通过GenTL方式连接并设置缓存节点个数。
  

MV_CC_SetGrabStrategy()

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

设置取流策略

参数

handle	[IN] 设备句柄
enGrabStrategy	[IN] 策略枚举值

返回

成功，返回MV_OK；失败，返回状态码。

备注

该接口定义了四种取流策略，用户可以根据实际需求进行选择。具体描述如下：

• OneByOne：从旧到新一帧一帧的从输出缓存列表中获取图像，打开设备后默认为该策略
• LatestImagesOnly：仅从输出缓存列表中获取最新的一帧图像，同时清空输出缓存列表
• LatestImages：从输出缓存列表中获取最新的OutputQueueSize帧图像，其中OutputQueueSize范围为1-ImageNodeNum，可用 MV_CC_SetOutputQueueSize() 接口设置，ImageNodeNum默认为1，可用 MV_CC_SetImageNodeNum() 接口设置 OutputQueueSize设置成1等同于LatestImagesOnly策略，OutputQueueSize设置成ImageNodeNum等同于OneByOne策略
• UpcomingImage：在调用取流接口时忽略输出缓存列表中所有图像，并等待设备即将生成的一帧图像。该策略仅支持GigE设备和USB设备

注解

• WINDOWS 该接口仅支持 MV_GIGE_DEVICE 、 MV_USB_DEVICE 设备。
• LINUX 该接口仅支持 MV_USB_DEVICE 设备。

MV_CC_SetOutputQueueSize()

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

设置输出缓存个数（只有在 MV_GrabStrategy_LatestImages 策略下才有效，范围：1-ImageNodeNum）

参数

handle	[IN] 设备句柄
nOutputQueueSize	[IN] 输出缓存个数

返回

成功，返回MV_OK；失败，返回状态码。

备注

该接口需与LatestImages取流策略配套调用，用于设置LatestImages策略下最多允许缓存图像的个数。可以在取流过程中动态调节输出缓存个数。

注解

• WINDOWS 该接口仅支持 MV_GIGE_DEVICE 、 MV_USB_DEVICE 设备。
• LINUX 该接口仅支持 MV_USB_DEVICE 设备。

MV_CC_AllocAlignedBuffer()

MV_CAMCTRL_API void* __stdcall MV_CC_AllocAlignedBuffer	(	IN uint64_t	nBufSize,
		IN unsigned int	nAlignment
	)

分配对齐内存

参数

nBufSize	[IN] 分配内存的长度
nAlignment	[IN] 内存对齐字节数 (必须是大于0，并且是2的整数次幂)

返回

成功，返回申请内存地址；失败，返回 NULL

MV_CC_FreeAlignedBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_FreeAlignedBuffer

(

IN void *

pBuffer

)

对齐内存释放

参数

pBuffer

[IN] 内存地址

返回

成功，返回MV_OK；失败，返回状态码。

备注

对齐内存的释放，搭配 MV_CC_AllocAlignedBuffer() 使用

MV_CC_GetPayloadSize()

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

获取设备payload大小（payload包含图像数据和Chunk数据）和内存对其方式，用于SDK外部注册缓存时，应用层分配足够的缓存及正确的内存对齐方式

参数

handle	[IN] 设备句柄
pnPayloadSize	[IN OUT] 负载长度
pnAlignment	[IN OUT] 负载内存对齐的字节数

返回

成功，返回MV_OK；失败，返回状态码。

备注

MV_CC_RegisterBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_RegisterBuffer	(	IN void *	handle,
		IN void *	pBuffer,
		IN uint64_t	nBufSize,
		IN void *	pUser
	)

将应用程序分配缓存注册到SDK内部，供SDK使用

参数

handle	[IN] 设备句柄
pBuffer	[IN] 内存地址
nBufSize	[IN] 内存长度
pUser	[IN] 用户指针

返回

成功，返回MV_OK；失败，返回状态码。

备注

可以使用 MV_CC_GetPayloadSize() 获取缓存大小，并使用 MV_CC_AllocAlignedBuffer() 分配空间，之后使用 MV_CC_RegisterBuffer() 注册

• 注册的缓存需要由应用层通知SDK取消注册（ MV_CC_UnRegisterBuffer() ）后，进行释放（ MV_CC_FreeAlignedBuffer() ）。
• 使用该接口后，仅支持 MV_CC_GetImageBuffer() / MV_CC_FreeImageBuffer() / MV_CC_RegisterImageCallBackEx() 获取图像，不支持其他接口获取图像。
  

注解

• 使用该接口后，如果之前配置了SDK内部节点（ MV_CC_SetImageNodeNum() ）无效。
  
• 双USB接口相机要求至少注册3块空间到SDK内部。其他相机暂无限制，但是为了避免缓存不足，请配置足够的缓存到底层。
  

MV_CC_UnRegisterBuffer()

MV_CAMCTRL_API int __stdcall MV_CC_UnRegisterBuffer	(	IN void *	handle,
		IN void *	pBuffer
	)

外部内存取消SDK内部注册

参数

handle	[IN] 设备句柄
pBuffer	[IN] 外部内存地址

返回

成功，返回MV_OK；失败，返回状态码。