| MIL 10 Reference
| Customize Help
| Save Settings

MdigAlloc


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 Iris GT
Partially supported on Matrox Morphis
Partially supported on Matrox Morphis QxT
Partially supported on Matrox Orion HD
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl
Partially supported on Matrox USB3 Vision driver (requires Update 19)
Partially 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
Previous
MdigControl
Synopsis
Allocate a digitizer.
Syntax
MIL_ID MdigAlloc(
MIL_ID SystemId, //in
MIL_INT DigNum, //in
MIL_CONST_TEXT_PTR DataFormat, //in
MIL_INT64 InitFlag, //in
MIL_ID *DigIdPtr //out
)
Description

This function allocates a digitizer on the specified system so that it can be used by subsequent MIL digitizer functions. A digitizer on the target system must be allocated to acquire data from a camera. Its device number specifies the first acquisition path of the digitizer. Its digitizer configuration format (DCF) establishes the number of acquisition paths used. One digitizer might use several acquisition paths depending on the input format of the camera. Use MdigGrab(), MdigGrabContinuous(), or MdigProcess() to grab.

Multiple digitizers can be allocated on the same system. If the system supports the possibility of independent acquisition paths, the digitizers' device number together with their DCF establishes if they represent dependent or independent acquisition path(s) on the system. If independent, grabs from these digitizers occur simultaneously. If dependent, grabs from these digitizers occur consecutively.

If multiple cameras of the same type are connected to the same acquisition path(s), instead of allocating multiple digitizers, you can allocate a single digitizer in the required format and then use MdigControl() with M_CHANNEL to switch between the cameras. M_CHANNEL selects the active input channel of the digitizer. The switch occurs upon the next call to MdigGrab(), MdigGrabContinuous(), or MdigProcess() with the digitizer. The default input channel is determined by the selected DCF (generally, M_CH0).

It is faster to allocate all the required digitizers first, perform the required grabs, and then free all the digitizers rather than allocate, grab, and then free each digitizer in succession.

Upon execution of this function, MIL ensures that the digitizer is present before allocating it and generates an error if it is not. Note that the corresponding hardware won't necessarily be programmed at the time of allocation.

When you have completely finished using a digitizer, you should free it, using MdigFree().

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
SystemId INQ

Specifies the identifier of the system on which to allocate the digitizer.

function map For specifying the system
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.

 † a
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().

 † a b c e f g h i j k l m n o p q r s
DigNum INQ

Specifies the number or string to identify the device to allocate for the digitizer.

This parameter can be set to one of the following:

function map For specifying the device number
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT

Specifies the default device number. This value is set during MIL installation and using the MILConfig utility. Note that the end-user can always change this value.

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

Specifies the camera (or device) to allocate for the digitizer.

(summarize)
† c o s
Parameters

Sets the camera identifier.

 † c o s
MIL system specific

When the InitFlag is set to M_GC_DEVICE_IP_ADDRESS, specify the camera's IP address. When the InitFlag is set to M_GC_DEVICE_USER_NAME, specify the camera's name. This macro is not available with any other InitFlag.

 † c s

Note that this macro can only be used when the InitFlag is set to M_GC_DEVICE_USER_NAME.

 † o
Collapse M_DEVn

Specifies the first acquisition path with which to associate a timing control unit (for example, a video capture controller) on your frame grabber, or the rank of your camera when dealing with a network camera (for example, a GigE Vision camera) or a USB3 Vision camera.

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

The value of n must be 0 since you can only grab from one digitizer at a time.

 † a b f n

The value of n must be from 0 to 31. This number represents the camera's index number. Note that this value can only be used when the InitFlag is set M_DEV_NUMBER.

 † c o s

The value of n must be from 0 to 3. The number of digitizers that can be allocated depends on the amount of bandwidth available using M_1394_BANDWIDTH().

 † e

The value of n must be either 0 or 1 for Matrox Morphis Dual. The value of n must be from 0 to 3 for Matrox Morphis Quad.

 † g

The value of n must be from 0 to 15 for Matrox Morphis QxT.

 † h

When dealing with Matrox Solios XA single analog, the value of n must be 0. When dealing with Matrox Solios XA quad analog, the value of n must be from 0 to 3. For details regarding allocation of specific independent digitizers, see the Allocating independent MIL digitizers on Matrox Solios section of Chapter 13: Matrox Solios.

 † l

The value of n must be from 0 to 3.

 † k q

When dealing with Matrox Radient eCL-SF, the value of n must be 0. When dealing with Matrox Radient eCL-DF or Matrox Radient eCL-DB, the value of n must be either 0 or 1. When dealing with Matrox Radient eCL-QB, the value of n must be 0 to 3.

 † j m p r
DataFormat INQ

Specifies the name of the digitizer configuration format (DCF) appropriate for your camera. Depending on the target system, different DCFs are supported.

One of the following values can be specified when allocating a digitizer for either a monochrome or a color camera:

function map For monochrome or color cameras
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_NULL

Specifies the data format is set by the digitizer allocated as the multicast master. Note that this value should only be used when allocating a multicast slave (using M_GC_MULTICAST_SLAVE).

For more information about multicasting and configuring your Matrox GigE Vision digitizer, refer to Chapter 4: Matrox GigE Vision driver.

(summarize)
† c s
Collapse MIL_TEXT("DCF File name") 1

Specifies the path and file name of the DCF (for example: "C:\mydirectory\myfile").

See the \Matrox Imaging\Drivers directory for the current list of supported formats.

When the path of the directory from which to retrieve the file is on a remote computer (under Distributed MIL), precede the path with "remote:///" (for example, "remote:///C:\mydirectory").

(summarize)
† b c f g h i j k l m n o p q r s
MIL system specific

Use the Matrox Intellicam program to create your own DCF file.

 † b c g h j k l m n o p q r s
Collapse MIL_TEXT("Image path[@n]") 1

Specifies the path of the directory from which to retrieve image files (or an AVI file) when allocating a simulated digitizer (for example, "C:\mydirectory\"), where n is the frame rate; the information in brackets is optional (for example, "C:\mydirectory\@30". For a list of image file formats supported, refer to MbufImport().

Note that, the X- and Y-size of each image in the path should be the same; otherwise, the X- and Y-size is taken from the first image and all subsequent images are either cropped to these dimensions, or expanded without zooming or stretching the original image, accordingly. In the latter case, portions of the previous image(s) might still be visible at the borders if the new image is smaller than the previous image.

When the path of the directory from which to retrieve the image files (or AVI file) is on a remote computer (under Distributed MIL), precede the path with "remote:///" (for example, "remote:///C:\mydirectory").

(summarize)
† a
Collapse MIL_TEXT("M_DEFAULT") 1

Specifies the default digitizer format. This value is set during MIL installation and using the MILConfig utility. Note that the end-user can always change this value.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse MIL_TEXT("M_DEFAULT_1394") 1

Specifies the format with the largest image dimensions possible with the highest available frame rate for the connected IEEE 1394-compliant camera. Note that when dealing with color cameras, this also selects the color data format.

(summarize)
† e
Collapse MIL_TEXT("M_xXy_data_FORMAT_7_z") 1

Specifies the string format for format 7 cameras, where x is SizeX in pixels, y is SizeY in pixels, data_FORMAT_7 is the image data format (for example, YUV, RGB...), and z is the format 7 mode (for example, "M_640X480_YUV411_FORMAT_7_1", "M_320X240_YUV422_FORMAT_7_2", and "M_1024X768_YUV_FORMAT_7_0" are accepted strings from one type of camera).

To use this string format, the total available bandwidth for a camera to communicate with a IEEE 1394 IIDC compliant digitizer should be divided amongst multiple cameras.

The InitFlag parameter must set the amount of bandwidth for the camera of the specified digitizer using M_1394_BANDWIDTH().

(summarize)
† e
Collapse MIL_TEXT("M_xXy_data[@z[FPS]]") 1

Specifies the string format, where x is SizeX in pixels, y is SizeY in pixels, data is the image data format (for example, YUV, RGB...), and z is the frame rate; the information in brackets is optional (for example, "M_640X480_YUV411@30FPS", "M_320x240_YUV422@7.5", and "M_1024X768_YUV" are accepted strings from one type of camera).

 † e
Collapse MIL_TEXT("SDCF File name") 1

Specifies the path and file name of the simulated DCF for use with a simulated digitizer (for example: "C:\mydirectory\myfile").

When the path of the directory from which to retrieve the SDCF file is on a remote computer (under Distributed MIL), precede the path with "remote:///" (for example, "remote:///C:\mydirectory").

(summarize)
† a

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

One of the following values can be specified when allocating a digitizer for a monochrome cameras:

function map For monochrome cameras
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse MIL_TEXT("M_CCIR") 1

Specifies a DCF for a CCIR, 768x576, 14.75 MHz, analog camera.

 † b g h l n
Collapse MIL_TEXT("M_RS170") 1

Specifies a DCF for an RS-170, 640x480, 12.27 MHz, analog camera.

(summarize)
† b e g h l n
MIL system specific

This value is available only if it is supported by the camera.

 † e

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

One of the following values can be specified when allocating a digitizer for a color camera:

[Matrox Solios eA/XA]

The following values are not supported on Matrox Solios XA single analog.

function map For color cameras
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse MIL_TEXT("M_NTSC") 1

Specifies a DCF for a composite NTSC 640x480, 12.27 MHz camera.

(summarize)
† b e g h n
MIL system specific

This value is available only if it is supported by the camera.

 † e
Collapse MIL_TEXT("M_NTSC_RGB") 1

Specifies a DCF for a component RGB, 640x480, 12.27 MHz camera. If your frame grabber has both a decoder and an RGB path, the RGB path will be used.

(summarize)
† l n
MIL system specific

Specifies a DCF for RGB format with an external synchronization signal.

 † l

Specifies a DCF for RGB format with a composite synchronization signal on green.

 † n
Collapse MIL_TEXT("M_NTSC_YC") 1

Specifies a DCF for a component NTSC Y/C (SVHS), 640x480, 12.27 MHz camera.

 † b g n
Collapse MIL_TEXT("M_PAL") 1

Specifies a DCF for a composite PAL 768x576, 14.75 MHz camera.

 † b g h n
Collapse MIL_TEXT("M_PAL_RGB") 1

Specifies a DCF for a component RGB, 768x576, 14.75 MHz camera. If your frame grabber has both a decoder and an RGB path, the RGB path will be used.

(summarize)
† l n
MIL system specific

Specifies a DCF for RGB format with an external synchronization signal.

 † l

Specifies a DCF for RGB format with a composite synchronization signal on green.

 † n
Collapse MIL_TEXT("M_PAL_YC") 1

Specifies a DCF for a PAL Y/C, 768x576, 14.75 MHz camera.

 † b g n

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

InitFlag INQ

Specifies the type of initialization to perform on the digitizer.

function map For specifying the type of initialization
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT

Specifies the default value.

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

The default value is M_DEV_NUMBER.

 † c o s

The default value is M_EMULATED.

 † a

The default value is M_1394_BANDWIDTH(), where the bandwidth is set to 100%.

 † e

Specifies that grabbing is permitted with the allocated digitizer.

 † i
Collapse

Specifies that the typical amount of bandwidth used by a camera communicating with MIL should be reduced by a given percentage. For example, allocating a digitizer for a camera that normally uses 40 Mbits/sec using MdigAlloc() with M_1394_BANDWIDTH() (50), results in 20 Mbits/sec being given to the camera.

If the 1394 bus can support 400 Mbits/sec, you could allocate up to 10 digitizers for cameras each with a bandwidth of 40 Mbits/sec, using MdigAlloc() with M_1394_BANDWIDTH() (100).

Note that this is available for use with 1394-compatible cameras that support Format7 formats.

(summarize)
† e
Parameters

Specifies the total amount of bandwidth for the digitizer being allocated, as a percentage.

 † e
Collapse M_DEV_NUMBER +

Specifies to allocate the digitizer for the camera with the specified device number. To specify the device number, use the DigNum paramater (M_DEVn).

(summarize)
† c o s
Collapse M_EMULATED

Specifies to allocate the digitizer as a simulated digitizer.

 † a
Collapse M_GC_DEVICE_IP_ADDRESS +

Specifies to allocate the digitizer for the camera at the specified IP address. To specify the IP address, use M_GC_CAMERA_ID().

(summarize)
† c s
Collapse M_GC_DEVICE_USER_NAME +

Specifies to allocate the digitizer for the camera with the specified device's user name. To specify the device's user name, use M_GC_CAMERA_ID().

(summarize)
† c o s
Collapse M_MINIMAL

Specifies that grabbing is not permitted with the allocated digitizer. When performing a grab, using either MdigGrab() or MdigProcess(), an error is generated. Up to 4 digitizers from M_DEV0 to M_DEV3 can be allocated simultaneously with this flag.

To receive a callback when a camera is connected or disconnected, use MdigHookFunction() with M_CAMERA_PRESENT.

(summarize)
† i
Combination constants that can be used alone or as combination constants for M_DEV_NUMBER; M_GC_DEVICE_IP_ADDRESS; M_GC_DEVICE_USER_NAME.

You can use one or more of the following values in combination with each other or with the above-mentioned values, to specify further details of the allocation of your camera.

function map For specifying further details
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse

Specifies which camera's device description file (XML) to download from the camera's manifest table. Note that, by default the MIL driver will always try to download a GenICam schema 1.1 compliant XML file. If no such file is present, then a GenICam schema 1.0 file is used. If manifest tables are not supported in the camera, then the single camera's device description file is downloaded. To skip this download, use M_GC_XML_DOWNLOAD_SKIP.

(summarize)
† c o s
Parameters

Specifies which XML to download from the camera's manifest table. This can be a value from 0 to 15.

 † c o s
Collapse M_GC_PACKET_SIZE_NEGOTIATION_SKIP

Specifies that the packet size negotiation task is skipped. Instead, MIL uses the GigE Vision digitizer's packet size register. If the packet size is too small or if the packet size is not supported by your digitizer, acquisition reliability will suffer. To force the packet size to a certain value, either store it in the DCF or use MdigControl() with M_GC_PACKET_SIZE.

(summarize)
† c s
Collapse M_GC_XML_DOWNLOAD_SKIP

Specifies that the camera's device description file (XML) should not be downloaded from the camera associated with the digitizer. The cached version, present in the MIL XML repository is used instead. If the camera's device description file is not present in the MIL XML repository or if the camera's device description file's name and/or size differs from the file in the MIL XML repository, the camera's device description file will be downloaded and this flag is ignored.

(summarize)
† c k o q s
Collapse M_GC_XML_FORCE_DOWNLOAD

Specifies that the camera's device description file (XML) should be downloaded from the camera associated with the digitizer. The cached version, present in the MIL XML repository is overwritten.

(summarize)
† c k o q s
Combination constants that can be used alone or as combination constants for M_DEV_NUMBER; M_GC_DEVICE_IP_ADDRESS; M_GC_DEVICE_USER_NAME.

You can use one of the following values on its own, or add it to the above-mentioned values, to specify whether the allocated digitizer will be a master, monitor, or slave digitizer in a multicast master-slave relationship.

For information about using IP multicast and configuring your Matrox GigE Vision digitizer, refer to the Using IP multicast section of Chapter 4: Matrox GigE Vision driver.

function map For specifying the multicasting master-slave relationship
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_GC_MULTICAST_MASTER

Specifies that the allocated digitizer will be the master digitizer in a multicasting master-slave or monitor relationship. Assigning the allocated digitizer as a master digitizer does not limit the digitizer in any way. In addition, as a multicast master digitizer, it is responsible to program the camera's destination stream and message channels (if supported) with an administratively scoped IP multicast address.

(summarize)
† c s
Collapse M_GC_MULTICAST_MONITOR

Specifies that the allocated digitizer will be a special type of slave digitizer (a monitor digitizer) in a multicast master-slave relationship. Assigning the allocated digitizer as a monitor digitizer limits its capabilities, since a monitor digitizer can only receive images and events (GenICam messages) from the camera and request packet resends, as necessary. In the master-slave relationship, only the multicast master digitizer has control. Therefore, the monitor digitizer's DCF that you pass MdigAlloc() should only contain X-size, Y-size, and pixel format information.

Image acquisition is only performed when the master digitizer (on another computer) initiates a grab and the GigE Vision camera streams the data. If the master has not initiated the image acquisition, then when using MdigGrab(), MdigGrabContinuous(), or MdigProcess() with the monitor digitizer, the monitor digitizer will wait until the master digitizer initiates the image acquisition.

Note that a monitor digitizer cannot be allocated if the GigE Vision camera is in chunk mode.

(summarize)
† c s
Collapse M_GC_MULTICAST_SLAVE

Specifies that the allocated digitizer will be a slave digitizer in a multicast master-slave relationship. Assigning the allocated digitizer as a slave digitizer limits its capabilities, since a slave digitizer can only read from the camera (using MdigInquireFeature()), receive images and events (GenICam messages) from the camera, and request packet resends. In the master-slave relationship, only the multicast master digitizer has control. Therefore, the slave digitizer's DCF that you pass to MdigAlloc() is not used. For best effect, set the DataFormat parameter to M_NULL.

Image acquisition is only performed when the master digitizer (on another computer) initiates a grab and the GigE Vision camera streams the data. If the master has not initiated the image acquisition, then when using MdigGrab(), MdigGrabContinuous(), or MdigProcess() with the slave digitizer, the slave digitizer will wait until the master digitizer initiates the image acquisition.

(summarize)
† c s
DigIdPtr

Specifies the address of the variable in which to write the digitizer identifier. Since the MdigAlloc() function also returns the digitizer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value
The returned value is the digitizer identifier if the allocation is successful. If allocation fails, M_NULL is returned.
Remark
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST DEFAULT DEVn NULL DEFAULT" DEFAULT 1394" xXy data FORMAT 7 z" xXy data[@z[FPS]]" CCIR" RS170" NTSC" NTSC RGB" NTSC YC" PAL" PAL RGB" PAL YC" DEFAULT DEV NUMBER EMULATED GC DEVICE IP ADDRESS GC DEVICE USER NAME MINIMAL GC PACKET SIZE NEGOTIATION SKIP GC XML DOWNLOAD SKIP GC XML FORCE DOWNLOAD GC MULTICAST MASTER GC MULTICAST MONITOR GC MULTICAST SLAVE