MdigProcess

This function uses the specified digitizer to acquire frames of data and stores them sequentially in a list of image buffers or a list of containers. It also hooks a user-defined function to the modification of any buffers/containers in the specified list. The user-defined function is therefore called every time a new frame is grabbed.

When grabbing an image, you should use an image buffer as a destination. When grabbing any other type of data (such as 3D data), you should use a container as a destination. You can determine what type of MIL object the digitizer is designed to grab into using MdigInquire() with M_TARGET_BUFFER_OBJECT.

If set synchronously, MdigProcess() will block the thread until the list of sequential grabs has completed. If set asynchronously, the buffers/containers 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, after a predefined number of grabs occur, or when a stop instruction is explicitly given. In the latter two cases, grabbing occurs in a round robin fashion; buffers/containers are filled with the grabbed data typically in the order they are stored in the list, wrapping around to the first buffer/container in the list once the last buffer/container in the list is filled.

The index of the modified buffer/container can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_INDEX. The MIL identifier of the modified buffer/container can be inquired using MdigGetHookInfo() with M_MODIFIED_BUFFER + M_BUFFER_ID. To identify whether the modified buffer/container (that is, the current frame) is corrupt (for example, because a packet was not received successfully), use MdigGetHookInfo() with M_CORRUPTED_FRAME.

Once a frame of data is grabbed into a buffer/container, MIL will not grab into that buffer/container again until the hook function has finished processing it. Once the hook function finishes executing, the buffer/container becomes available for MIL to grab into it. If all buffers/containers are filled with data and are waiting to be processed by the hook function, MIL waits for the next available buffer/container (typically the next buffer/container in the list) before grabbing another frame of data.

If the average time it takes to process a frame of data is greater than the frame rate of a camera, frames will eventually be missed. You can determine how many of the processing buffers are currently available using MdigInquire() with M_PROCESS_PENDING_GRAB_NUM.

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. Once the stop instruction is issued, no more frames will be grabbed. Buffers/containers that store unprocessed frames are processed before the original calling thread continues, unless the stop instruction is issued by calling MdigProcess() from within the hook-handler function itself (in which case, processing is completed while the original calling thread continues).

By default, buffers/containers are processed sequentially, in the order into which grabbed; a single instance of the hooked user-defined function will run on a single thread, processing one buffer/container at a time. When running on a computer with multiple CPU cores, you can have the grabbed buffers/containers 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.

If you are grabbing from multiple cameras simultaneously with the hook function executing in single-threaded mode, each instance of MdigProcess() will use its own thread to execute an instance of the hooked function. Additionally, many MIL functions are transparently multi-threaded. These factors can combine to generate a large number of threads, potentially slowing down your application. Since having the hook function execute in multi-threaded mode can multiply the number of threads generated by the number of physical CPU cores in your computer (or, optionally, the number of threads that you specify with M_MULTI_THREAD), it is often more efficient to have the hook function execute in single-threaded mode. If you are considering multi-threaded mode, you should benchmark your application under real-world conditions before making a final decision.

When processing with the hook function executing in multi-threaded mode, it is possible for buffers/containers to be grabbed and processed in a different order than they are stored in the list because they are processed at different rates. For example, if the list contains 3 buffers and all of them are being processed, it is possible that processing will finish on the second buffer in the list before the first buffer in the list. In this case, MIL will grab into the second buffer and cue it for processing instead of waiting for the first buffer to become available.

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.

Note that if the camera is in triggered mode, you should not also use the digitizer in triggered mode.

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