| Customize Help
| Save Settings

MdigGrab


Function Map
Syntax
Description
Parameters
- DigId
- DstContainerOrImageBufId
Table: For the identifier of the destination image buffer
Compilation information
Synopsis
Grab data from a camera into a buffer or container.
Syntax
void MdigGrab(
MIL_ID DigId, //in
MIL_ID DstContainerOrImageBufId //in
)
Description

This function uses the specified digitizer to acquire a frame of data and stores this data in the destination image buffer or container. 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.

By default, when you call MdigGrab(), the digitizer will grab the next valid frame. You can have the digitizer wait for a trigger signal to control when a frame of data is actually grabbed; to do so, set your digitizer to triggered mode using MdigControl() with M_GRAB_TRIGGER_STATE. For more information, see the Grabbing with triggers section of Chapter 25: Grabbing with your digitizer.

When acquiring data from a line-scan type of camera, the exact number of rows grabbed is determined by the DCF.

[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.

If you need to continuously grab and process the grabbed data, without dropping frames, use MdigProcess(). You can also use MdigGrabContinuous() to continuously acquire frames of data for use with a 2D or 3D display.

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.

DstContainerOrImageBufId

Specifies the identifier of the destination image buffer or container.

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

function map For the identifier of the destination image buffer
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize MIL color image buffer identifier

Specifies the identifier of a color destination image buffer with an M_IMAGE + M_GRAB attribute.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

If the grab buffer is smaller than the digitizer's frame size, the image buffer will be filled and all other data will be lost. If the grab buffer is larger than the digitizer's frame size, the buffer will be filled up to the digitizer's frame size. The rest of the buffer will remain untouched.

If you grab into a buffer from a digitizer that outputs data in a format suitable for a container, the first intensity component in the frame of data will be grabbed. If there is no intensity component, the first component that is not metadata will be grabbed.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

The destination buffer's depth can only be 8 bits per band.

 ‡ g h i u
U36

The destination buffer's depth can be 8 or 16 bits per band.

 ‡ c
M10		 o v

The width of the destination buffer must be at least 17 bytes. If not, an error will occur.

 ‡ l m

When dealing with color smart-cameras, the destination image buffer can only be a BGR packed buffer with a 32-bit color depth (allocated using MbufAllocColor() with M_IMAGE + M_GRAB + M_BGR32). When dealing with monochrome smart-cameras, you cannot grab into a MIL color image buffer.

 ‡ t
U28
Click to summarize MIL container identifier

Specifies the identifier of a container with an M_GRAB attribute.

When grabbing into a container for the first time, MIL will free all existing components and allocate the components required to store the current frame of data. MIL will typically reuse these automatically allocated components during subsequent grabs, unless you add or remove components from the container (in which case all components will be freed and new components will again be allocated for the grabbed data).

MIL will not grab into components of the container that you have allocated manually using MbufAllocComponent(), MbufCopyComponent(), or MbufCreateComponent().

In rare applications, you might configure your camera/3D sensor to transmit components of a different size or format with each grab. If there is any mismatch between the components from the previous grab and those required to store the current frame of data (for example, if the ordering, component type, or size has changed), all components will be automatically freed and new components will be allocated; the components will be assigned new identifiers. You can inquire the new buffer identifiers using MbufInquireContainer() with M_COMPONENT_ID.

If you need the buffer identifier of a component, and it is possible that the components might be reallocated, you should inquire the current buffer identifier after each grab.

(summarize)
‡ a c
U85		 o
Click to summarize MIL monochrome image buffer identifier

Specifies the identifier of a monochrome destination image buffer with an M_IMAGE + M_GRAB attribute.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

It is not possible to grab into a color-band child buffer (that is, a child buffer created from one band of a color parent buffer) when the parent buffer is packed.

When grabbing into an image buffer, if the grab destination buffer is smaller than the digitizer's frame size, the image buffer will be filled and all other data will be lost. If the grab destination buffer is larger than the digitizer's frame size, the buffer will be filled up to the digitizer's frame size. The rest of the buffer will remain untouched.

If you grab into a buffer from a digitizer that outputs data in a format suitable for a container, the first intensity component in the frame of data will be grabbed. If there is no intensity component, the first component that is not metadata will be grabbed.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

When using a color camera, the color data is first converted into YUV, and then the Y (luminance) component is stored in the buffer. The color space conversion is done in hardware.

 ‡ g h i k
M10		 l m t
U28		 u
U36		 y
U75

The destination buffer's depth can only be 8 bits per band.

 ‡ g h i u
U36

The destination buffer's depth can be 8 or 16 bits per band.

 ‡ c
M10		 j k
M10		 l m o p r
U27		 v y
U75		 aa

The width of the destination buffer must be at least 17 bytes. If not, an error will occur.

 ‡ l m

The destination buffer can only be an 8-bit monochrome buffer.

 ‡ t
U28
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
GRAB GRAB GRAB