MdigAlloc

See also

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Partially supported on:

Partially supported on Host system (a)

Partially supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Partially supported on Matrox Morphis (g)

Partially supported on Matrox Morphis QxT (h)

Partially supported on Matrox Orion HD (i)

Partially supported on Matrox Radient eCL (j)

Partially supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Partially supported on Matrox Solios eA/XA (l)

Partially supported on Matrox Solios ecl/xcl/ev-cl (m)

Partially supported on Matrox USB3 Vision driver (Update 19) (o)

Partially supported on Matrox RadientPro-CL (Update 7) (p)

Partially supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Partially supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Partially supported on Matrox Clarity UHD (Update 36 or 76) (u)

Partially supported on Matrox GenTL driver (Update 34) (v)

Partially supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Partially supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

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/GPm

Available on Matrox Supersight

Function map

Examples

actiontrigger.cpp
autodetect.cpp
blobmerge.cpp
classseafoodinspect.cpp
classsurfacesteel.cpp
depthfromfocus.cpp
dmilmdigprocesssharedmemory.cpp
dmilmultisystem.cpp
dmilobjecttracking.cpp
extendeddepthoffield.cpp
fixturingusingblob.cpp
flatfieldcorrection.cpp
gentl.cpp
interactiveexample.cpp
irisgtrlensfocus.cpp
m3ddisp.cpp
m3ddisp.cs
m3ddisp.vb
mapptrace.cpp
mapptrace.cs
mapptrace.vb
mclass.cpp
mclass.cs
mclass.vb
mdiggrabmultiple.cpp
mdighandler.cpp
mdigitizer.cpp
mdigprocess16vd.cpp
mdigprocess3d.cpp
mdigprocess3d.cs
mdigprocess3d.vb
mdigprocessmultiple.cpp
mdispgtkapp.cpp
mdispmfc.cpp
mdispoverlay.cpp
mdispoverlay.cs
mdispoverlay.vb
mdispqtapp.cpp
mdispwindowgtk.cpp
mdispwindowqt.cpp
milapplication.cs
milapplication.vb
milgige.cpp
mimdeinterlace.cpp
mimdeinterlace.cs
mimdeinterlace.vb
morphischannelswitchingdlg.cpp
multicamera.cpp
multicastmaster.cpp
multicastmonitor.cpp
multicastslave.cpp
scriptpreprocessing.cpp

Function Map

- SystemId

Table:

For specifying the system

- DigNum

Table:

For specifying the device number

- DataFormat

Table:	For monochrome or color cameras, or 3D sensors
Table:	For monochrome cameras
Table:	For color cameras
Table:	For simulated digitizers

- InitFlag

Table:	For specifying the type of initialization
+ combination:	For specifying further details
+ combination:	For specifying the multicasting master-slave relationship

- DigIdPtr

Return value

Remarks

Compilation information

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 acquisition path to allocate for the digitizer. Use MdigGrab(), MdigGrabContinuous(), or MdigProcess() to grab.

Typically, each digitizer only uses a single acquisition path. However, in some cases a digitizer might use several acquisition paths depending on the input format of the camera. Its digitizer configuration format (DCF) establishes the number of acquisition paths used.

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.

For specifying the system
Value	Description	MIL system-specific tooltip (‡)
M_DEFAULT_HOST	Specifies the default Host system of the current MIL application.	‡	a
MIL system identifier	Specifies a valid system identifier, previously allocated using MsysAlloc().	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	y U75	aa

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:

For specifying the device number
Value	Description		MIL system-specific tooltip (‡)
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) Specifies the default device number. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	y U75	aa
M_GC_CAMERA_ID( MIL_TEXT_PTR CameraIdentifierString )	Specifies the camera (or device) to allocate for the digitizer. (summarize) Specifies the camera (or device) to allocate for the digitizer. (more details...)		‡		c M10								o					v
		Parameters
		CameraIdentifierString Sets the camera identifier.	‡		c M10								o					v
		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_NAME, specify the camera's name. This macro is not available with any other InitFlag.	‡		c M10													v
		Note that this macro can only be used when the InitFlag is set to M_GC_DEVICE_NAME.	‡										o
M_DEVn	Specifies which acquisition path on your frame grabber, or which camera by rank when dealing with a grabberless interface camera (for example, a GigE Vision or USB3 Vision camera), to allocate for the digitizer. You can inquire the total number of possible independent acquisition paths on a system using MsysInquire() with M_DIGITIZER_NUM. (summarize) Specifies which acquisition path on your frame grabber, or which camera by rank when dealing with a grabberless interface camera (for example, a GigE Vision or USB3 Vision camera), to allocate for the digitizer. (more details...)		‡	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 value of n must be from 0 to 31. This number represents the index of the simulated digitizer.	‡	a
		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 M10								o					v
		The value of n must be 0 for Matrox Iris GTR.	‡													t U28
		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 eA/XA single analog, the value of n must be 0. When dealing with Matrox Solios eA/XA Dingle analog, the value of n must be 0. When dealing with Matrox Solios eA/XA Quad analog, the value of n must be from 0 to 3. If you are allocating a digitizer for a camera that uses multiple acquisition paths, specify the index of the first acquisition path to allocate. For details regarding allocation of specific independent digitizers, see the Allocating independent MIL digitizers on Matrox Solios section of the Matrox Solios chapter in the MIL Hardware-specific Notes.	‡								l
		The value of n must be from 0 to 3. If you are allocating a digitizer for a camera that uses multiple connections, specify the index of the connector on your board used for the master connection. The other connections used for the camera are associated with the digitizer automatically.	‡							k M10									y U75
		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 U27					aa

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, or a 3D sensor:

For monochrome or color cameras, or 3D sensors
Value	Description		MIL system-specific tooltip (‡)
MIL_TEXT("M_DEFAULT") ¹	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) Specifies the default digitizer format. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	y U75	aa
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 the Matrox GigE Vision driver chapter in the MIL Hardware-specific Notes. (summarize) Specifies the data format is set by the digitizer allocated as the multicast master. (more details...)		‡		c M10													v
MIL_TEXT("DCF File name") ¹	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) Specifies the path and file name of the DCF (for example: "C:\mydirectory\myfile"). (more details...)		‡		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
		Use the Matrox Intellicam program to create your own DCF file.	‡		c M10	g	h		j	k M10	l	m	o	p	r U27			v	y U75	aa

¹ 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:

For monochrome cameras
Value	Description	MIL system-specific tooltip (‡)
MIL_TEXT("M_CCIR") ¹	Specifies a DCF for a CCIR, 768x576, 14.75 MHz, analog camera.	‡	g	h	l
MIL_TEXT("M_RS170") ¹	Specifies a DCF for an RS-170, 640x480, 12.27 MHz, analog camera.	‡	g	h	l

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

For color cameras
Value	Description		MIL system-specific tooltip (‡)
MIL_TEXT("M_NTSC") ¹	Specifies a DCF for a composite NTSC 640x480, 12.27 MHz camera.		‡	g	h
MIL_TEXT("M_NTSC_RGB") ¹	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) Specifies a DCF for a component RGB, 640x480, 12.27 MHz camera. (more details...)		‡			l
		MIL system specific
		Specifies a DCF for RGB format with an external synchronization signal.	‡			l
MIL_TEXT("M_NTSC_YC") ¹	Specifies a DCF for a component NTSC Y/C (SVHS), 640x480, 12.27 MHz camera.		‡	g
MIL_TEXT("M_PAL") ¹	Specifies a DCF for a composite PAL 768x576, 14.75 MHz camera.		‡	g	h
MIL_TEXT("M_PAL_RGB") ¹	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) Specifies a DCF for a component RGB, 768x576, 14.75 MHz camera. (more details...)		‡			l
		MIL system specific
		Specifies a DCF for RGB format with an external synchronization signal.	‡			l
MIL_TEXT("M_PAL_YC") ¹	Specifies a DCF for a PAL Y/C, 768x576, 14.75 MHz camera.		‡	g

¹ 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 simulated digitizer:

For simulated digitizers
Value	Description	MIL system-specific tooltip (‡)
MIL_TEXT("Image path[@n]") ¹	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) 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"). (more details...)	‡	a
MIL_TEXT("M_2D_SIMULATOR") ¹	Specifies to use MIL's internal 2D pattern generator with the simulated digitizer. This generates a series of images of the Matrox Imaging logo, which can be used to simulate acquisition without the need to create sample images. The generated images are 640x480, in the 8-bit RGB color format. (summarize) Specifies to use MIL's internal 2D pattern generator with the simulated digitizer. (more details...)	‡	a
MIL_TEXT("M_3D_SIMULATOR") ¹	Specifies to use MIL's internal 3D pattern generator with the simulated digitizer. This generates a meshed point cloud of the Matrox Imaging logo, which can be used to simulate acquisition without the need to create sample point clouds. (summarize) Specifies to use MIL's internal 3D pattern generator with the simulated digitizer. (more details...)	‡	a
MIL_TEXT("SDCF File name") ¹	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) Specifies the path and file name of the simulated DCF for use with a simulated digitizer (for example: "C:\mydirectory\myfile"). (more details...)	‡	a

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

For specifying the type of initialization
Value	Description		MIL system-specific tooltip (‡)
M_DEFAULT	Specifies the default value. (summarize) Specifies the default value. (more details...)		‡	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 default value is M_DEV_NUMBER.	‡		c M10								o					v
		The default value is M_EMULATED.	‡	a
		Specifies that grabbing is permitted with the allocated digitizer.	‡					i									u U36
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) Specifies to allocate the digitizer for the camera with the specified device number. (more details...)		‡		c M10								o					v
M_EMULATED	Specifies to allocate the digitizer as a simulated digitizer.		‡	a
M_GC_DEVICE_IP_ADDRESS +	Specifies to allocate the digitizer for theMdigAlloc.xml camera at the specified IP address. To specify the IP address, use M_GC_CAMERA_ID(). (summarize) Specifies to allocate the digitizer for theMdigAlloc. (more details...)		‡		c M10													v
M_GC_DEVICE_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) Specifies to allocate the digitizer for the camera with the specified device's user name. (more details...)		‡		c M10								o					v
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. To receive a callback when a camera is connected or disconnected, use MdigHookFunction() with M_CAMERA_PRESENT. (summarize) Specifies that grabbing is not permitted with the allocated digitizer. (more details...)		‡					i									u U36
		MIL system specific
		Up to 8 digitizers from M_DEV0 to M_DEV7 can be allocated simultaneously with this type of initialization.	‡														u U36
		Up to 4 digitizers from M_DEV0 to M_DEV3 can be allocated simultaneously with this type of initialization.	‡					i

Combination values that can be used alone or as combination values for M_DEV_NUMBER; M_GC_DEVICE_IP_ADDRESS; M_GC_DEVICE_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.

For specifying further details
Value	Description		MIL system-specific tooltip (‡)
M_GC_MANIFEST_ENTRY( MIL_INT EntryNum )	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) Specifies which camera's device description file (XML) to download from the camera's manifest table. (more details...)		‡	c M10	o	v
		Parameters
		EntryNum Specifies which XML to download from the camera's manifest table. This can be a value from 0 to 15.	‡	c M10	o	v
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) Specifies that the packet size negotiation task is skipped. (more details...)		‡	c M10
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) Specifies that the camera's device description file (XML) should not be downloaded from the camera associated with the digitizer. (more details...)		‡	c M10
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) Specifies that the camera's device description file (XML) should be downloaded from the camera associated with the digitizer. (more details...)		‡	c M10

Combination values that can be used alone or as combination values for M_DEV_NUMBER; M_GC_DEVICE_IP_ADDRESS; M_GC_DEVICE_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 the Matrox GigE Vision driver chapter in the MIL Hardware-specific Notes.

For specifying the multicasting master-slave relationship
Value	Description	MIL system-specific tooltip (‡)
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) Specifies that the allocated digitizer will be the master digitizer in a multicasting master-slave or monitor relationship. (more details...)	‡	c M10
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) Specifies that the allocated digitizer will be a special type of slave digitizer (a monitor digitizer) in a multicast master-slave relationship. (more details...)	‡	c M10
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) Specifies that the allocated digitizer will be a slave digitizer in a multicast master-slave relationship. (more details...)	‡	c M10

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

If you are creating a DLL that includes a call to MdigAlloc(), ensure that the call is not made from the DllMain() function, because MdigAlloc() might load a required DLL and you cannot load a DLL from DllMain(). If necessary, call MdigAlloc() from an initialization function in your DLL instead.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.