Device Access

Functions for accessing device and memory (especially image specific/captured data) functionality. More...

Functions
TDMR_ERROR DMR_CALL	DMR_AcquisitionStart (HDRV hDrv)
	Manually starts the acquisition engine of this device driver instance.
TDMR_ERROR DMR_CALL	DMR_AcquisitionStop (HDRV hDrv)
	Manually stops the acquisition engine of this device driver instance.
TDMR_ERROR DMR_CALL	DMR_AllocImageBuffer (ImageBuffer **ppBuffer, TImageBufferPixelFormat pixelFormat, int width, int height)
	Allocates memory for a new ImageBuffer structure and the associated pixel memory.
TDMR_ERROR DMR_CALL	DMR_AllocImageRequestBufferDesc (ImageBuffer **ppBuffer, int channelCount)
	Allocates memory for a new ImageBuffer structure.
TDMR_ERROR DMR_CALL	DMR_BuildImpactImage (const ImageBuffer *pBuffer, IPL_BUFHANDLE *pBufHandle, TImpactBufferFlag flags, void *pReserved, size_t reservedSize)
	Converts an image from the drivers internal format into the mvIMPACT processing libraries format.
TDMR_ERROR DMR_CALL	DMR_Close (void)
	Frees internal data structures and decreases the usage counter for this library.
TDMR_ERROR DMR_CALL	DMR_CloseDevice (HDRV hDrv, HDEV hDev)
	Closes a device.
TDMR_ERROR DMR_CALL	DMR_CloseVideoStream (HDMR_VIDEO_STREAM hVideoStream)
	Closes a video stream and frees resources.
TDMR_ERROR DMR_CALL	DMR_CopyCameraDescription (HDRV hDrv, HLIST hCameraDescList, const char *pNewName)
	Creates a new camera description list as a copy of the current one(deprecated).
TDMR_ERROR DMR_CALL	DMR_CopyImageBuffer (const ImageBuffer *pSrc, ImageBuffer **ppDst, int flags)
	Copies the complete data of one ImageBuffer structure into another.
TDMR_ERROR DMR_CALL	DMR_CopyImageRequestBufferDesc (const ImageBuffer *pSrc, ImageBuffer **ppDst, int flags)
	Copies the complete data of one ImageBuffer structure into another.
TDMR_ERROR DMR_CALL	DMR_CreateRequestControl (HDRV hDrv, const char *pName, const char *pParentName, HLIST *pHList, int *pRequestCtrl)
	Creates a new image request control object.
TDMR_ERROR DMR_CALL	DMR_CreateSetting (HDRV hDrv, const char *pName, const char *pParentName, HLIST *pHList)
	Creates a new setting.
TDMR_ERROR DMR_CALL	DMR_CreateUserDataEntry (HDEV hDev, HLIST *pEntry)
	Creates and returns a new entry to store user specific data.
TDMR_ERROR DMR_CALL	DMR_DeleteList (HDRV hDrv, const char *pName, TDMR_ListType type)
	Deletes a list previously created by the user.
TDMR_ERROR DMR_CALL	DMR_DeleteSetting (const char *pName, TStorageLocation location, TScope scope)
	Tries to delete a certain setting.
TDMR_ERROR DMR_CALL	DMR_DeleteUserDataEntry (HDEV hDev, HLIST hEntry)
	Deletes an entry of user specific data.
const char *DMR_CALL	DMR_ErrorCodeToString (int errorCode)
	Returns a string representation of a given error code.
TDMR_ERROR DMR_CALL	DMR_ExportCameraDescription (HDRV hDrv, HLIST hCameraDescList)
	Stores the current camera description on disc(deprecated).
TDMR_ERROR DMR_CALL	DMR_FindList (HDRV hDrv, const char *pName, TDMR_ListType type, unsigned int flags, HLIST *pHList)
	Locates a specified list within the device drivers interface.
TDMR_ERROR DMR_CALL	DMR_GetDevice (HDEV *pHDev, TDMR_DeviceSearchMode searchMode, const char *pSearchString, unsigned int devNr, char wildcard)
	Tries to locate a certain device in the system which matches the input criteria.
TDMR_ERROR DMR_CALL	DMR_GetDeviceCount (unsigned int *pDevCnt)
	Receives the number of devices recognized by this interface.
TDMR_ERROR DMR_CALL	DMR_GetDeviceInfo (unsigned int devNr, TDMR_DeviceInfo *pInfo, size_t infoSize)
	Obtains information about a certain device(deprecated).
TDMR_ERROR DMR_CALL	DMR_GetDeviceInfoEx (HDEV hDev, TDMR_DeviceInfoType infoType, void *pInfo, size_t *pInfoSize)
	Obtains information about a certain device.
TDMR_ERROR DMR_CALL	DMR_GetDeviceWithStringID (HDEV *pHDev, TDMR_DeviceSearchMode searchMode, const char *pSearchString, const char *pStringID, char wildcard)
	Tries to locate a certain device in the system which matches a certain string ID.
TDMR_ERROR DMR_CALL	DMR_GetDriverHandle (HDEV hDev, HDRV *pHDrv)
	Obtains the driver interface handle to a initialised device.
TDMR_ERROR DMR_CALL	DMR_GetImageRequestBuffer (HDRV hDrv, int requestNr, ImageBuffer **ppBuffer)
	Returns the ImageBuffer of the desired request.
TDMR_ERROR DMR_CALL	DMR_GetImageRequestBufferChannelData (HDRV hDrv, int requestNr, int channelNr, int *pChannelOffset, int *pLinePitch, int *pPixelPitch, char *pChannelDesc, size_t channelDescSize)
	Returns information about the channel specific data of the image associated with the desired request.
TDMR_ERROR DMR_CALL	DMR_GetImageRequestBufferData (HDRV hDrv, int requestNr, int *pBytesPerPixel, int *pChannelCount, int *pHeight, int *pWidth, int *pSize, TImageBufferPixelFormat *pPixelFormat, void **ppData)
	Returns information about the image associated with the desired request.
TDMR_ERROR DMR_CALL	DMR_GetImageRequestBufferImageData (HDRV hDrv, int requestNr, int xOff, int yOff, int width, int height, char *pBuf, size_t bufSize)
	Returns an AOI of raw image data belonging to the specified request.
MVDMR_API TDMR_ERROR DMR_CALL	DMR_GetImageRequestInfo (HDRV hDrv, int requestNr, RequestInfo *pInfo)
	Retrieves the RequestInfo of the desired request(deprecated).
TDMR_ERROR DMR_CALL	DMR_GetImageRequestInfoEx (HDRV hDrv, int requestNr, RequestInfo *pInfo, size_t infoSize, int reserved, int reserved2)
	Retrieves the RequestInfo of the desired request.
TDMR_ERROR DMR_CALL	DMR_GetImageRequestParamS (HDRV hDrv, int requestNr, TImageRequestParam param, char *pBuf, size_t bufSize)
	Retrieves a string representation of a request related parameter.
MVDMR_API TDMR_ERROR DMR_CALL	DMR_GetImageRequestResult (HDRV hDrv, int requestNr, RequestResult *pResult)
	Retrieves the RequestResult of the desired request(deprecated).
TDMR_ERROR DMR_CALL	DMR_GetImageRequestResultEx (HDRV hDrv, int requestNr, RequestResult *pResult, size_t resultSize, int reserved, int reserved2)
	Retrieves the RequestResult of the desired request.
MVDMR_API TDMR_ERROR DMR_CALL	DMR_GetImpactRequestBuffer (HDRV hDrv, int requestNr, IPL_BUFHANDLE *pBuffer)
	Returns the IPL_BUFHANDLE of the desired request(deprecated).
TDMR_ERROR DMR_CALL	DMR_GetImpactRequestBufferEx (HDRV hDrv, int requestNr, IPL_BUFHANDLE *pBuffer, TImpactBufferFlag flags, unsigned int)
	Returns the IPL_BUFHANDLE of the desired request.
TDMR_ERROR DMR_CALL	DMR_GetLastError (TDMR_ERROR *pErrorCode, char *pErrorText, size_t *pErrorTextSize)
	Returns the last error code and string that did occur within the current thread.
const char *DMR_CALL	DMR_GetVersion (TLibraryQuery libraryQuery)
	Returns a string containing the version number of the specified library.
TDMR_ERROR DMR_CALL	DMR_ImageRequestConfigure (HDRV hDrv, int requestNr, int reserved, void *pReserved)
	Sets a request into configuration mode.
TDMR_ERROR DMR_CALL	DMR_ImageRequestReset (HDRV hDrv, int requestCtrl, int mode)
	Deletes all requests currently queued for the specified request control.
TDMR_ERROR DMR_CALL	DMR_ImageRequestResultQueueElementCount (HDRV hDrv, int queueNr, int *pResultQueueElements)
	Returns the number of Request objects in the result queue.
TDMR_ERROR DMR_CALL	DMR_ImageRequestSave (HDRV hDrv, int requestNr, const char *pFileName, TImageFileFormat format)
	Stores the image data described by a request into a file.
TDMR_ERROR DMR_CALL	DMR_ImageRequestSaveToVideoStream (HDRV hDrv, int requestNr, HDMR_VIDEO_STREAM hVideoStream)
	Stores the image data described by a request into a video stream.
TDMR_ERROR DMR_CALL	DMR_ImageRequestSingle (HDRV hDrv, int requestCtrl, int *pRequestUsed)
	Sends an image request to the device driver.
TDMR_ERROR DMR_CALL	DMR_ImageRequestUnlock (HDRV hDrv, int requestNr)
	Unlocks the request for the driver again.
TDMR_ERROR DMR_CALL	DMR_ImageRequestWaitFor (HDRV hDrv, int timeout_ms, int queueNr, int *pRequestNr)
	Waits for a request object to become ready.
TDMR_ERROR DMR_CALL	DMR_ImportCameraDescription (HDRV hDrv, HLIST hCameraDescList)
	Updates a camera description with the data stored in a previous session or with the original default data(deprecated).
TDMR_ERROR DMR_CALL	DMR_Init (HDMR *pDevices)
	Initialises the library.
TDMR_ERROR DMR_CALL	DMR_InitVideoStreamAPI (void *pReserved, size_t reserved)
	Initialises the video stream API.
TDMR_ERROR DMR_CALL	DMR_IsSettingAvailable (const char *pName, TStorageLocation storageLocation, TScope scope)
	Checks if a certain setting is available.
TDMR_ERROR DMR_CALL	DMR_IsVideoStreamPaused (HDMR_VIDEO_STREAM hVideoStream)
	Checks is this video stream currently is paused.
TDMR_ERROR DMR_CALL	DMR_LoadImageBuffer (ImageBuffer **ppBuffer, const char *pFileName, TImageFileFormat format)
	Loads an image from a file into a newly allocated image buffer structure.
TDMR_ERROR DMR_CALL	DMR_LoadRTCtrProgram (HDRV hDrv, HLIST hRTCtrList)
	Loads a program from a file into a hardware real-time controller (HRTC)
TDMR_ERROR DMR_CALL	DMR_LoadSetting (HDRV hDrv, const char *pName, TStorageFlag storageFlags, TScope scope)
	Loads a previously stored setting.
TDMR_ERROR DMR_CALL	DMR_LoadSettingFromDefault (HDRV hDrv, TScope)
	Loads the default settings.
TDMR_ERROR DMR_CALL	DMR_OpenDevice (HDEV hDev, HDRV *pHDrv)
	Initialises a device.
TDMR_ERROR DMR_CALL	DMR_OpenVideoStream (const char *pFileName, const unsigned int imageWidth, const unsigned int imageHeight, const TVideoCodec codec, const unsigned int quality_pc, const unsigned int bitrate, HDMR_VIDEO_STREAM *pHVideoStream)
	Creates a new video stream.
TDMR_ERROR DMR_CALL	DMR_PauseVideoStream (HDMR_VIDEO_STREAM hVideoStream)
	Pauses a video stream.
TDMR_ERROR DMR_CALL	DMR_ReleaseImageBuffer (ImageBuffer **ppBuffer)
	frees the memory previously allocated for the specified ImageBuffer structure again.
TDMR_ERROR DMR_CALL	DMR_ReleaseImageRequestBufferDesc (ImageBuffer **ppBuffer)
	frees the memory previously allocated for the specified ImageBuffer structure again.
TDMR_ERROR DMR_CALL	DMR_ResumeVideoStream (HDMR_VIDEO_STREAM hVideoStream)
	Resumes a video stream.
TDMR_ERROR DMR_CALL	DMR_SaveImageBuffer (const ImageBuffer *pBuffer, const char *pFileName, TImageFileFormat format)
	Stores the complete data of one ImageBuffer structure into a file.
TDMR_ERROR DMR_CALL	DMR_SaveImageBufferToVideoStream (HDMR_VIDEO_STREAM hVideoStream, const ImageBuffer *pBuffer, const int64_type timestamp_us)
	Stores an image into a video stream.
TDMR_ERROR DMR_CALL	DMR_SaveRTCtrProgram (HDRV hDrv, HLIST hRTCtrList)
	Stores the current program of a hardware real-time controller (HRTC) into a file.
TDMR_ERROR DMR_CALL	DMR_SaveSetting (HDRV hDrv, const char *pName, TStorageFlag storageFlags, TScope scope)
	Stores the current settings.
TDMR_ERROR DMR_CALL	DMR_SaveSettingToDefault (HDRV hDrv, TScope scope)
	Stores the current settings under a default location.
TDMR_ERROR DMR_CALL	DMR_SetDeviceID (HDEV hDev, int newID)
	Assigns a new ID to this device.
TDMR_ERROR DMR_CALL	DMR_SetImageRequestBufferImageData (HDRV hDrv, int requestNr, int xOff, int yOff, int width, int height, char *pBuf, size_t)
	Sets an AOI of raw image data belonging to the specified request.
TDMR_ERROR DMR_CALL	DMR_UpdateDeviceList (unsigned int reserved, int reserved2)
	Updates the internal device list.
TDMR_ERROR DMR_CALL	DMR_UpdateDigitalInputs (HDRV hDrv)
	Updates the property representation of the digital inputs by checking the physical device's inputs.
TDMR_ERROR DMR_CALL	DMR_UpdateFirmware (HDEV hDev)
	Updates the firmware of the device.
TDMR_ERROR DMR_CALL	DMR_WriteUserDataToHardware (HDEV hDev)
	Writes the current set of user data into the devices non-volatile memory.

Detailed Description

Functions for accessing device and memory (especially image specific/captured data) functionality.

Function Documentation

DMR_AcquisitionStart()

TDMR_ERROR DMR_CALL DMR_AcquisitionStart

(

HDRV

hDrv

)

Manually starts the acquisition engine of this device driver instance.

Calling this function will manually start this device drivers acquisition engine. This will only have effect on the overall behaviour, if the property acquisitionStartStopBehaviour is set to assbUser.

If supported by the device driver starting and stopping the acquisition engine manually can sometimes help to overcome capture queue under-runs or certain restrictions in the underlying device driver technology.

See also

DMR_AcquisitionStop(),
DMR_ImageRequestSingle(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestReset()

Since

1.12.11

Returns

• DMR_NO_ERROR if successful.
• DMR_FEATURE_NOT_AVAILABLE if this device/driver combination does not support manual control over the acquisition engine. This will also happen if the acquisitionStartStopBehaviour property is NOT set to assbUser.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hDrv

A handle to the device drivers interface.

DMR_AcquisitionStop()

TDMR_ERROR DMR_CALL DMR_AcquisitionStop

(

HDRV

hDrv

)

Manually stops the acquisition engine of this device driver instance.

Calling this function will manually stop this device drivers acquisition engine. This will only have effect on the overall behaviour, if the property acquisitionStartStopBehaviour is set to assbUser.

See also

DMR_AcquisitionStop(),
DMR_ImageRequestSingle(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestReset()

Since

1.12.11

Returns

• DMR_NO_ERROR if successful.
• DMR_FEATURE_NOT_AVAILABLE if this device/driver combination does not support manual control over the acquisition engine. This will also happen if the acquisitionStartStopBehaviour property is NOT set to assbUser.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hDrv

A handle to the device drivers interface.

DMR_AllocImageBuffer()

TDMR_ERROR DMR_CALL DMR_AllocImageBuffer	(	ImageBuffer **	ppBuffer,
		TImageBufferPixelFormat	pixelFormat,
		int	width,
		int	height )

Allocates memory for a new ImageBuffer structure and the associated pixel memory.

If ppBuffer points to a structure previously allocated by any other function, this memory will be lost(memory leak). In that case DMR_ReleaseImageRequestBufferDesc() (if the structure has been allocated with DMR_AllocImageRequestBufferDesc() or DMR_GetImageRequestBuffer()) or DMR_ReleaseImageBuffer()(if the structure has been allocated with DMR_AllocImageBuffer()) should be called before.

This function will allocate memory for the pixel data pointed to by ImageBuffer::vpData and also will fill the structure with channel specific data derived from the pixel format specified by the user. If this is NOT desired the function DMR_AllocImageRequestBufferDesc() should be used instead.

This function will call DMR_AllocImageRequestBufferDesc(), so everything described in that functions description will be valid for this call as well.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageBuffer() as otherwise the result will either be a corrupted heap or a memory leak!

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_AllocImageRequestBufferDesc(),
DMR_GetImageRequestBuffer(),
DMR_CopyImageBuffer(),
DMR_CopyImageRequestBufferDesc()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	ppBuffer	A pointer to a pointer receiving the address of the allocated structure on a successful call to this function.
[in]	pixelFormat	The pixel format of the buffer that shall be allocated. This will influence the amount of memory and the channel specific data that will be created. E.g. if an RGB format is selected the channel descriptor entries will contain 'R', 'G', and 'B' after a successful call to this function.
[in]	width	The width of the buffer that shall be allocated.
[in]	height	The height of the buffer that shall be allocated.

DMR_AllocImageRequestBufferDesc()

TDMR_ERROR DMR_CALL DMR_AllocImageRequestBufferDesc	(	ImageBuffer **	ppBuffer,
		int	channelCount )

Allocates memory for a new ImageBuffer structure.

If ppBuffer points to a structure previously allocated by any other function, this memory will be lost(memory leak). In that case DMR_ReleaseImageRequestBufferDesc() (if the structure has been allocated with DMR_AllocImageRequestBufferDesc()) or DMR_ReleaseImageBuffer()(if the structure has been allocated with DMR_AllocImageBuffer())should be called before.

This function will NOT allocate memory for the pixel data pointed to by ImageBuffer::vpData and also will NOT fill the structure with channel specific data. If this is desired the function DMR_AllocImageBuffer() should be used instead.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageRequestBufferDesc() as otherwise the result will either be a corrupted heap or a memory leak!

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_GetImageRequestBuffer(),
DMR_CopyImageBuffer(),
DMR_AllocImageBuffer(),
DMR_CopyImageRequestBufferDesc()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	ppBuffer	A pointer to a pointer receiving the address of the allocated structure on a successful call to this function.
[in]	channelCount	The number of elements to allocate for channel specific data.

DMR_BuildImpactImage()

TDMR_ERROR DMR_CALL DMR_BuildImpactImage	(	const ImageBuffer *	pBuffer,
		IPL_BUFHANDLE *	pBufHandle,
		TImpactBufferFlag	flags,
		void *	pReserved,
		size_t	reservedSize )

Converts an image from the drivers internal format into the mvIMPACT processing libraries format.

This function will convert an image obtained from a device driver or any other image into an image that can be passed to any image processing function of the mvIMPACT processing library.

Note

If *pBuffer equals IPL_DONT_CARE new memory will be allocated for the resulting image.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function IPL_BufFree() as otherwise the result will either be a corrupted heap or a memory leak!

Note

When working with RGB data the destination format idpfRGB888Planar should be used for performance reasons as then less copy work has to be performed.

See also

IPL_BufFree()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise. In case of an error you still might need to call IPL_BufFree() in order to avoid resource leaks (e.g. if you've already passed a valid buffer handle to the function). You always have to free this buffer, if *pBuffer is not equal to IPL_DONT_CARE AFTER the call.

Parameters

[in]	pBuffer	A const pointer to the image buffer that shall be converted
[out]	pBufHandle	A pointer to a variable retrieving the data of the desired requests image buffer. The handle might be set to IPL_DONT_CARE if a new buffer shall be allocated.
[in]	flags	Flags to define the behaviour of this function.
[in]	pReserved	Reserved. Must be 0!
[in]	reservedSize	Reserved. Must be 0!

DMR_Close()

TDMR_ERROR DMR_CALL DMR_Close

(

void

)

Frees internal data structures and decreases the usage counter for this library.

This function frees memory previously allocated by DMR_Init( HDMR* pHDmr ) and decrements the internal usage counter. For each call to DMR_Init( HDMR* pHDmr ) the user must call this function once before unloading the library from process memory again as otherwise resource leaks and other problems may arise.

When the internal reference counter indicates, that the library is not needed anymore the device manager automatically closes all devices which still might be open.

Attention

NEVER call this function from the DllMain context (Windows)! See DMR_Init( HDMR* pHDmr ) for additional details.

See also

DMR_Init( HDMR* pHDmr )

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

DMR_CloseDevice()

TDMR_ERROR DMR_CALL DMR_CloseDevice	(	HDRV	hDrv,
		HDEV	hDev )

Closes a device.

This function will try to close a device previously initialised by a call to DMR_OpenDevice() and associated with hDev and hDrv. Once this function has been called, every device driver object handle (HOBJ, HLIST) for this device will become invalid.

See also

DMR_OpenDevice(),
DMR_GetDevice(),
DMR_GetDriverHandle(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hDev	A handle to the device.

DMR_CloseVideoStream()

TDMR_ERROR DMR_CALL DMR_CloseVideoStream

(

HDMR_VIDEO_STREAM

hVideoStream

)

Closes a video stream and frees resources.

Frees all resources allocated previously through a call to DMR_OpenVideoStream() and closes the associated file.

Since

2.39.0

See also

DMR_OpenVideoStream(),
DMR_PauseVideoStream(),
DMR_IsVideoStreamPaused(),
DMR_ResumeVideoStream(),
DMR_ImageRequestSaveToVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_INVALID_PARAMETER if hVideoStream refers to an invalid handle.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hVideoStream

The handle for the stream to close as obtained from a previous call to DMR_OpenVideoStream().

DMR_CopyCameraDescription()

TDMR_ERROR DMR_CALL DMR_CopyCameraDescription	(	HDRV	hDrv,
		HLIST	hCameraDescList,
		const char *	pNewName )

Creates a new camera description list as a copy of the current one(deprecated).

Deprecated

There is NO direct replacement for this function! Support for frame grabber boards has ended years ago. Simply remove all references to these functions and adjust your code to continue to work without them or stick to older releases of this SDK.

This function can be used to create a new camera description list. It will create a deep copy of the list referenced by hCameraDescList and will append it to the list of camera descriptions.

Note

This will NOT store the new description permanently. After the driver has been closed, this data will be lost. To store the new list in a way, that it will be available the next time the driver/device is opened again DMR_ExportCameraDescription() must be called with the handle of the newly created description after this function.

See also

DMR_ImportCameraDescription(),
DMR_ExportCameraDescription()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hCameraDescList	A handle to the camera description list returned from a previous call to DMR_FindList() and one or more of the iterator functions OBJ_GetFirstSibling(), OBJ_GetNextSibling() and OBJ_GetFirstChild().
[in]	pNewName	A constant pointer to a C-string containing the name of the new camera description.

DMR_CopyImageBuffer()

TDMR_ERROR DMR_CALL DMR_CopyImageBuffer	(	const ImageBuffer *	pSrc,
		ImageBuffer **	ppDst,
		int	flags )

Copies the complete data of one ImageBuffer structure into another.

This function copies the image describing structure of one ImageBuffer structure into another. A deep copy is made including the complete pixel data!

Note

If *ppDst equals NULL new memory will be allocated for the ImageBuffer structure.

If *ppDst does not equal NULL and also does not point to a valid ImageBuffer structure this function will crash!

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageBuffer() as otherwise the result will either be a corrupted heap or a memory leak!

Always use the function DMR_AllocImageBuffer() or DMR_AllocImageRequestBufferDesc() to allocate memory for the ImageBuffer structure as otherwise the result may either be a memory leak or undefined behaviour. The reason for this is, that this function might try to free and reallocate memory for ImageBuffer::pChannels, which can't be done across library boundaries.

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_GetImageRequestBuffer(),
DMR_CopyImageRequestBufferDesc(),
DMR_AllocImageRequestBufferDesc(),
DMR_AllocImageBuffer()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	pSrc	A pointer to an ImageBuffer structure to be copied.
[out]	ppDst	A pointer to a pointer to a structure receiving the data stored in pSrc.
[in]	flags	Currently unsupported. MUST be set 0.

DMR_CopyImageRequestBufferDesc()

TDMR_ERROR DMR_CALL DMR_CopyImageRequestBufferDesc	(	const ImageBuffer *	pSrc,
		ImageBuffer **	ppDst,
		int	flags )

Copies the complete data of one ImageBuffer structure into another.

This function copies the image describing structure of one ImageBuffer structure into another. A swallow copy is made! Just the pointer to the image data (ImageBuffer::vpData) is copied, but NOT the data pointed to.

Note

If *ppDst equals NULL new memory will be allocated for the ImageBuffer structure.

If *ppDst does not equal NULL and also does not point to a valid ImageBuffer structure this function will crash!

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageRequestBufferDesc() as otherwise the result will either be a corrupted heap or a memory leak!

Note

Always use the function DMR_AllocImageRequestBufferDesc() to allocate memory for the ImageBuffer structure as otherwise the result may either be a memory leak or undefined behaviour. The reason for this is, that this function might try to free and reallocate memory for ImageBuffer::pChannels, which can't be done across library boundaries.

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_GetImageRequestBuffer(),
DMR_CopyImageBuffer(),
DMR_AllocImageRequestBufferDesc(),
DMR_AllocImageBuffer()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	pSrc	A pointer to an ImageBuffer structure to be copied.
[out]	ppDst	A pointer to a pointer to a structure receiving the data stored in pSrc.
[in]	flags	Currently unsupported. MUST be set 0.

DMR_CreateRequestControl()

TDMR_ERROR DMR_CALL DMR_CreateRequestControl	(	HDRV	hDrv,
		const char *	pName,
		const char *	pParentName,
		HLIST *	pHList,
		int *	pRequestCtrl )

Creates a new image request control object.

This function creates a new request control based on an existing one. New request controls can only be derived from request controls that already exist. When the driver has been initialised there will at least be one base request control called 'Base', which acts as the base for all other request controls.

All request control constructed by the application must be derived either from this base or any of its children.

Note

See all comments made under DMR_CreateSetting() for understanding the relationship between base and derived request control objects.

See also

DMR_FindList(),
DMR_DeleteList(),
DMR_CreateSetting()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	pName	The name of the new request control to create.
[in]	pParentName	The name of the request control to derive the new request control from.
[out]	pHList	A pointer to the HLIST variable to receive the new list on a successful function call. This my be 0 if the caller is not interested in this value.
[out]	pRequestCtrl	A pointer to the variable the receives the number of the new request control on a successful call. This parameter is currently NOT implemented and therefore will NOT be modified by this function.

DMR_CreateSetting()

TDMR_ERROR DMR_CALL DMR_CreateSetting	(	HDRV	hDrv,
		const char *	pName,
		const char *	pParentName,
		HLIST *	pHList )

Creates a new setting.

This function creates a new setting based on an existing one. New settings can only be derived from settings that already exist. When the driver has been initialised there will at least be one base setting called 'Base', which acts as the base for all other settings.

When a new setting is created it derives all the properties from the parent setting. That means initially the new setting will contain the very same data as the parent setting. As long as a component hasn't been modified in the new setting it will depend on the parent settings data. That means if e.g. a property in the parent list is modified, the newly created setting will also benefit from the updated value.

To release a certain component from this dependency it must be assigned a new value. The function OBJ_IsDefault() will return false afterwards indicating, that the component no longer depends on the parent.

To restore this parent <-> child dependency the user can call the function OBJ_RestoreDefault() for the object in question. Afterwards settings applied to the parent component will also be visible in the child component again.

When a new setting has been created successfully it can be accessed anywhere in the program by calling the function DMR_FindList().

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	pName	The name of the new setting to create.
[in]	pParentName	The name of the setting to derive the new setting from.
[out]	pHList	A pointer to the HLIST variable to receive the new list on a successful function call. This my be 0 if the caller is not interested in this value.

DMR_CreateUserDataEntry()

TDMR_ERROR DMR_CALL DMR_CreateUserDataEntry	(	HDEV	hDev,
		HLIST *	pEntry )

Creates and returns a new entry to store user specific data.

Note

The data handled by this object will not be stored permanently in the devices non-volatile memory until DMR_WriteUserDataToHardware() has been called successfully.

See also

DMR_DeleteUserDataEntry(),
DMR_WriteUserDataToHardware()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	A handle to the device.
[out]	pEntry	A pointer to the variable receiving the handle to the new user data entry on a successful call.

DMR_DeleteList()

TDMR_ERROR DMR_CALL DMR_DeleteList	(	HDRV	hDrv,
		const char *	pName,
		TDMR_ListType	type )

Deletes a list previously created by the user.

This function deletes a list previously created by the user due to a call to DMR_CreateSetting() or DMR_CreateRequestControl().

Note

Only lists created by the user can be deleted by the user again so currently this function only supports dmltSetting and dmltRequestCtrl as valid values for type.

See also

DMR_FindList(),
DMR_CreateSetting(),
DMR_CreateRequestControl()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	pName	A pointer to the name of the list to delete.
[in]	type	The type of list to be deleted.

DMR_DeleteSetting()

TDMR_ERROR DMR_CALL DMR_DeleteSetting	(	const char *	pName,
		TStorageLocation	location,
		TScope	scope )

Tries to delete a certain setting.

Since

2.19.0 Please note that certain user privileges might be required to delete a global setting.

Returns

• PROPHANDLING_NO_ERROR if the setting could be deleted.
• A negative error code of type TPROPHANDLING_ERROR otherwise.

Parameters

[in]	pName	The name of the setting to look for.
[in]	location	The storage location where to look for this setting.
[in]	scope	Specifies where to look for the setting when storageLocation is set to slNative or slNative_Raw under Windows© as then the Registry will be used.

DMR_DeleteUserDataEntry()

TDMR_ERROR DMR_CALL DMR_DeleteUserDataEntry	(	HDEV	hDev,
		HLIST	hEntry )

Deletes an entry of user specific data.

If the entry has been stored to the non-volatile memory already and has been assigned the udarPassword flag, this call will fail, when the property password belonging to that entry does not contain the correct password.

Note

The data handled by this object will not be removed permanently from the devices non-volatile memory until DMR_WriteUserDataToHardware() has been called successfully.

See also

DMR_CreateUserDataEntry(),
DMR_WriteUserDataToHardware()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	A handle to the device.
[in]	hEntry	The handle to the user data entry that shall be deleted.

DMR_ErrorCodeToString()

const char *DMR_CALL DMR_ErrorCodeToString

(

int

errorCode

)

Returns a string representation of a given error code.

This function returns a string representation for the error code passed to the function.

Returns

A pointer to the corresponding error string.

Parameters

errorCode

The error code whose string representation shall be returned. This can either be a TDMR_ERROR or a TPROPHANDLING_ERROR error code value.

DMR_ExportCameraDescription()

TDMR_ERROR DMR_CALL DMR_ExportCameraDescription	(	HDRV	hDrv,
		HLIST	hCameraDescList )

Stores the current camera description on disc(deprecated).

Deprecated

There is NO direct replacement for this function! Support for frame grabber boards has ended years ago. Simply remove all references to these functions and adjust your code to continue to work without them or stick to older releases of this SDK.

This function can be used to store the current settings of a camera description permanently so that the next time the driver is initialised these settings are restored.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hCameraDescList	A handle to the camera description list returned from a previous call to DMR_FindList() and one or more of the iterator functions OBJ_GetFirstSibling(), OBJ_GetNextSibling() and OBJ_GetFirstChild().

DMR_FindList()

TDMR_ERROR DMR_CALL DMR_FindList	(	HDRV	hDrv,
		const char *	pName,
		TDMR_ListType	type,
		unsigned int	flags,
		HLIST *	pHList )

Locates a specified list within the device drivers interface.

This function tries to locate a certain list of device properties within the device driver interface.

Once a list has been located successfully the properties contained in that list can be accessed via the function OBJ_GetHandle().

EXAMPLE:

//-----------------------------------------------------------------------------
void fn( HDrv hDriverInterface )
//-----------------------------------------------------------------------------
{
  TPROPHANDLING_ERROR objResult;
  TDMR_ERROR dmrResult;
  HOBJ hProp;
  HLIST baseList;
  double fps;
 
  // try to locate the list for statistical information
  if( ( dmrResult = DMR_FindList( hDriverInterface, 0, dmltStatistics, 0, &baseList ) ) == DMR_NO_ERROR )
  {
    // try to locate the property containing the frames per second
    if( ( objResult = OBJ_GetHandle( baseList, "FramesPerSecond", &hProp ) ) == PROPHANDLING_NO_ERROR )
    {
      // read the properties value
      OBJ_GetF( hProp, &fps, 0 );
      printf( "frames per second: %.5f\n", fps );
    }
    else
    {
      printf( "OBJ_GetHandle failed: %d ID: %d\n", objResult, hProp );
    }
  }
  else
  {
    printf( "DMR_FindList failed: %d\n", dmrResult );
  }
}

Apart from that this function can also be used to locate lists previously created by the user. This e.g. might be a new setting. In that case pName should contain the name of the previously created setting.

EXAMPLE:

//-----------------------------------------------------------------------------
void fn( HDRV hDrv )
//-----------------------------------------------------------------------------
{
  HLIST hList;
  DMR_CreateSetting( hDrv, "MySetting", "Base", &hList );
}
 
//-----------------------------------------------------------------------------
void fn2( HDRV hDrv )
//-----------------------------------------------------------------------------
{
  HLIST hMySetting;
  fn(hDrv);
  DMR_FindList( hDrv, "MySetting", dmltSetting, 0, &hMySetting );
  // do something with the setting
}

For hardware real-time controller (HRTC) lists the parameter flags can be used to specify which HRTCs list to locate.

The following code will locate every HRTC for a certain device:

//-----------------------------------------------------------------------------
void fn( HDRV hDrv )
//-----------------------------------------------------------------------------
{
  // register all real time control machines if available
  unsigned int cnt=0;
  HLIST hList;
  while( ( result = DMR_FindList( hDrv, 0, dmltRTCtr, cnt, &hList ) ) == DMR_NO_ERROR )
  {
    registerRTCtrProgram( hDrv, hList ); // this function might do some registration work for the user
    ++cnt;
  }
}

See also

DMR_DeleteList(),
DMR_CreateSetting(),
DMR_CreateRequestControl()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface. When looking for dmltDeviceDriverLib this parameter is ignored.
[in]	pName	A pointer to a string containing the exact name of the list to be found if there is more than one of the same type/name. Otherwise pName can be NULL.
[in]	type	The type of list to look for.
[in]	flags	Flags to define how to search for certain list types
[in]	pHList	A pointer to the HLIST variable to receive the located list on a successful function call.

DMR_GetDevice()

TDMR_ERROR DMR_CALL DMR_GetDevice	(	HDEV *	pHDev,
		TDMR_DeviceSearchMode	searchMode,
		const char *	pSearchString,
		unsigned int	devNr,
		char	wildcard )

Tries to locate a certain device in the system which matches the input criteria.

This function can be used to locate devices, which obey to criteria passed to the function.

EXAMPLES:

Consider three devices of sample device as installed in the current system. Their serial number may be 'SD00000001',
'SD00000002' and 'SD00000003', two devices are for grey video sources (product string 'SampleDevice-G),
one for color source (product string 'SampleDevice-C'). Each device has been assigned a unique ID,
which is stored in the devices internal memory.

Serial	Product string	device ID	Family string
SD00000001	SampleDevice-G	3	SampleDevice
SD00000002	SampleDevice-C	66	SampleDevice
SD00000003	SampleDevice-G	2	SampleDevice

HDEV hDev;
// this will find the first device whose serial number starts with 'SD0000' in the
// system(device SD00000001).
DMR_GetDevice( &hDev, dmdsmSerial, "SD0000*", 0, '*' );
// this will find the third device whose serial number starts with 'SD0000' in the
// system(device SD00000003).
DMR_GetDevice( &hDev, dmdsmSerial, "SD0000*", 2, '*' );
// this will find the device whose serial number starts with 'SD0000' in the system
// which has a device ID of 2 stored in the device specifics internal
// memory(device SD00000003).
DMR_GetDevice( &hDev, (TDMR_DeviceSearchMode)(dmdsmSerial | dmdsmUseDevID), "SD0000*", 2, '*' );
// this will find the first device whose product string is 'SampleDevice-G' in the
// system(device SD00000001).
DMR_GetDevice( &hDev, dmdsmProduct, "SampleDevice-G", 0, '*' );

Precondition

Before this function can be used DMR_Init( HDMR* pHDmr ) must have been called successfully.

See also

DMR_GetDeviceWithStringID(),
DMR_Init(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	pHDev	A pointer to a variable that receives the handle to the located device on a successful call
[in]	searchMode	Defines how to search for the device
[in]	pSearchString	A pointer to a string containing information about the device to search
[in]	devNr	Either the number of the device to return or the unique device ID stored in the device specific memory. If dmdsmUseDevID is specified, this parameter will be interpreted as the latter one.
[in]	wildcard	A wild-card character which can be used to mark certain parts of pSearchString as 'to be ignored'.

DMR_GetDeviceCount()

TDMR_ERROR DMR_CALL DMR_GetDeviceCount

(

unsigned int *

pDevCnt

)

Receives the number of devices recognized by this interface.

This function returns the number of devices currently recognized by this interface and detected in the current system.

See also

DMR_GetDevice(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]

pDevCnt

A pointer to a variable that receives the number of recognized devices.

DMR_GetDeviceInfo()

TDMR_ERROR DMR_CALL DMR_GetDeviceInfo	(	unsigned int	devNr,
		TDMR_DeviceInfo *	pInfo,
		size_t	infoSize )

Obtains information about a certain device(deprecated).

This function will fill the members of the structure TDMR_DeviceInfo with information about the device.

Deprecated

This function has been declared deprecated. Use DMR_GetDeviceInfoEx() instead.

See also

DMR_Init(),
DMR_GetDevice(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	devNr	The number of the device from which to receive the information.
[out]	pInfo	A pointer to a structure receiving the information on a successful call.
[in]	infoSize	The size of the structure pointed to by pInfo receiving the information.

DMR_GetDeviceInfoEx()

TDMR_ERROR DMR_CALL DMR_GetDeviceInfoEx	(	HDEV	hDev,
		TDMR_DeviceInfoType	infoType,
		void *	pInfo,
		size_t *	pInfoSize )

Obtains information about a certain device.

This function will return various device specific information.

See also

TDMR_DeviceInfoType,
DMR_Init(),
DMR_GetDevice(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Since

1.12.42

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	A handle to the device.
[in]	infoType	The information that shall be queried.
[out]	pInfo	A pointer to a buffer receiving the information on a successful call. This can be NULL in order to query the size of this buffer only but since each infoType has a dedicated data type documented as part of it's description this usually should not be necessary.
[in,out]	pInfoSize	The size of the buffer pointed to by pInfo. This variable will receive the needed buffer size needed for pInfo, if pInfo is 0 allowing to call this function twice: Once to query the needed buffer size for the requested information and then a second time after allocating a sufficient amount of memory for pInfo.

DMR_GetDeviceWithStringID()

TDMR_ERROR DMR_CALL DMR_GetDeviceWithStringID	(	HDEV *	pHDev,
		TDMR_DeviceSearchMode	searchMode,
		const char *	pSearchString,
		const char *	pStringID,
		char	wildcard )

Tries to locate a certain device in the system which matches a certain string ID.

This function can be used to locate devices with a certain string identifier that has previously been written into a devices non-volatile memory. E.g. GenICam devices may support the DeviceUserID feature to assign a certain user defined name. A user defined name might be useful e.g. to access a device with a certain function without the need to worry about which device is it. You could e.g. have a barcodeReadingDevice and a monitorCamera. This functions is similar to the DMR_GetDevice() function in every way, except that the DeviceID parameter is a const char* instead of an unsigned int.

Precondition

Before this function can be used DMR_Init( HDMR* pHDmr ) must have been called successfully.

The following line of code will try to locate a device who's product string starts with mvBlueCOUGAR-X, might contain additional characters afterwards and has a user assigned string identifier of exactly Camera1.

DMR_GetDeviceWithStringID( &hDevice, ( TDMR_DeviceSearchMode )( dmdsmProduct | dmdsmUseDevID ), "mvBlueCOUGAR-X*", "Camera1", '*' );

See also

DMR_GetDevice(),
DMR_Init(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	pHDev	A pointer to a variable that receives the handle to the located device on a successful call
[in]	searchMode	Defines how to search for the device. dmdsmUseDevID MUST be specified, otherwise DMR_INVALID_PARAMETER will be returned.
[in]	pSearchString	A pointer to a string containing information about the device to search
[in]	pStringID	A pointer to a string containing the string ID of the device to return.
[in]	wildcard	A wild-card character which can be used to mark certain parts of pSearchString as 'to be ignored'.

DMR_GetDriverHandle()

TDMR_ERROR DMR_CALL DMR_GetDriverHandle	(	HDEV	hDev,
		HDRV *	pHDrv )

Obtains the driver interface handle to a initialised device.

The function can be used to check if a certain device is currently open in the current process or not. If the device has already been opened in the current process, the function will obtain a valid handle to the devices driver interface.

See also

DMR_Init(),
DMR_GetDevice(),
DMR_OpenDevice(),
DMR_CloseDevice(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	A handle to the device.
[out]	pHDrv	A pointer to a variable that receives the handle to the devices driver interface if the device is currently open. If the device handle hDev is valid, but the device is currently not in use, this variable will be set to INVALID_ID.

DMR_GetImageRequestBuffer()

TDMR_ERROR DMR_CALL DMR_GetImageRequestBuffer	(	HDRV	hDrv,
		int	requestNr,
		ImageBuffer **	ppBuffer )

Returns the ImageBuffer of the desired request.

This function returns the current image describing structure for the desired request. Always call this function to receive the correct data for the desired request and do not work with references to old structures, as the structure returned will be a copy of the structure currently describing the image buffer and NOT the address to the internal driver structure.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

If *ppBuffer equals NULL new memory will be allocated for the ImageBuffer structure. This memory then MUST be freed using DMR_ReleaseImageRequestBufferDesc() when no longer needed.

If *ppBuffer does not equal NULL and also does not point to a valid ImageBuffer structure this function will crash!

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageRequestBufferDesc() as otherwise the result will either be a corrupted heap or a memory leak!

Note

Always use the function DMR_AllocImageRequestBufferDesc() to allocate memory for the ImageBuffer structure as otherwise the result may either be a memory leak or undefined behaviour. The reason for this is, that this function might try to free and reallocate memory for ImageBuffer::pChannels, which can't be done across library boundaries.

EXAMPLES:

version passing '0' to the first call of DMR_GetImageRequestBuffer

//-----------------------------------------------------------------------------
unsigned int __stdcall liveThread( void* pData )
//-----------------------------------------------------------------------------
{
  HDRV          hDriverInterface;
  TDMR_ERROR    result;
  ImageBuffer*  pIB;
  RequestResult ReqRes;
  int           frameCount;
  int           requestNr;
 
  hDriverInterface = ((ThreadParameter*)pData)->hDriverInterface;
  pIB = 0;
 
  // pre-fill the default capture queue
  while( ( result = DMR_ImageRequestSingle( hDrv, 0, 0 ) ) == DMR_NO_ERROR );
  if( result != DEV_NO_FREE_REQUEST_AVAILABLE )
  {
    printf( "DMR_ImageRequestSingle: Unexpected error(code: %d(%s))\n", result, DMR_ErrorCodeToString( result ) );
  }
 
  // run thread loop
  while( !s_boTerminated )
  {
    result = DMR_ImageRequestWaitFor( hDriverInterface, 500, 0, &requestNr );
    if( result == DMR_NO_ERROR )
    {
      // check if the request contains a valid image
      result = DMR_GetImageRequestResult( hDriverInterface, requestNr, &ReqRes );
      if( ( result == DMR_NO_ERROR ) && ( ReqRes.result == rrOK ) )
      {
        if( ( result = DMR_GetImageRequestBuffer( hDriverInterface, requestNr, &pIB ) ) == DMR_NO_ERROR )
        {
          // display the captured image or do whatever is necessary
        }
        else
        {
          /// ...
        }
      }
      else
      {
        // ...
      }
      DMR_ImageRequestUnlock( hDriverInterface, requestNr );
      DMR_ImageRequestSingle( hDriverInterface, 0, 0 );
    }
    else
    {
      // ...
    }
  }
 
  // free resources
  printf( "DMR_ImageRequestReset: %d\n", DMR_ImageRequestReset( hDriverInterface, 0, 0 ) );
  printf( "DMR_ReleaseImageRequestBufferDesc: %d\n", DMR_ReleaseImageRequestBufferDesc( &pIB ) );
  return 0;
}

version calling DMR_AllocImageRequestBufferDesc() before:

//-----------------------------------------------------------------------------
unsigned int __stdcall liveThread( void* pData )
//-----------------------------------------------------------------------------
{
  HDRV          hDriverInterface;
  TDMR_ERROR    result;
  ImageBuffer*  pIB;
  RequestResult ReqRes;
  int           frameCount;
  int           requestNr;
 
  hDriverInterface = ((ThreadParameter*)pData)->hDriverInterface;
  pIB = 0;
  DMR_AllocImageRequestBufferDesc( &pIB, 1 ); // one channel -> default
 
  // pre-fill the default capture queue
  while( ( result = DMR_ImageRequestSingle( hDrv, 0, 0 ) ) == DMR_NO_ERROR );
  if( result != DEV_NO_FREE_REQUEST_AVAILABLE )
  {
    printf( "DMR_ImageRequestSingle: Unexpected error(code: %d(%s))\n", result, DMR_ErrorCodeToString( result ) );
  }
 
  // run thread loop
  while( !s_boTerminated )
  {
    result = DMR_ImageRequestWaitFor( hDriverInterface, 500, 0, &requestNr );
    if( result == DMR_NO_ERROR )
    {
      // check if the request contains a valid image
      result = DMR_GetImageRequestResult( hDriverInterface, requestNr, &ReqRes );
      if( ( result == DMR_NO_ERROR ) && ( ReqRes.result == rrOK ) )
      {
        if( ( result = DMR_GetImageRequestBuffer( hDriverInterface, requestNr, &pIB ) ) == DMR_NO_ERROR )
        {
          // display the captured image or do whatever is necessary
        }
        else
        {
          /// ...
        }
      }
      else
      {
        // ...
      }
      DMR_ImageRequestUnlock( hDriverInterface, requestNr );
      DMR_ImageRequestSingle( hDriverInterface, 0, 0 );
    }
    else
    {
      // ...
    }
  }
 
  // free resources
  printf( "DMR_ImageRequestReset: %d\n", DMR_ImageRequestReset( hDriverInterface, 0, 0 ) );
  printf( "DMR_ReleaseImageRequestBufferDesc: %d\n", DMR_ReleaseImageRequestBufferDesc( &pIB ) );
  return 0;
}

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_CopyImageRequestBufferDesc(),
DMR_CopyImageRequestBufferDesc(),
DMR_AllocImageBuffer(),
DMR_AllocImageRequestBufferDesc()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	ppBuffer	A pointer to a pointer retrieving the data of the desired requests image buffer or a pointer to NULL if a new ImageBuffer structure shall be allocated. The memory should be allocated by the function DMR_AllocImageRequestBufferDesc() and NOT as a stack variable as this otherwise might result in memory leaks.

DMR_GetImageRequestBufferChannelData()

TDMR_ERROR DMR_CALL DMR_GetImageRequestBufferChannelData	(	HDRV	hDrv,
		int	requestNr,
		int	channelNr,
		int *	pChannelOffset,
		int *	pLinePitch,
		int *	pPixelPitch,
		char *	pChannelDesc,
		size_t	channelDescSize )

Returns information about the channel specific data of the image associated with the desired request.

Note

This function should only be used when working with programming languages, that do not support function calls with pointers to pointers to structures like e.g. Visual Basic. Other users should call the function DMR_GetImageRequestBuffer() instead, as it is more efficient as it combines the work performed by this function and one or more calls to the function DMR_GetImageRequestBufferChannelData().

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

The function checks each pointer passed to it and only fills out the parameters with valid pointers, so if one or more values are not required you can pass '0' instead.

Always call this function to receive the up to date data for the current request and do NOT use this data for any other request!

See also

DMR_GetImageRequestBuffer(),
DMR_GetImageRequestBufferData()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	channelNr	The number of the channel of the requests image buffer from which to read the parameters.
[out]	pChannelOffset	A pointer to the variable receiving offset in bytes of this channel with respect to ppData returned by DMR_GetImageRequestBufferData(). This can be 0 if the value is not needed.
[out]	pLinePitch	A pointer to the variable receiving line pitch of this channel. This can be 0 if the value is not needed.
[out]	pPixelPitch	A pointer to the variable receiving pixel pitch of this channel. This can be 0 if the value is not needed.
[out]	pChannelDesc	A pointer to a user supplied string buffer receiving the channel specific descriptor of this channel./ This can be 0 if the value is not needed.
[in]	channelDescSize	The size in bytes of the user supplied string buffer for the channel descriptor.

DMR_GetImageRequestBufferData()

TDMR_ERROR DMR_CALL DMR_GetImageRequestBufferData	(	HDRV	hDrv,
		int	requestNr,
		int *	pBytesPerPixel,
		int *	pChannelCount,
		int *	pHeight,
		int *	pWidth,
		int *	pSize,
		TImageBufferPixelFormat *	pPixelFormat,
		void **	ppData )

Returns information about the image associated with the desired request.

Note

This function should only be used when working with programming languages, that do not support function calls with pointers to pointers to structures like e.g. Visual Basic. Other users should call the function DMR_GetImageRequestBuffer() instead, as it is more efficient as it combines the work performed by this function and one or more calls to the function DMR_GetImageRequestBufferChannelData().

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

The function checks each pointer passed to it and only fills out the parameters with valid pointers, so if one or more values are not required you can pass '0' instead.

Always call this function to receive the up to date data for the current request and do NOT use this data for any other request!

See also

DMR_GetImageRequestBuffer(),
DMR_GetImageRequestBufferChannelData()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pBytesPerPixel	A pointer to the variable receiving the bytes per pixel for this image buffer. This can be 0 if the value is not needed.
[out]	pChannelCount	A pointer to the variable receiving number of channels for this image buffer. This can be 0 if the value is not needed.
[out]	pHeight	A pointer to the variable receiving the height of this image buffer. This can be 0 if the value is not needed.
[out]	pWidth	A pointer to the variable receiving the width of this image buffer. This can be 0 if the value is not needed.
[out]	pSize	A pointer to the variable receiving the size of this image buffer in bytes. This can be 0 if the value is not needed.
[out]	pPixelFormat	A pointer to the variable receiving the pixel format for this image buffer. This can be 0 if the value is not needed.
[out]	ppData	A pointer to the variable receiving the address of actual image data associated with this image buffer. This can be 0 if the value is not needed.

DMR_GetImageRequestBufferImageData()

TDMR_ERROR DMR_CALL DMR_GetImageRequestBufferImageData	(	HDRV	hDrv,
		int	requestNr,
		int	xOff,
		int	yOff,
		int	width,
		int	height,
		char *	pBuf,
		size_t	bufSize )

Returns an AOI of raw image data belonging to the specified request.

Note

This function should only be used when working with programming languages, that do not support function calls with pointers to pointers to structures like e.g. Visual Basic. Other users should call the function DMR_GetImageRequestBuffer() instead, as it is much more efficient as it allows direct access to the image data.

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

See also

DMR_SetImageRequestBufferImageData()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	xOff	The x offset from where to start to copy the data.
[in]	yOff	The y offset from where to start to copy the data.
[in]	width	The width of the AOI to copy.
[in]	height	The height of the AOI to copy.
[out]	pBuf	A pointer to the variable receiving the pixel values.
[in]	bufSize	The size of the user supplied buffer.

DMR_GetImageRequestInfo()

MVDMR_API TDMR_ERROR DMR_CALL DMR_GetImageRequestInfo	(	HDRV	hDrv,
		int	requestNr,
		RequestInfo *	pInfo )

Retrieves the RequestInfo of the desired request(deprecated).

Deprecated

This function has been declared deprecated. Use the more flexible function DMR_GetImageRequestInfoEx() instead.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

Attention

Using this function is not recommended as the data returned in the RequestInfo structure might contain truncated data. See RequestInfo for details and use direct property access functions in favour of this function to get information about a request object!

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pInfo	A pointer to a RequestInfo structure to retrieve the result on a successful call to this function.

DMR_GetImageRequestInfoEx()

TDMR_ERROR DMR_CALL DMR_GetImageRequestInfoEx	(	HDRV	hDrv,
		int	requestNr,
		RequestInfo *	pInfo,
		size_t	infoSize,
		int	reserved,
		int	reserved2 )

Retrieves the RequestInfo of the desired request.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

Attention

Using this function is not recommended as the data returned in the RequestInfo structure might contain truncated data. See RequestInfo for details and use direct property access functions in favour of this function to get information about a request object!

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pInfo	A pointer to a RequestInfo structure to retrieve the result on a successful call to this function.
[in]	infoSize	The size of the structure pointed to by pInfo in bytes.
[in]	reserved	Currently unsupported. MUST be set 0.
[in]	reserved2	Currently unsupported. MUST be set 0.

DMR_GetImageRequestParamS()

TDMR_ERROR DMR_CALL DMR_GetImageRequestParamS	(	HDRV	hDrv,
		int	requestNr,
		TImageRequestParam	param,
		char *	pBuf,
		size_t	bufSize )

Retrieves a string representation of a request related parameter.

When certain parameters shall be displayed in a GUI or a console window this function might come in handy. As things like 'pixel format: 3' doesn't have too much explanatory power this function provides a string representation for certain parameters belonging to a request.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

If the user supplied string buffer is not large enough to accommodate the complete string this function will return DMR_INPUT_BUFFER_TOO_SMALL

See also

DMR_ImageRequestWaitFor(),
DMR_GetImageRequestBuffer(),
DMR_GetImageRequestInfo(),
DMR_GetImageRequestResult()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	param	The parameter whose string representation shall be queried.
[out]	pBuf	A pointer to a user supplied string buffer.
[in]	bufSize	The size of the user supplied string buffer in bytes.

DMR_GetImageRequestResult()

MVDMR_API TDMR_ERROR DMR_CALL DMR_GetImageRequestResult	(	HDRV	hDrv,
		int	requestNr,
		RequestResult *	pResult )

Retrieves the RequestResult of the desired request(deprecated).

Deprecated

This function has been declared deprecated. Use the more flexible function DMR_GetImageRequestResultEx() instead.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pResult	A pointer to a RequestResult structure to retrieve the result on a successful call to this function.

DMR_GetImageRequestResultEx()

TDMR_ERROR DMR_CALL DMR_GetImageRequestResultEx	(	HDRV	hDrv,
		int	requestNr,
		RequestResult *	pResult,
		size_t	resultSize,
		int	reserved,
		int	reserved2 )

Retrieves the RequestResult of the desired request.

Note

Please see the description of DMR_ImageRequestUnlock() to find out when this function will return valid data.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pResult	A pointer to a RequestResult structure to retrieve the result on a successful call to this function.
[in]	resultSize	The size of the structure pointed to by pResult in bytes.
[in]	reserved	Currently unsupported. MUST be set 0.
[in]	reserved2	Currently unsupported. MUST be set 0.

DMR_GetImpactRequestBuffer()

MVDMR_API TDMR_ERROR DMR_CALL DMR_GetImpactRequestBuffer	(	HDRV	hDrv,
		int	requestNr,
		IPL_BUFHANDLE *	pBuffer )

Returns the IPL_BUFHANDLE of the desired request(deprecated).

Deprecated

This function is provided for compatibility with versions smaller than 1.3.4.11 of this library and has been declared deprecated. Applications should call DMR_GetImpactRequestBufferEx() instead.

This function returns the current image as an IPL_BUFHANDLE for the desired request. Always call this function to receive the correct data for the desired request and do not work with references to old structures, as the structure returned will be a copy of the structure currently describing the image buffer and NOT the address to the internal driver structure.

Note

If *pBuffer equals IPL_DONT_CARE new memory will be allocated for the resulting image.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function IPL_BufFree() as otherwise the result will either be a corrupted heap or a memory leak!

Note

When working with RGB data the destination format idpfRGB888Planar should be used for performance reasons as then less copy work has to be performed.

See also

IPL_BufFree()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise. In case of an error you still might need to call IPL_BufFree() in order to avoid resource leaks (e.g. if you've already passed a valid buffer handle to the function). You always have to free this buffer, if *pBuffer is not equal to IPL_DONT_CARE AFTER the call.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pBuffer	A pointer to a variable retrieving the data of the desired requests image buffer. The handle might be set to IPL_DONT_CARE if a new buffer shall be allocated.

DMR_GetImpactRequestBufferEx()

TDMR_ERROR DMR_CALL DMR_GetImpactRequestBufferEx	(	HDRV	hDrv,
		int	requestNr,
		IPL_BUFHANDLE *	pBuffer,
		TImpactBufferFlag	flags,
		unsigned int	reserved )

Returns the IPL_BUFHANDLE of the desired request.

This function returns the current image as an IPL_BUFHANDLE for the desired request. Always call this function to receive the correct data for the desired request and do not work with references to old structures, as the structure returned will be a copy of the structure currently describing the image buffer and NOT the address to the internal driver structure.

Note

If *pBuffer equals IPL_DONT_CARE new memory will be allocated for the resulting image.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function IPL_BufFree() as otherwise the result will either be a corrupted heap or a memory leak!

Note

When working with RGB data the destination format idpfRGB888Planar should be used for performance reasons as then less copy work has to be performed.

See also

IPL_BufFree()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise. In case of an error you still might need to call IPL_BufFree() in order to avoid resource leaks (e.g. if you've already passed a valid buffer handle to the function). You always have to free this buffer, if *pBuffer is not equal to IPL_DONT_CARE AFTER the call.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request from which to read the information. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[out]	pBuffer	A pointer to a variable retrieving the data of the desired requests image buffer. The handle might be set to IPL_DONT_CARE if a new buffer shall be allocated.
[in]	flags	Flags to define the behaviour of this function.
[in]	reserved	Reserved for later enhancement.

DMR_GetLastError()

TDMR_ERROR DMR_CALL DMR_GetLastError	(	TDMR_ERROR *	pErrorCode,
		char *	pErrorText,
		size_t *	pErrorTextSize )

Returns the last error code and string that did occur within the current thread.

This function returns the last error code and string that did occur within the current thread.

Note

The error code might either be from the range of TDMR_ERROR or TPROPHANDLING_ERROR depending on the module the error did occur so appropriate casting might be needed.

Since

2.21.0

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	pErrorCode	A pointer to a variable that receives the last error code that has been set within the current thread. This parameter must not be NULL!
[out]	pErrorText	A pointer to a user allocated buffer that receives the last error string that has been set within the current thread. Pass NULL to query the size needed in pErrorTextSize.
[in,out]	pErrorTextSize	A pointer to a variable containing the size of the user allocated buffer pointed to by pErrorText if pErrorText is not NULL. pErrorText is NULL the needed size for pErrorText will be returned. This parameter must not be NULL!

DMR_GetVersion()

const char *DMR_CALL DMR_GetVersion

(

TLibraryQuery

libraryQuery

)

Returns a string containing the version number of the specified library.

This function returns a string containing the version number of the specified library.

The format of the string will be MAJOR.MINOR.RELEASE.BUILD.

Since

2.1.2

Returns

A pointer to an internal version string.

Parameters

[in]

libraryQuery

The type of library to query information from.

DMR_ImageRequestConfigure()

TDMR_ERROR DMR_CALL DMR_ImageRequestConfigure	(	HDRV	hDrv,
		int	requestNr,
		int	reserved,
		void *	pReserved )

Sets a request into configuration mode.

In configuration mode certain properties of a request object can be modified. Only requests that are currently not used by the driver and are not locked because they contain image data that hasn't been processed can be set into configuration mode.

Note

A request that is in configuration mode can't be sent to the driver for acquisition until DMR_ImageRequestUnlock() has been called again.

See also

DMR_ImageRequestSingle(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestReset()

Since

1.10.31

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the image request to use for this call.
[in]	reserved	Currently unsupported. MUST be set 0.
[in]	pReserved	Currently unsupported. MUST be set 0.

DMR_ImageRequestReset()

TDMR_ERROR DMR_CALL DMR_ImageRequestReset	(	HDRV	hDrv,
		int	requestCtrl,
		int	mode )

Deletes all requests currently queued for the specified request control.

This function will terminate all running image acquisitions associated with the queue bound to the specified image request control and in addition to that will empty the queue of pending image requests for that queue. Also all requests that reside in the result queue and have not been picked up by the application will be unlocked and removed from the result queue. So after this function returns only the requests currently in possession of the application (so requests that have been picked up by successful calls to DMR_ImageRequestWaitFor() that have NOT been unlocked) need to be handled. All other requests are in a state where they can be queued for an acquisition again.

It does NOT unlock requests currently locked by the user!

See also

DMR_ImageRequestSingle(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestConfigure()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestCtrl	The number of the image request control to use for this call.
[in]	mode	Currently unsupported. MUST be set 0.

DMR_ImageRequestResultQueueElementCount()

TDMR_ERROR DMR_CALL DMR_ImageRequestResultQueueElementCount	(	HDRV	hDrv,
		int	queueNr,
		int *	pResultQueueElements )

Returns the number of Request objects in the result queue.

This functions queries the number of Request objects currently in the result queue that are available for pickup. This number reflects the number of DMR_imageRequestWaitFor() calls that could be executed afterwards the would return with a valid Request object immediately without waiting!

See also

DMR_ImageRequestReset(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestConfigure()

Since

2.9.0

Returns

• The number of Request objects in the result queue if successful.
• DMR_INVALID_QUEUE_SELECTION if the selected result queue does not exist.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	queueNr	The queue to be queried.
[out]	pResultQueueElements	A pointer to a variable which receives the number of request objects in the result queue

DMR_ImageRequestSave()

TDMR_ERROR DMR_CALL DMR_ImageRequestSave	(	HDRV	hDrv,
		int	requestNr,
		const char *	pFileName,
		TImageFileFormat	format )

Stores the image data described by a request into a file.

This function stores the image described by a request into a file.

Note

Internally the FreeImage library is used for this operation. If the library cannot be located in a supported version on the host system calling this function will fail.

Since

2.23.0

Returns

• DMR_NO_ERROR if successful.
• DMR_LIBRARY_NOT_FOUND if the required version of the FreeImage library could not be located on the host system.
• DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
• DEV_INPUT_PARAM_INVALID if a pixel format has been passed to the function that is not supported by the FreeImage library.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request which shall be saved. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	pFileName	The full path of the file to create.
[in]	format	The format of the file to be created. If this parameter is set to iffAuto make sure to specify a proper file extension.

DMR_ImageRequestSaveToVideoStream()

TDMR_ERROR DMR_CALL DMR_ImageRequestSaveToVideoStream	(	HDRV	hDrv,
		int	requestNr,
		HDMR_VIDEO_STREAM	hVideoStream )

Stores the image data described by a request into a video stream.

This function stores the image described by a request into a video stream.

Note

Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: DMR_OpenVideoStream()) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since

2.39.0

See also

DMR_OpenVideoStream(),
DMR_PauseVideoStream(),
DMR_SaveImageBufferToVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_LIBRARY_NOT_FOUND if no compatible version of the FFmpeg libraries could be located on the host system.
• DMR_EXECUTION_PROHIBITED if the video stream is currently paused.
• DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
• DEV_INPUT_PARAM_INVALID e.g. if a pixel format has been passed to the function that is not supported by the FFmpeg libraries.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request which shall be stored into the video stream. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	hVideoStream	The handle for the stream as obtained from a previous call to DMR_OpenVideoStream().

DMR_ImageRequestSingle()

TDMR_ERROR DMR_CALL DMR_ImageRequestSingle	(	HDRV	hDrv,
		int	requestCtrl,
		int *	pRequestUsed )

Sends an image request to the device driver.

This functions sends a single image request to the device driver. To wait for the image to become ready call the function DMR_ImageRequestWaitFor().

Attention

In order to make sure that no image data is lost, it is important to understand how the request mechanism works. The driver works with a fixed number of Request objects. The number of request objects available to the driver can be set by modifying the value of the property RequestCount in the system list. Each request will consume a certain amount of memory. Once an image has been captured by the request, this amount will be slightly more than the image itself needs in memory, so modify this parameter gently. On the other hand, it's necessary to have more than a single request in order to ensure a lossless acquisition. E.g. when working with free running cameras an image might be lost because when an image has been captured and processed the next vertical sync. pulse has already been missed before the request is unlocked again.

See also

DMR_ImageRequestReset(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestConfigure()

Returns

• DMR_NO_ERROR if successful.
• DEV_NO_FREE_REQUEST_AVAILABLE if all request objects are currently in use (either owned by the user or queued for acquisition).
• DEV_INVALID_REQUEST_NUMBER if the request number defined by the property RequestToUse of the used request control instance is invalid (out of bounds).
• DEV_REQUEST_ALREADY_IN_USE if the request number defined by the property RequestToUse of the used request control instance is already in use (either owned by the user or queued for acquisition).
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestCtrl	The number of the request control to use for this request
[out]	pRequestUsed	A pointer to a variable that will receive the number of the request used. This can be NULL if the value is not needed.

DMR_ImageRequestUnlock()

TDMR_ERROR DMR_CALL DMR_ImageRequestUnlock	(	HDRV	hDrv,
		int	requestNr )

Unlocks the request for the driver again.

To ensure that no image data is overwritten by another image request while the user still deals with the image from a previous acquisition each image buffer will be locked by the driver when it is returned to the user by a call to DMR_ImageRequestWaitFor(). No new image will be captured into the same buffer until the user unlocks the buffer again by calling DMR_ImageRequestUnlock().

After unlocking a request it is no longer guaranteed that the memory once referenced by the request and the image buffer belonging to it stays valid, so do NEVER try to access memory belonging to an unlocked request object. If you need to copy the image buffer or modify it in any other way, do everything you have to do BEFORE calling this function! Besides the actual image buffer (the information about the image and the image data itself) a request object consists of certain other data like e.g. the result, a time stamp etc. that can be queried using the various functions provided for this purpose. Among others these are:

DMR_GetImageRequestBufferData(),
DMR_GetImageRequestInfoEx(),
DMR_GetImageRequestParamS(),
DMR_GetImageRequestResultEx(),
DMR_GetImpactRequestBufferEx()

None of these functions should be called AFTER DMR_ImageRequestUnlock() has been called, as the result can either be an access to invalid memory or data that is no longer correct.

See also

DMR_ImageRequestReset(),
DMR_ImageRequestSingle(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestWaitFor(),
DMR_ImageRequestConfigure()

Returns

• DMR_NO_ERROR if successful.
• DEV_REQUEST_CANT_BE_UNLOCKED if the request number defined by requestNr is currently not owned by the application (either already unlocked or queued for acquisition).
• DMR_INPUT_BUFFER_TOO_SMALL if the request number defined by requestNr has been configured to capture into a user supplied buffer but the buffer is too small to acquire data into.
• DEV_REQUEST_BUFFER_MISALIGNED if the request number defined by requestNr has been configured to capture into a user supplied buffer but this buffer is not aligned in order to the alignment restrictions reported by this driver/device combination.
• DEV_REQUEST_BUFFER_INVALID if the request number defined by requestNr has been configured to capture into a user supplied buffer but an invalid (NULL) pointer has been attached to the request.
• DEV_INVALID_REQUEST_NUMBER if the request number defined by requestNr is invalid (out of bounds).
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request to unlock as received from a previous call to DMR_ImageRequestWaitFor()

DMR_ImageRequestWaitFor()

TDMR_ERROR DMR_CALL DMR_ImageRequestWaitFor	(	HDRV	hDrv,
		int	timeout_ms,
		int	queueNr,
		int *	pRequestNr )

Waits for a request object to become ready.

This function waits for a request object previously sent to the capture device by calling DMR_ImageRequestSingle(). When a new request became ready during the period of time specified by the timeout_ms parameter this request is extracted from the result queue and is returned to the user so the same request can not be returned twice until it has been processed and unlocked by the application.

Note

Whenever a request is returned to the user the image data described by the request remains valid until the user unlocks the image buffer again or the device driver is closed.

See also

DMR_ImageRequestReset(),
DMR_ImageRequestSingle(),
DMR_ImageRequestResultQueueElementCount(),
DMR_ImageRequestUnlock(),
DMR_ImageRequestConfigure(),
DMR_GetImageRequestBuffer(),
DMR_GetImageRequestInfo(),
DMR_GetImageRequestResult(),
DMR_GetImageRequestParamS()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	timeout_ms	The maximum wait time in milliseconds(ms) for this request to become ready. If timeout_ms is '-1', the function's timeout interval never elapses. If the result queue specified by the queueNr parameter already contains a request when calling this function the function will return immediately. Please note that each request has its own timeout that is independent from this wait timeout, thus this function will return with a valid request after the timeout for this request has elapsed even if e.g. a trigger has not been detected. For detailed information on the interaction of the timeout of this function and the timeout of a request please refer to the chapter Acquiring Data in the C section.
[in]	queueNr	The queue where to wait for the request. The number of request queues available depends on the number of video channels offered by the device. The queue a processed request ends up in can be defined by setting the property resultQueue of the used image request control BEFORE calling DMR_ImageRequestSingle().
[out]	pRequestNr	A pointer to a variable which receives the number of the request which contains the captured image on a successful call. This number can e.g. be passed to the function DMR_GetImageRequestBuffer()

DMR_ImportCameraDescription()

TDMR_ERROR DMR_CALL DMR_ImportCameraDescription	(	HDRV	hDrv,
		HLIST	hCameraDescList )

Updates a camera description with the data stored in a previous session or with the original default data(deprecated).

Deprecated

There is NO direct replacement for this function! Support for frame grabber boards has ended years ago. Simply remove all references to these functions and adjust your code to continue to work without them or stick to older releases of this SDK.

To restore the default values valid during the driver was initialised the function OBJ_RestoreDefault() with hCameraDescList as parameter can be used as well.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hCameraDescList	A handle to the camera description list returned from a previous call to DMR_FindList() and one or more of the iterator functions OBJ_GetFirstSibling(), OBJ_GetNextSibling() and OBJ_GetFirstChild().

DMR_Init()

TDMR_ERROR DMR_CALL DMR_Init

(

HDMR *

pDevices

)

Initialises the library.

This group contains functions for accessing device and memory (especially image specific/captured data) functionality. This function initialises internal data structures and locates devices and device drivers in the system.

Before any device can be accessed the user MUST successfully call this function. DMR_Init( HDMR* pHDmr ) can be called multiple times, but for each call to this function a call to DMR_Close() must be executed before unloading the library from process memory again.

If this function is called multiple times in the same process without calling DMR_Close() in between no additional work is performed by the function, but an internal usage counter is incremented.

When calling this function for the first time ever or for the first time after shutting down the library again with an appropriate number of calls to DMR_Close() this will result in all supported driver stacks to be loaded dynamically. See remarks below for consequences that result from this.

Attention

NEVER call this function from the DllMain context (Windows) of a dynamic library(*.dll, *.so, *.ocx, ...) as this will result in other shared libraries to be loaded dynamically by the framework and loading other libraries from within DllMain is discouraged (see DllMain Best Practices in MSDN for example). Violating this may cause lock ups in applications using your library. Instead define custom library init/close for this functions or use any other approach that suits your needs.

See also

DMR_Close()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

pDevices

A pointer to variable that receives the handle to the initialised device manager on a successful call to the function.

DMR_InitVideoStreamAPI()

TDMR_ERROR DMR_CALL DMR_InitVideoStreamAPI	(	void *	pReserved,
		size_t	reserved )

Initialises the video stream API.

Calling this function will initialise the video stream API.

Note

Internally the FFmpeg project (see FFmpeg section as well) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Because of what is stated in the above section Impact Acquire is NOT shipped with the FFmpeg binaries required to use this class!

On Windows the FFmpeg-share package matching the platform the application shall run with (32- or 64-bit) is needed. This can either be extracted into the installation folder of Impact Acquire e.g. into Toolkits/ffmpeg-4.2.2-win64-shared or Toolkits/ffmpeg-4.2.2-win32-shared (Works only for this versions) OR at the location pointed to by MVIMPACT_ACQUIRE_FFMPEG_DIR (see below) OR anywhere into the systems search path.

On Linux the package ffmpeg must be installed and if e.g. H.264 support is needed the libavcodec-extra package as well.

Attention

Please carefully read and understand the legal implications coming with the use of FFmpeg in a commercial product: http://ffmpeg.org/legal.html

Note

Impact Acquire is capable of communicating with FFmpeg 3.x and 4.x right now. In order to load the FFmpeg libraries from a custom location the environment variable MVIMPACT_ACQUIRE_FFMPEG_DIR can be defined before opening the first video stream after loading the mvDeviceManager library into the current processes address space. Without this environment variable only the systems default search path will be used to locate it and (Windows only) the Toolkits folder of the installation directory. This is how the search algorithm will operate:

if isEnvironmentVariableDefined( MVIMPACT_ACQUIRE_FFMPEG_DIR )
  if tryToLoadFFmpegVersion4Succeeded
    return
  if tryToLoadFFmpegVersion3Succeeded
    return
if isWindowsSystem
  if tryToLoadFFmpegVersionFromToolkits4Succeeded
    return
if tryToLoadFFmpegVersion4Succeeded
  return
if tryToLoadFFmpegVersion3Succeeded
  return
ReportError

Attention

It is NOT necessary to call this function before creating the first video stream! Right now this functions sole purpose is to find out if the video stream API is available at all without creating a video stream. Later this function might accept parameters allowing to e.g. specify a certain of the FFmpeg project to use etc.

Since

2.39.0

See also

DMR_OpenVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_INVALID_PARAMETER if any of the reserved parameters are not set to the required values
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	pReserved	Currently unsupported. MUST be set 0.
[in]	reserved	Currently unsupported. MUST be set 0.

DMR_IsSettingAvailable()

TDMR_ERROR DMR_CALL DMR_IsSettingAvailable	(	const char *	pName,
		TStorageLocation	storageLocation,
		TScope	scope )

Checks if a certain setting is available.

Since

2.19.0

Returns

• DMR_NO_ERROR if the setting is available.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	pName	The name of the setting to look for.
[in]	storageLocation	The storage location where to look for this setting.
[in]	scope	Specifies where to look for the setting when storageLocation is set to slNative or slNative_Raw under Windows© as then the Registry will be used.

DMR_IsVideoStreamPaused()

TDMR_ERROR DMR_CALL DMR_IsVideoStreamPaused

(

HDMR_VIDEO_STREAM

hVideoStream

)

Checks is this video stream currently is paused.

Note

Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: DMR_OpenVideoStream()) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since

2.41.0

See also

DMR_OpenVideoStream(),
DMR_CloseVideoStream(),
DMR_PauseVideoStream(),
DMR_ResumeVideoStream()

Returns

• DMR_NO_ERROR if successful thus if the video stream currently is paused.
• DMR_NOT_INITIALIZED if this stream is valid but NOT paused
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hVideoStream

The handle for the stream as obtained from a previous call to DMR_OpenVideoStream().

DMR_LoadImageBuffer()

TDMR_ERROR DMR_CALL DMR_LoadImageBuffer	(	ImageBuffer **	ppBuffer,
		const char *	pFileName,
		TImageFileFormat	format )

Loads an image from a file into a newly allocated image buffer structure.

If ppBuffer points to a structure previously allocated by any other function, this memory will be lost(memory leak). In that case DMR_ReleaseImageRequestBufferDesc() (if the structure has been allocated with DMR_AllocImageRequestBufferDesc() or DMR_GetImageRequestBuffer()) or DMR_ReleaseImageBuffer()(if the structure has been allocated with DMR_AllocImageBuffer()) should be called before.

This function will allocate memory for the pixel data pointed to by ImageBuffer::vpData and also will fill the structure with channel specific data depending on the format of the pixel data detected in the file specified by pFileName.

This function will call DMR_AllocImageRequestBuffer(), so everything described in that functions description will be valid for this call as well.

Attention

Do NOT try to free memory allocated by this function by calling free() or delete. Always use the function DMR_ReleaseImageBuffer() as otherwise the result will either be a corrupted heap or a memory leak!

Note

Internally the FreeImage is used for this operation. If the library cannot be located in a supported version on the host system calling this function will fail.

See also

DMR_ReleaseImageRequestBufferDesc(),
DMR_ReleaseImageBuffer(),
DMR_AllocImageRequestBufferDesc(),
DMR_GetImageRequestBuffer(),
DMR_CopyImageBuffer(),
DMR_CopyImageRequestBufferDesc()

Since

2.23.0

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[out]	ppBuffer	A pointer to a pointer receiving the address of the newly allocated structure on a successful call to this function.
[in]	pFileName	The full path of the file to create.
[in]	format	The format of the file to be created. If this parameter is set to iffAuto make sure to specify a proper file extension.

DMR_LoadRTCtrProgram()

TDMR_ERROR DMR_CALL DMR_LoadRTCtrProgram	(	HDRV	hDrv,
		HLIST	hRTCtrList )

Loads a program from a file into a hardware real-time controller (HRTC)

This function loads a program from a file into the HRTC associated with the parameter hRTCtrList. The name and full path for the file to be loaded is stored in the string property 'FileName' in the list bound to hRTCtrList. It can be modified by the user. The parameter hRTCtrList can be obtained by a previous call to DMR_FindList() where the type has been set to dmltRTCtr. In this case the parameter flags can be used as an index to the HRTC in question.

See also

DMR_SaveRTCtrProgram()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hRTCtrList	A handle to the HRTC as returned from a previous call to DMR_FindList().

DMR_LoadSetting()

TDMR_ERROR DMR_CALL DMR_LoadSetting	(	HDRV	hDrv,
		const char *	pName,
		TStorageFlag	storageFlags,
		TScope	scope )

Loads a previously stored setting.

This function can be used to restore a previously stored setting again.

To load a setting from a file the sfFile should be specified as part of storageFlags. To load a setting from a platform specific location such as the Registry under Windows© sfNative should be specified. It's not allowed to combine sfFile and sfNative for this operation.

Attention

Since Impact Acquire 2.9.0 GenICam devices will be able to save their properties in a XML File, only if the properties have the streamable attribute set (for more information refer to the GenICam standard specification). Properties with no streamable attribute set, will be silently ignored when saving, which means they will not be saved in the XML file. For Balluff/MATRIX VISION GenICam cameras, starting with firmware version 1.6.414 the streamable attribute is set for all the necessary properties.

Attention

Since Impact Acquire 2.9.0 and again in version 2.11.0 storing and loading of camera settings in a XML file for the dilGenICam interface layout has been updated. As a result XML files created with newer versions of Impact Acquire might not be readable on systems with older version of Impact Acquire installed. XML files created on systems with earlier versions of Impact Acquire will always be readable this or newer versions. See the following table for details.

Impact Acquire Version	Loading a XML settings file created with Impact Acquire version < 2.9.0	Loading a XML settings file created with Impact Acquire version 2.9.0 - 2.10.1	Loading a XML settings file created with Impact Acquire version 2.11.0 or later
< 2.9.0	YES	NO	NO
2.9.0 - 2.10.1	YES	YES	NO
>= 2.11.0	YES	YES	YES

Since Impact Acquire 2.28.0 it is possible for devices operated in the dilGenICam interface layout to store settings including including sequencer set and user set (see SFNC for details) data by specifying the sfProcessGenICamSequencerData and/or sfProcessGenICamUserSetData during the storage operation. Settings stored like this cannot be loaded by previous Impact Acquire versions.

Note

For devices operated in the dilGenICam interface layout further restriction apply: Settings created with a certain product type can only be used with other devices belonging to the exact same type as defined by the property Product inside the device list (the one device specific property list that is accessible without initialising the device before). Even if a setting can be used with various firmware versions it is recommended to use one setting for multiple devices all updated to the very same firmware version to avoid compatibility problems.

See also

DMR_SaveSetting(),
DMR_LoadSettingFromDefault(),
DMR_SaveSettingToDefault().

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	pName	The name or the full path under where the setting is located
[in]	storageFlags	The flags which define which information shall be read from the location and how this information shall be interpreted.
[in]	scope	Specifies where the information is located.

DMR_LoadSettingFromDefault()

TDMR_ERROR DMR_CALL DMR_LoadSettingFromDefault	(	HDRV	hDrv,
		TScope	scope )

Loads the default settings.

This function will try to load the settings from a default location. This function can only succeed if a setting has been stored previously by a call to DMR_SaveSettingToDefault().

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See DMR_LoadSetting for details.

See also

DMR_SaveSetting(),
DMR_LoadSetting(),
DMR_SaveSettingToDefault().

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	scope	Specifies where the information is located.

DMR_OpenDevice()

TDMR_ERROR DMR_CALL DMR_OpenDevice	(	HDEV	hDev,
		HDRV *	pHDrv )

Initialises a device.

This function will try to initialise the device associated with hDev. On a successful call to this function pHDrv will contain a handle to the device's driver interface. This handle then can be used to call various driver functions or access and use device specific properties and objects.

Whenever a device is opened, the driver will execute the following procedure:

Device setting start procedure

Please have a look at the tool ImpactControlCenter for more information about automatic loading of settings when a device is opened.

See also

DMR_CloseDevice(),
DMR_GetDevice(),
DMR_GetDriverHandle(),
DMR_GetDeviceCount(),
DMR_UpdateDeviceList()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	The valid handle to a device.
[out]	pHDrv	A pointer to a variable that receives the handle to the successfully initialised devices interface.

DMR_OpenVideoStream()

TDMR_ERROR DMR_CALL DMR_OpenVideoStream	(	const char *	pFileName,
		const unsigned int	imageWidth,
		const unsigned int	imageHeight,
		const TVideoCodec	codec,
		const unsigned int	quality_pc,
		const unsigned int	bitrate,
		HDMR_VIDEO_STREAM *	pHVideoStream )

Creates a new video stream.

Calling this function will create a new video stream. After successful creation functions like DMR_SaveImageBufferToVideoStream() or DMR_ImageRequestSaveToVideoStream() can be called to store images into this stream. Once the stream is no longer needed an application should call DMR_CloseVideoStream() to free all resources again. Not doing so will block these resources until the mvDeviceManager library is unloaded from the process memory.

Note

See DMR_InitVideoStreamAPI() for more information about the internals of the video stream API!

When creating a new video stream please refer to the codecs recommended file extension documented at the corresponding value of TVideoCodec. Currently video streams can only be created for a limited number of pixel formats. Which codec supports which input formats is also described at the corresponding TVideoCodec value. Make sure to use one of these formats either by setting up your device accordingly or by using the PixelFormat property of the Image Format Conversion Filter.

Since

2.39.0

See also

DMR_InitVideoStreamAPI(),
DMR_CloseVideoStream(),
DMR_PauseVideoStream(),
DMR_IsVideoStreamPaused(),
DMR_ResumeVideoStream(),
DMR_SaveImageBufferToVideoStream(),
DMR_ImageRequestSaveToVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_INVALID_PARAMETER if hVideoStream refers to an invalid handle.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	pFileName	The full path or file name for the video stream to create.
[in]	imageWidth	The inpout image width in pixels.
[in]	imageHeight	The input image height in pixels.
[in]	codec	The video codec to use for the stream to create.
[in]	quality_pc	The quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: vcH264. vcH265
[in]	bitrate	The bitrate of the resulting MPEG video stream in kBit/s. This value is only taken into account for the following codecs: vcMPEG2.
[out]	pHVideoStream	On a successful call this variable will contain a new handle to a video stream after the function did return.

DMR_PauseVideoStream()

TDMR_ERROR DMR_CALL DMR_PauseVideoStream

(

HDMR_VIDEO_STREAM

hVideoStream

)

Pauses a video stream.

This function pauses a video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note

Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: DMR_OpenVideoStream()) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since

2.41.0

See also

DMR_OpenVideoStream(),
DMR_CloseVideoStream(),
DMR_IsVideoStreamPaused(),
DMR_ResumeVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_BUSY if this stream has been paused already.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hVideoStream

The handle for the stream as obtained from a previous call to DMR_OpenVideoStream().

DMR_ReleaseImageBuffer()

TDMR_ERROR DMR_CALL DMR_ReleaseImageBuffer

(

ImageBuffer **

ppBuffer

)

frees the memory previously allocated for the specified ImageBuffer structure again.

These functions will require a subsequent call to DMR_ReleaseImageBuffer():

• DMR_AllocImageBuffer(),
  
• DMR_CopyImageBuffer()
  

Attention

Do not call this function when the buffer pointed to by ppBuffer has been obtained from one of the following functions:

• DMR_AllocImageRequestBufferDesc()
• DMR_GetImageRequestBuffer()
• DMR_CopyImageRequestBufferDesc()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in,out]

ppBuffer

A pointer to the ImageBuffer structure whose memory shall be freed. On a successful call to this function, the pointer pointing to the actual structure will be reset to 0.

DMR_ReleaseImageRequestBufferDesc()

TDMR_ERROR DMR_CALL DMR_ReleaseImageRequestBufferDesc

(

ImageBuffer **

ppBuffer

)

frees the memory previously allocated for the specified ImageBuffer structure again.

These functions will require a subsequent call to DMR_ReleaseImageRequestBufferDesc():

DMR_GetImageRequestBuffer() if called with ppBuffer = 0,
DMR_CopyImageRequestBufferDesc() if called with ppDst = 0,
DMR_AllocImageRequestBufferDesc()

Attention

Do not call this function when the buffer pointed to by ppBuffer has been allocated with one of the following functions:

• DMR_AllocImageBuffer()
• DMR_CopyImageBuffer()

In that case the function DMR_ReleaseImageBuffer() must be called in order to avoid memory leaks.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in,out]

ppBuffer

A pointer to the ImageBuffer structure whose memory shall be freed. On a successful call to this function, the pointer pointing to the actual structure will be reset to NULL.

DMR_ResumeVideoStream()

TDMR_ERROR DMR_CALL DMR_ResumeVideoStream

(

HDMR_VIDEO_STREAM

hVideoStream

)

Resumes a video stream.

This function resumes a previously paused video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note

Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: DMR_OpenVideoStream()) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since

2.41.0

See also

DMR_OpenVideoStream(),
DMR_CloseVideoStream(),
DMR_IsVideoStreamPaused(),
DMR_PauseVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_EXECUTION_PROHIBITED if this stream has not been paused before.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hVideoStream

The handle for the stream as obtained from a previous call to DMR_OpenVideoStream().

DMR_SaveImageBuffer()

TDMR_ERROR DMR_CALL DMR_SaveImageBuffer	(	const ImageBuffer *	pBuffer,
		const char *	pFileName,
		TImageFileFormat	format )

Stores the complete data of one ImageBuffer structure into a file.

This function stores the image described by a ImageBuffer structure pointed to by the pBuffer variable into a file.

Note

Internally the FreeImage library (see FreeImage section) is used for this operation. If the library cannot be located in a supported version on the host system calling this function will fail.

Since

2.23.0

Returns

• DMR_NO_ERROR if successful.
• DMR_LIBRARY_NOT_FOUND if the required version of the FreeImage library could not be located on the host system.
• DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
• DMR_INVALID_PARAMETER if either pBuffer or pFileName refers to a NULL pointer.
• DEV_INPUT_PARAM_INVALID if a pixel format has been passed to the function that is not supported by the FreeImage library.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	pBuffer	A pointer to an ImageBuffer structure to be stored.
[in]	pFileName	The full path of the file to create.
[in]	format	The format of the file to be created. If this parameter is set to iffAuto make sure to specify a proper file extension.

DMR_SaveImageBufferToVideoStream()

TDMR_ERROR DMR_CALL DMR_SaveImageBufferToVideoStream	(	HDMR_VIDEO_STREAM	hVideoStream,
		const ImageBuffer *	pBuffer,
		const int64_type	timestamp_us )

Stores an image into a video stream.

This function stores an image into a video stream.

Note

Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: DMR_OpenVideoStream()) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.

Since

2.39.0

See also

DMR_OpenVideoStream(),
DMR_PauseVideoStream(),
DMR_IsVideoStreamPaused(),
DMR_ResumeVideoStream(),
DMR_ImageRequestSaveToVideoStream()

Returns

• DMR_NO_ERROR if successful.
• DMR_LIBRARY_NOT_FOUND if no compatible version of the FFmpeg libraries could be located on the host system.
• DMR_EXECUTION_PROHIBITED if the video stream is currently paused.
• DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
• DEV_INPUT_PARAM_INVALID e.g. if a pixel format has been passed to the function that is not supported by the FFmpeg libraries.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hVideoStream	The handle for the stream as obtained from a previous call to DMR_OpenVideoStream().
[in]	pBuffer
[in]	timestamp_us	The timestamp (in micro-seconds) to associate with this image

DMR_SaveRTCtrProgram()

TDMR_ERROR DMR_CALL DMR_SaveRTCtrProgram	(	HDRV	hDrv,
		HLIST	hRTCtrList )

Stores the current program of a hardware real-time controller (HRTC) into a file.

This function stores the current state of the program associated with an HRTC into a file. The name and full path for the file to be written is stored in the string property 'FileName' in the list bound to hRTCtrList. It can be modified by the user. The parameter hRTCtrList can be obtained by a previous call to DMR_FindList() where the type has been set to dmltRTCtr. In this case the parameter flags can be used as an index to the HRTC in question.

See also

DMR_LoadRTCtrProgram()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	hRTCtrList	A handle to the HRTC as returned from a previous call to DMR_FindList().

DMR_SaveSetting()

TDMR_ERROR DMR_CALL DMR_SaveSetting	(	HDRV	hDrv,
		const char *	pName,
		TStorageFlag	storageFlags,
		TScope	scope )

Stores the current settings.

This function can be used to store the current settings either in a XML-file or (under Windows©) into the Registry.

To store a setting in a file the sfFile should be specified as part of storageFlags. To store a setting in a platform specific location such as the Registry under Windows© sfNative should be specified. Both flags can be combined. In that case the same setting will be stored in a file AND in a platform specific location if these location differ (platform dependent!).

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See DMR_LoadSetting for details.

See also

DMR_LoadSettingFromDefault(),
DMR_LoadSetting(),
DMR_SaveSettingToDefault().

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	pName	The name or the full path under which this setting shall be stored
[in]	storageFlags	The flags which define which information shall be stored and how this information shall be stored.
[in]	scope	Specifies where the information shall be stored.

DMR_SaveSettingToDefault()

TDMR_ERROR DMR_CALL DMR_SaveSettingToDefault	(	HDRV	hDrv,
		TScope	scope )

Stores the current settings under a default location.

Under Windows® this will be the Registry.

Attention

There has been an incompatible change when loading settings in version 2.9.0 and 2.11.0 of Impact Acquire as well as in version 2.28.0. See DMR_LoadSetting for details.

See also

DMR_LoadSettingFromDefault(),
DMR_LoadSetting(),
DMR_SaveSetting().

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR or TPROPHANDLING_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	scope	Currently unsupported. MUST be set sUser.

DMR_SetDeviceID()

TDMR_ERROR DMR_CALL DMR_SetDeviceID	(	HDEV	hDev,
		int	newID )

Assigns a new ID to this device.

To allow any application to distinguish between different devices of the same type the user can assign an unique ID to each device using this function. This ID currently is limited to values between 0 and 250 and is stored in the physical devices EEPROM.

Precondition

The device must be closed to assign a new ID.

Note

This ID is not to be confused with the handle returned by the function DMR_GetDevice(). The latter one represents something which can be assumed as a handle from a software based point of view, while the ID represented by the property DeviceID is an ID stored in the physical devices EEPROM.

See also

DMR_OpenDevice(),
DMR_CloseDevice()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDev	A handle to the device.
[in]	newID	The new ID to be written to the devices internal memory

DMR_SetImageRequestBufferImageData()

TDMR_ERROR DMR_CALL DMR_SetImageRequestBufferImageData	(	HDRV	hDrv,
		int	requestNr,
		int	xOff,
		int	yOff,
		int	width,
		int	height,
		char *	pBuf,
		size_t	bufSize )

Sets an AOI of raw image data belonging to the specified request.

Note

This function should only be used when working with programming languages, that do not support function calls with pointers to pointers to structures like e.g. Visual Basic. Other users should call the function DMR_GetImageRequestBuffer() instead, as it is much more efficient as it allows direct access to the image data.

See also

DMR_GetImageRequestBufferImageData()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	hDrv	A handle to the device drivers interface.
[in]	requestNr	The number of the request to apply the parameter set to. This parameter is typically obtained by a call to DMR_ImageRequestWaitFor().
[in]	xOff	The x offset from where to start to copy the data.
[in]	yOff	The y offset from where to start to copy the data.
[in]	width	The width of the AOI to copy.
[in]	height	The height of the AOI to copy.
[in]	pBuf	A pointer to the variable containing the pixel values.
[in]	bufSize	The size of the user supplied buffer. Currently not used.

DMR_UpdateDeviceList()

TDMR_ERROR DMR_CALL DMR_UpdateDeviceList	(	unsigned int	reserved,
		int	reserved2 )

Updates the internal device list.

Most devices can't appear out of nowhere. For example a PCI device is either connected to the current system when the device manager is initialised or not but it will never appear at runtime after the DMR_Init() function has been called successfully.

However certain device classes (e.g. network devices) might be connected to the system AFTER the device manager has been initialised. In order not to pollute the network or bus with constant rescan messages the user should call this function instead. This can either be done in reasonable intervals or after it is known that a new device has been connected to the system.

If new devices have been detected a subsequent call to DMR_GetDeviceCount() will result in a higher value when compared to a previous call and the changed counter of the HDMR returned from DMR_Init() will contain a different value as well then (however this could also happen because a certain device related property did change its state).

Note

As long as a certain instance of a device manager is active, the devices once detected will NOT disappear from the list of devices even if they have been unplugged from the system. So the list of devices can only grow, but never gets shorter again until either the process terminates or the DMR_Close() function has been called at least the same amount of times DMR_Init() has been called before. If a device has been unplugged, its State property will change. If the application is interested in getting an instant notification when a device has been disconnected a callback can be registered on this property. How to do this is explained here: Callback.c

See also

DMR_Init(),
DMR_GetDevice(),
DMR_OpenDevice(),
DMR_CloseDevice(),
DMR_GetDeviceCount()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]	reserved	Currently unsupported. MUST be set 0.
[in]	reserved2	Currently unsupported. MUST be set 0.

DMR_UpdateDigitalInputs()

TDMR_ERROR DMR_CALL DMR_UpdateDigitalInputs

(

HDRV

hDrv

)

Updates the property representation of the digital inputs by checking the physical device's inputs.

The actual value of the digital inputs can be queried by reading the property DigitalInputs in the IOSubSystem property list. However the value stored in this property will only reflect the current state of the digital inputs if the function DMR_UpdateDigitalInputs() has been called since the last change on the digital inputs has occurred.

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hDrv

A handle to the device drivers interface.

DMR_UpdateFirmware()

TDMR_ERROR DMR_CALL DMR_UpdateFirmware

(

HDEV

hDev

)

Updates the firmware of the device.

calling this function will cause the driver to download the firmware version compiled into the driver library into the devices internal memory. This ID is NOT volatile. It will remain stored even if the device is unplugged.

Note

• This feature currently is only available for mvBlueFOX devices. To update the firmware of other devices please refer to the tool DeviceConfigure(this tool also offers a command-line interface)
• Be sure what you are doing before calling this function. Under normal circumstances it won't be necessary to update a devices firmware.
• The download will take some time (depending on the device up to 30 seconds). During this time the device and the thread calling this function will NOT respond.
• Do NOT interrupt this download.
• After a successful download a USB device needs to be unplugged and plugged in again. Otherwise the new firmware version will not be activated.
• To download a new firmware version the device must be closed.
• Not every device will offer this feature! When calling this function for a device that does not offer this feature, the function will return DMR_FEATURE_NOT_AVAILABLE.

See also

DMR_OpenDevice(),
DMR_CloseDevice()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hDev

A handle to the device.

DMR_WriteUserDataToHardware()

TDMR_ERROR DMR_CALL DMR_WriteUserDataToHardware

(

HDEV

hDev

)

Writes the current set of user data into the devices non-volatile memory.

This function might take a while. Depending on the device architecture and the amount of memory up to some hundred ms. Therefore make sure this function is not called more often then necessary to let your application perform efficiently.

See also

DMR_CreateUserDataEntry(),
DMR_DeleteUserDataEntry()

Returns

• DMR_NO_ERROR if successful.
• A negative error code of type TDMR_ERROR otherwise.

Parameters

[in]

hDev

A handle to the device.