Click here to show toolbars of the Web Online Help System: show toolbars
 

| Customize Help
| Save Settings

MdigProcess


Function Map
Syntax
Description
Parameters
- DigId
- DestImageArrayPtr
- ImageCount
- Operation
Table: For specifying the type of operation to perform
+ combination: For M_STOP
+ combination: For M_SEQUENCE
+ combination: For M_START
- OperationFlag
Table: For controlling the order in which processing occurs
+ combination: For how the camera calibration context is propagated
+ combination: For specifying whether to clear the ROI of the previous grab
+ combination: For only controlling the grab of the first frame with a trigger
- HookHandlerPtr
- UserDataPtr
Compilation information
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-out
)
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
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize 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 t u
Click to summarize 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 t u
Click to summarize 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 t u
Combination value 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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 t u
Combination value 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize
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 t u
Parameters
n

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 value 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize

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 t u
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 t u
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 t u
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 t u
OperationFlag

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

function map For controlling the order in which processing occurs
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize 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 t u
Click to summarize 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 t u
Click to summarize 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 t u
Combination values for M_ASYNCHRONOUS; M_SYNCHRONOUS.

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

function map For how the camera calibration context is propagated
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_CALIBRATION_PROPAGATE_AT_EACH_FRAME

Specifies that the camera 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)
‡ a b c e f g h i j k l m n o p q r s t u
Click to summarize M_CALIBRATION_PROPAGATE_OFF

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

(summarize)
‡ a b c e f g h i j k l m n o p q r s t u
Click to summarize M_CALIBRATION_PROPAGATE_ONCE

Specifies that before starting image acquisition, the camera 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 camera calibration state of the original parent buffer. The child buffer will have its own local camera calibration information that will not affect its parent buffer.

Since the camera 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 camera calibration context settings; the camera calibration context re-associated with the digitizer will not be associated with the modified buffer afterwards.

This is the default value.

(summarize)
‡ a b c e f g h i j k l m n o p q r s t u
Combination values for M_ASYNCHRONOUS; M_SYNCHRONOUS.

You can add one of the following values to the above-mentioned values to specify whether to keep or remove the ROI.

function map For specifying whether to clear the ROI of the previous grab
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_REGION_DELETE_AT_EACH_FRAME

Specifies that any ROI associated with the modified buffer in the hook function is deleted immediately before calling the user-defined hook function. This is equivalent to calling MbufSetRegion() to clear the ROI of the modified buffer after every grab. This is less error-prone, but might slow down the user-defined hook function's execution slightly.

Note that this value is only supported if you have installed the MIL 10 Processing Pack 2 update.

(summarize)
‡ a b c e f g h i j k l m n o p q r s t u
Click to summarize M_REGION_KEEP

Specifies that any ROI associated with the modified buffer is left as is.

Note that this value is only supported if you have installed the MIL 10 Processing Pack 2 update.

This is the default value.

(summarize)
‡ a b c e f g h i j k l m n o p q r s t u
Combination value 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 controlling the grab of the first frame with a trigger
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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 t u
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 REGION DELETE AT EACH FRAME REGION KEEP TRIGGER FOR FIRST GRAB