| MIL 10 Reference
| Customize Help
| Save Settings

MdigProcess


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Not supported on:
Not supported on Matrox GPU processing driver
Partially supported on:
Partially supported on Host system
Partially supported on Matrox CronosPlus
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox IEEE 1394 IIDC driver
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox USB3 Vision driver (requires Update 19)

Fully supported on:
Fully supported on Matrox Iris GT
Fully supported on Matrox Morphis
Fully supported on Matrox Morphis QxT
Fully supported on Matrox Orion HD
Fully supported on Matrox Radient eCL
Fully supported on Matrox Solios eA/XA
Fully supported on Matrox Solios ecl/xcl/ev-cl
Fully supported on Matrox Vio

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MdigInquireFeature
Next
Synopsis
Grabs a sequence of images and processes them with a user-defined function as they are grabbed.
Syntax
void MdigProcess(
MIL_ID DigId, //in
const MIL_ID *DestImageArrayPtr, //in
MIL_INT ImageCount, //in
MIL_INT64 Operation, //in
MIL_INT64 OperationFlag, //in
MIL_DIG_HOOK_FUNCTION_PTR HookHandlerPtr, //in
void *UserDataPtr //in
)
Description

This function uses the specified digitizer to acquire images and store them sequentially in a list of buffers. It also hooks a user-defined function to the modification of any buffer in the specified list. So every time a new frame is grabbed in a buffer in the list, the user-defined function is called.

If set synchronously, MdigProcess() will block the thread until the list of sequential grabs has completed. If set asynchronously, the buffers are prepared, and then control is returned to the calling thread while, in the background, the grabs will begin.

The grabs can stop at the end of the list of buffers, after a predefined number of grabs occur, or when a stop instruction is explicitly given. Round-robin grabbing will occur when the number of grabs exceeds the number of buffers available. To grab until a stop instruction, you must call MdigProcess() with M_START; when you want to stop grabbing, you must call MdigProcess() with M_STOP. Note that in this case, if you do not issue a stop instruction, an endless loop is created.

When grabbing round-robin, if the average time it takes to process a frame is greater than the frame rate of a camera, frames will eventually be missed.

The buffers are filled with the grabbed data in the order in which they are stored in the list. The index of the buffer modified can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_INDEX. The MIL identifier of the buffer modified can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_ID. To identify whether the buffer modified (that is, the current frame) is corrupt, use MdigGetHookInfo() with M_CORRUPTED_FRAME.

Note that, by default, if a buffer modification event occurs while a buffer is being processed by the hooked user-defined function, the event is queued. When running on a computer with multiple CPUs, you can have the event handled by different instances of the user defined function running on different threads. To do so, use MsysControl() with M_MODIFIED_BUFFER_HOOK_MODE set to M_MULTI_THREAD.

When the specified digitizer is set to perform triggered grabs, the default behavior of the function is to wait for a trigger event before grabbing each frame. To grab all or a specific number of frames per trigger, set the OperationFlag parameter to M_TRIGGER_FOR_FIRST_GRAB and use the Operation parameter to specify how many frames to grab per trigger. To grab continuously after just one trigger, use + M_FRAMES_PER_TRIGGER() set to M_INFINITE with M_TRIGGER_FOR_FIRST_GRAB.

It is not recommended to change the digitizer settings of the digitizer currently being used when grabs are still pending.

[Matrox GigE Vision driver; Matrox GigE Vision driver (requires Update 25); Matrox Radient eV-CLHS (requires Update 21); Matrox Radient eV-CXP; Matrox USB3 Vision driver (requires Update 19)]

This function transparently sets up the camera to start the acquisition of images, in either streaming or triggered mode, depending on your settings. If the camera is in triggered mode, it will start waiting for a trigger. To control this behavior, use MdigControl() with M_GC_STREAMING_MODE.

[Host system]

When grabbing from a video or directory of images, once the last image is grabbed, grabbing will restart from the beginning of the video or from the first image in the directory.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
DigId

Specifies the identifier of the digitizer to be used to perform the grabs.

DestImageArrayPtr

Specifies the address of the array containing the identifiers of the buffers in which to place the grabbed images. The buffers should be of an appropriate type and depth to hold the grabbed images. To allocate each buffer, use MbufAlloc...() with M_GRAB. When a buffer is no longer required, release it, using MbufFree().

Note the image buffers in the array must not have a region of interest (ROI) associated with them. Using an image buffer with an ROI will cause an error.

ImageCount INQ

Specifies the number of buffers in the array of destination image buffers.

Operation

Specifies the type of operation to perform.

This parameter should be set to one of the following values:

function map For specifying the type of operation to perform
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_SEQUENCE +

Grabs a specific number of frames, storing them sequentially in a list of buffers. Grabbing ends once the specified number of frames have been captured.

When using a digitizer set to perform triggered grabs and the OperationFlag parameter is set to M_TRIGGER_FOR_FIRST_GRAB, the function will grab the specified number of frames when the first trigger event occurs.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_START +

Starts grabbing round-robin into the list of buffers; the grabs will continue until stopped (using MdigProcess() with M_STOP).

When using a digitizer set to perform triggered grabs and the OperationFlag parameter is set to M_TRIGGER_FOR_FIRST_GRAB, the function will, by default, start grabbing all frames when the first trigger event occurs.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_STOP +

Stops the grab. By default, it also cancels all grabs that might have been queued. Note that cancelled grabs will not trigger the hooked function, but the events for the previous grabs are still processed.

To stop a grab started in synchronous mode, the Operation parameter must be set to M_STOP and the MdigProcess() function called from a separate thread.

(summarize)
† a b c e f g h i j k l m n o p q r s
Combination constant for M_STOP.

You can add the following value to the above-mentioned value to specify that previously queued grabs should not be cancelled when stopping .

function map For M_STOP
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_WAIT

Stops queuing new grabs and waits for all previously queued grabs to finish before returning control to the Host.

 † a b c e f g h i j k l m n o p q r s
Combination constant for M_SEQUENCE.

You can add the following value to the above-mentioned value to specify the number of frames to grab .

function map For M_SEQUENCE
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse
M_COUNT (
MIL_INT n
)

Specifies the number of frames to grab in the sequence.

This combination constant will cause MdigProcess() to stop grabbing when the grab count (n) is reached. If the grab count is greater than the buffer count, the grab will be done in round-robin style. By default, the grab count is equal to the number of buffers in the destination image array.

(summarize)
† a b c e f g h i j k l m n o p q r s
Parameters

Specifies the number of frames to grab. n is a positive integer that can be a maximum of 2 to the power of 28.
Combination constant for M_START.

You can add the following value to the above-mentioned value to specify the number of frames to grab sequentially when a digitizer trigger event occurs .

function map For M_START
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse

Specifies the number of frames to grab sequentially when a digitizer trigger event occurs.

Note that to use this setting, the OperationFlag parameter must be set to M_TRIGGER_FOR_FIRST_GRAB and the digitizer used must be configured to grab upon a trigger.

(summarize)
† f g h i j k l m n p q r
Parameters

Specifies the number of frames to grab sequentially for each digitizer trigger event.

 † f g h i j k l m n p q r
M_INFINITE

Sets to grab an infinite number of frames. No other trigger is necessary.
† f g h i j k l m n p q r
Value

Sets to grab a specific number of frames. Note that this can be a maximum of 2 to the power of 28.
† f g h i j k l m n p q r
OperationFlag

Specifies more information about the synchronization and triggering of the grab.

function map For controlling the order in which processing occurs
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT

Specifies the default execution mode.

If the Operation parameter is set to M_START, the default is the same as M_ASYNCHRONOUS.

If the Operation parameter is set to M_SEQUENCE, the default is the same as M_SYNCHRONOUS.

If the Operation parameter is set to M_STOP, the default is the same as M_SYNCHRONOUS unless MdigProcess() is called from the user-defined function, in which case the default is the same as M_ASYNCHRONOUS. Note that when the Operation parameter is set to M_STOP, M_DEFAULT is the only possible setting for the OperationFlag parameter.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_ASYNCHRONOUS +

Allows your thread to continue after initiating the start of the grabs, rather than waiting for MdigProcess() to finish.

Note than when you are grabbing and processing a sequence of images asynchronously, you must make an additional call to MdigProcess using M_STOP to free internally allocated resources.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_SYNCHRONOUS +

Synchronizes your thread with the end of MdigProcess().

 † a b c e f g h i j k l m n o p q r s
Combination constants for M_ASYNCHRONOUS; M_SYNCHRONOUS.

You can add one of the following values to the above-mentioned values to specify how the calibration context associated with the digitizer is propagated to each modified image buffer in the list.

function map For how the calibration context is propigated
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_CALIBRATION_PROPAGATE_AT_EACH_FRAME

Specifies that the calibration context associated with the digitizer is re-associated with the buffer each time the buffer is modified and just before calling the hook-handler function. This is less error-prone than M_CALIBRATION_PROPAGATE_ONCE, but it might slow down the hook-handler function.

(summarize)
† f g h i j k l m n p q r
Collapse M_CALIBRATION_PROPAGATE_OFF

Specifies to not affect the calibration context associated with the modified image buffer. You must associate the required calibration context with the image buffers before calling MdigProcess(), if necessary.

(summarize)
† f g h i j k l m n p q r
Collapse M_CALIBRATION_PROPAGATE_ONCE

Specifies that before starting image acquisition, the calibration context associated with the digitizer is also associated with each image buffer. Alternatively, you can create a child buffer that has the same size as the grabbed buffer and work with this child buffer to preserve the calibration state of the original parent buffer. The child buffer will have its own local calibration information that will not affect its parent bufffer.

Since the calibration context associated with the digitizer is only propagated at the beginning of the grab sequence, be cautious when using the hook-handler function to change the calibration context settings; the calibration context re-associated with the digitizer will not be associated with the modified buffer afterwards.

This is the default value.

(summarize)
† f g h i j k l m n p q r
Combination constant for M_ASYNCHRONOUS; M_SYNCHRONOUS.

You can add the following value to the above-mentioned values to set how the function will behave when the digitizer is configured for triggered grabs.

function map For only controling the grab of the first frame with a trigger
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_TRIGGER_FOR_FIRST_GRAB

Specifies that a trigger will only be used to control the grab of the first frame. When there is no preset end to the list of grabs (M_START), you can also force every n th grab to wait for a trigger. To do so, set the Operation parameter to M_START + M_FRAMES_PER_TRIGGER().

Note that if the digitizer is not configured for triggered grabs, M_TRIGGER_FOR_FIRST_GRAB is ignored. Also, when the digitizer is configured for triggered grabs, but M_TRIGGER_FOR_FIRST_GRAB is not set (the default behavior), the function will only grab each frame when triggered.

(summarize)
† a b c e f g h i j k l m n o p q r s
HookHandlerPtr

Specifies the address of the function that is called when a buffer is modified in the array of destination image buffers.

The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

MIL_INT MFTYPE HookHandler(
MIL_INT HookType,
MIL_ID EventId,
void *UserDataPtr
)
Parameters
HookType

Type of event that generated the call (M_MODIFIED_BUFFER).

EventId

Event identifier. You can pass the identifier to MdigGetHookInfo() to inquire about the hooked event.

UserDataPtr

User data pointer that was passed (as UserDataPtr) to MdigProcess().

Upon successful completion, the hook-handler function should return M_NULL. Note MFTYPE and MIL_DIG_HOOK_FUNCTION_PTR are reserved MIL predefined types for functions and data pointers.

If the hook-handler function modifies the buffer which triggred the hook-handler function, it will not be called again for that buffer.

UserDataPtr

Specifies the address of the user data that you want to make available to the hook-handler function. This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
GRAB NONE SEQUENCE START STOP WAIT INFINITE DEFAULT ASYNCHRONOUS SYNCHRONOUS CALIBRATION PROPAGATE AT EACH FRAME CALIBRATION PROPAGATE OFF CALIBRATION PROPAGATE ONCE TRIGGER FOR FIRST GRAB