MsysAlloc

See also

User Guide:

Attribute Cameras and video sources Controlling configuration DirectShow capture filter for MIL Distributed MIL on your local computer MIL system-specific information Mandatory allocations: allocating an application context and its systems Preparing computers for Distributed MIL Processing an image with a Processing FPGA Simulated digitizer Using the defaults

Reference:

MappAlloc MappAllocDefault MappInquire MdigAlloc MdispAlloc MsysControl MsysFree

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

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 Indio (Update 53 or Update 68) (w)

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

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

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 Matrox 4Sight GP/GPm with restrictions

Available on Matrox 4Sight-X with restrictions

Available on Non-Matrox computer with restrictions

Available on Matrox Supersight

Function map

Examples

3dcadregistration.cpp
3dgapandflush.cpp
3dplanarity.cpp
3dplanefit.cpp
3dprofilemetrology.cpp
advancedmeasurement.cpp
alphablending.cpp
ampouleandpackageinspection.cpp
autodetect.cpp
binarybasedcircledetection.cpp
blisterpackinspection.cpp
blobmerge.cpp
blobtransform.cpp
bottlecapandcontentinspection.cpp
bottlecapandlabelinspection.cpp
bottlecapinspection.cpp
calgenchessgrid.cpp
calibratedruler.cpp
calibrationfromlist.cpp
cameraonrobotarmcalibration.cpp
centeredlabelinspection.cpp
circlemeasurement.cpp
classcnncompletetrain.cpp
classprintedchar.cpp
classseafoodinspect.cpp
classsurfacesteel.cpp
classtreeensembletrain.cpp
codegrading.cpp
codetrain.cpp
colorrelativecalibration.cpp
cookiedetection.cpp
deadpixelcorrection.cpp
defectdetectionexample.cpp
depthfromfocus.cpp
dmiladdconstantmain.cpp
dmilbasic.cpp
dmilmdigprocesssharedmemory.cpp
dmilmultisystem.cpp
dmilobjecttracking.cpp
dmilremap.cpp
dmilsyncasyncmain.cpp
dmrcontextviewer.cpp
dmreditfontfile.cpp
dmrgenfontfile.cpp
dmrshowfontfile.cpp
dotspacing.cpp
exampleinterface.cpp
examplemanagerfor3d.cpp
extendeddepthoffield.cpp
fixturedcoderead.cpp
flatfieldcorrection.cpp
foodinspectioncereal.cpp
foodinspectionmango.cpp
gentl.cpp
isodpmgrading.cpp
m3ddisp.cpp
m3ddisp.cs
m3ddisp.vb
m3dgra.cpp
m3dgra.cs
m3dgra.vb
m3dreg.cpp
m3dreg.cs
m3dreg.vb
mapptrace.cpp
mapptrace.cs
mapptrace.vb
mclass.cpp
mclass.cs
mclass.vb
mdigcrossbar.cpp
mdiggrabmultiple.cpp
mdigprocess16vd.cpp
mdigprocess3d.cpp
mdigprocess3d.cs
mdigprocess3d.vb
mdigprocessmultiple.cpp
mdispwindowgtk.cpp
mdispwindowqt.cpp
meas2stepoverview.cpp
metrologyonblobs.cpp
milapplication.cs
milapplication.vb
milsamplegrabber.cpp
mimiirfilter.cpp
morphischannelswitchingdlg.cpp
morphology.cpp
mpmenu.cpp
mpprocessing.cpp
msysio.cpp
muart.cpp
multicameradisplay.cpp
multicameralasercalibration.cpp
multipledatamatrixcoderead.cpp
multiviewannotations.cpp
objectlocalization3d.cpp
pcbmodelmatching.cpp
productidentificationoasis.cpp
registeredgoldentemplate.cpp
scriptpreprocessing.cpp
semiocr.cpp
simplehdr.cpp
sphereinspection.cpp
stereocalibration.cpp
stereorectification.cpp
studinspection.cpp
superresolution.cpp
superresolutioncode.cpp
systemdetection.cpp
systemdetection.cs
systemdetection.vb
tirestringread.cpp
triggeroverethernet.cpp
variouscodereadings.cpp

Function Map

Table:

For specifying the application context

- SystemDescriptor

Table:

For specifying the type of system to allocate

- SystemNum

Table:	For specifying the number of the target board
+ combination:	For identifying the instance of the GenTL library to use

- InitFlag

Table:	For specifying the type of initialization setup
+ combination:	For specifying that the target board is identified using its user-defined name

- SysIdPtr

Return value

Remarks

Compilation information

Synopsis

Allocate a MIL system.

Syntax

MIL_ID MsysAlloc(

MIL_ID ContextAppId,	//in
MIL_CONST_TEXT_PTR SystemDescriptor,	//in
MIL_INT SystemNum,	//in
MIL_INT64 InitFlag,	//in
MIL_ID *SysIdPtr	//out

)

Description

This function allocates a MIL system so that it can be used by subsequent MIL functions. This function can allocate a MIL system, which consists of a Matrox imaging board (or third-party board), the Host CPU and memory, and any available graphics controller. Alternatively, this function can allocate a Host-type system, which consists of the Host CPU and memory, and any available graphics controller. Upon execution of this function, MIL ensures that it can open communication with the hardware associated with the system before allocating it, and generates an error if it cannot.

A system must be allocated before any buffers, displays, or digitizer can be allocated on it. Before allocating a system, an application must be allocated, using MappAlloc() or MappAllocDefault(). To use the default system, you must allocate it using M_SYSTEM_DEFAULT.

Note, upon allocation of an application, a default Host system is automatically allocated. Rather than using MsysAlloc() to allocate a Host system, you can use this default Host system, by specifying M_DEFAULT_HOST wherever a Host system identifier is required.

When you no longer need a particular system, free it using MsysFree().

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

ContextAppId

Specifies the identifier of the application context to use.

For specifying the application context
Value	Description
M_DEFAULT	Specifies the current application context.
Application Context Identifier	Specifies the application context identifier.

SystemDescriptor INQ

Specifies the type of system to allocate. Set this parameter to one of the following values:

For specifying the type of system to allocate
Value	Description		MIL system-specific tooltip (‡)
M_SYSTEM_CLARITY_UHD	Allocates a MIL Clarity UHD system.		‡														u U36
M_SYSTEM_CONCORD_POE	Allocates a MIL Concord POE system. Note that to use Matrox Concord PoE for acquisition, you must allocate and use a MIL GigE Vision system (M_SYSTEM_GIGE_VISION) instead; refer to information denoted for a GigE Vision system. You only need to allocate and use a MIL Concord PoE system (M_SYSTEM_CONCORD_POE) to use the other functionality on the board and to inquire about the board itself. So information in this reference, for use with a MIL Concord PoE system, is denoted MIL Concord PoE with ToE since it is typically only applicable to this model of the board. If the information is applicable to the Matrox Concord PoE base model, it will be explicitly specified. For more information, see the Using a MIL Concord PoE system with the Matrox Concord PoE base model section of the Matrox Concord PoE chapter in the MIL Hardware-specific Notes. (summarize) Allocates a MIL Concord POE system. (more details...)		‡																		z
M_SYSTEM_DEFAULT	Specifies the default system. 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 system. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
M_SYSTEM_GENTL	Allocates a MIL GenTL system. This allocation opens general communication with all the GenTL-compliant cameras (or devices) found on your subnet. (summarize) Allocates a MIL GenTL system. (more details...)		‡															v
M_SYSTEM_GIGE_VISION	Allocates a MIL GigE Vision system. This allocation opens general communication with all the GigE Vision-compliant cameras (or devices) found on your subnet (through one or more Gigabit Ethernet network adapters in your computer). (summarize) Allocates a MIL GigE Vision system. (more details...)		‡		c U25
M_SYSTEM_HOST	Specifies a Host system. Note that a Host system has no hardware-supported acquisition capabilities, however some acquisition capabilities are available when using a simulated digitizer, allocated using MdigAlloc() with M_EMULATED. (summarize) Specifies a Host system. (more details...)		‡	a
M_SYSTEM_INDIO	Allocates a MIL Indio system. If you need to capture images from a GigE Vision camera, you will need to allocate M_SYSTEM_GIGE_VISION as well. (summarize) Allocates a MIL Indio system. (more details...)		‡																w U53
M_SYSTEM_IRIS_GTR	Allocates a MIL Iris GTR system.		‡													t U28
M_SYSTEM_MORPHIS	Allocates a MIL Morphis system.		‡			g
M_SYSTEM_MORPHISQXT	Allocates a MIL Morphis QxT system.		‡				h
M_SYSTEM_ORION_HD	Allocates a MIL Orion HD system.		‡					i
M_SYSTEM_RADIENT	Allocates a MIL Radient system.		‡						j
M_SYSTEM_RADIENTCXP	Allocates a MIL Radient eV-CXP system.		‡							k M10
M_SYSTEM_RADIENTEVCL	Allocates a MIL Radient eV-CL system.		‡												r U27							aa
M_SYSTEM_RADIENTPRO	Allocates a MIL RadientPro CL system.		‡											p
M_SYSTEM_RAPIXOCXP	Allocates a MIL Rapixo CXP system.		‡																	y U75
M_SYSTEM_SOLIOS	Allocates a MIL Solios system.		‡								l	m
M_SYSTEM_USB3_VISION	Allocates a MIL USB3 Vision system. This allocation opens general communication with all the USB3 Vision-compliant cameras (or devices) connected to your computer. (summarize) Allocates a MIL USB3 Vision system. (more details...)		‡										o
MIL_TEXT("dmilpcie://[Passkey:]RemoteComputerName[:Port]/MILSystemType") ¹	[This is only applicable to Matrox Supersight platform] Allocates a DMIL remote system on a remote Matrox Supersight SHB that will communicate with the local SHB, using the PCIe protocol. To allocate a DMIL remote system on a Matrox Supersight SHB, that SHB must have a valid DMIL installation and be in the same Matrox Supersight as the local SHB. When specifying the string that indicates the remote SHB: If required, replace [Passkey] with the passkey for the remote SHB. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the remote system, omit the passkey and the ":" that follows it. Replace RemoteComputerName with the remote SHB's name. This protocol does not support connections to "localhost" or to IP addresses. If required, replace [Port] with the port that the local computer should access on the remote computer to initiate new connections, unless the default server connection port is appropriate; in which case, omit the port number and the ":" that follows it. Replace MILSystemType with any valid MIL system type listed in this table. If the remote system is the Host CPU of another SHB (without a Matrox frame grabber installed) use M_SYSTEM_HOST. The "://" and "/" must be included. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 48: Distributed MIL. (summarize) [This is only applicable to Matrox Supersight platform] Allocates a DMIL remote system on a remote Matrox Supersight SHB that will communicate with the local SHB, using the PCIe protocol. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27		u U36	v	w U53	y U75	z	aa
		MIL system specific
		Note that to allocate this system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, click on the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 48: Distributed MIL.	‡					i									u U36
MIL_TEXT("dmilshm://[Passkey:]localhost[:Port]/MILSystemType") ¹	Allocates a DMIL remote system for a separate process on the local computer, using the DMIL SHM protocol. This protocol allows you to communicate between a client and server process on the same computer using shared memory. To allocate a DMIL remote system on a computer, that computer must have a valid DMIL installation. When specifying the string that indicates the local computer: If required, replace [Passkey] with the passkey for the DMIL server on the local computer. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the DMIL server, omit the passkey and the ":" that follows it. Following "localhost:", replace [Port] with the port that the local computer should access to initiate new connections with the DMIL server, unless the default connection port is the listening port of the DMIL server; in which case, omit the port number and the ":" that follows it. Replace MILSystemType with any valid MIL system type listed in this table, such as M_SYSTEM_MORPHIS. The "://" and "/" must be included. The DMIL SHM protocol only supports connections to localhost. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 48: Distributed MIL. (summarize) Allocates a DMIL remote system for a separate process on the local computer, using the DMIL SHM protocol. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
		MIL system specific
		Note that to allocate this system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, click on the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 48: Distributed MIL.	‡					i									u U36
MIL_TEXT("dmiltcp://[Passkey:]RemoteComputerName[:Port]/MILSystemType") ¹	Allocates a DMIL remote system on a remote or local computer, using the TCP/IP protocol. To allocate a DMIL remote system on a computer, that computer must have a valid DMIL installation. When specifying the string that indicates the remote computer (or local computer for a DMIL server also running locally): If required, replace [Passkey] with the passkey for the remote computer. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the remote computer, omit the passkey and the ":" that follows it. If you are attempting to connect to a local computer, specify the passkey for the DMIL server on the local computer. Replace RemoteComputerName with the remote computer's name or IP address; MIL supports both IPv4 and IPv6 addresses. A typical IPv4 string has the format n.n.n.n, where n is a number between 0 and 255. A typical IPv6 string has the format x:x:x:x:x:x:x:x, where x is a hexadecimal number between 0000 and FFFF. If you are supplying an IPv6 address, you must use square brackets to separate the address from the port. If you are attempting to connect to the local computer, set this to localhost. If required, replace [Port] with the port that the local computer should access on the remote computer to initiate new connections, unless the default connection port is the listening port of the DMIL server on the remote computer; in which case, omit the port number and the ":" that follows it. If you are attempting to connect to a local computer, specify the listening port of the DMIL server on the local computer. Replace MILSystemType with any valid MIL system type listed in this table, such as M_SYSTEM_SOLIOS. The "://" and "/" must be included. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 48: Distributed MIL. (summarize) Allocates a DMIL remote system on a remote or local computer, using the TCP/IP protocol. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	w U53	y U75	z	aa
		MIL system specific
		Note that to allocate this system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, click on the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 48: Distributed MIL.	‡					i									u U36

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

SystemNum INQ

Specifies the number (rank) or user-defined name of the target board of the specified system type. This parameter can be set to one of the following:

For specifying the number of the target board

Value

Description

MIL system-specific
tooltip (‡)

M_DEFAULT

Specifies the default board.

‡

c
M10

k
M10

r
U27

t
U28

u
U36

w
U53

y
U75

M_PTR_TO_MIL_INT(

MIL_CONST_TEXT_PTR BoardName

)

Casts the address of the string identifying the user-defined board name, from a MIL_CONST_TEXT_PTR to a MIL_INT.

(summarize)

Casts the address of the string identifying the user-defined board name, from a MIL_CONST_TEXT_PTR to a MIL_INT.

(more details...)

‡

Parameters

BoardName

This parameter specifies the string to cast.

‡

MIL_TEXT("BoardIdentifierString") ¹

Specifies the user-defined name of the board. When allocating the board with a name, the InitFlag must be set to M_DEVICE_NAME. The name must also have been previously assigned and written to the board. Typically, this is done from a different executable that allocates a system for the board using M_DEVn, and then assigns a name to the board using MsysControl() with M_DEVICE_NAME.

‡

M_DEVn +

Specifies the device number (rank) of the board. You can set n to one of the following values: 0 <= n <=15.

(summarize)

Specifies the device number (rank) of the board.

(more details...)

‡

c
M10

k
M10

r
U27

t
U28

u
U36

w
U53

y
U75

MIL system specific

Note that only M_DEV0 is valid.

‡

c
M10

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

Combination value for M_DEVn.

You can add the following value to the above-mentioned value to identify the GenTL library for which to allocate a MIL GenTL system.

All third-party proprietary GenTL libraries installed on your computer are sorted and indexed by MIL. Use the GenTL Producer index number to identify the library that your MIL system should use to communicate with the hardware devices on the specified transportation layer. These libraries are indexed and sorted for reference by MIL (the GenTL Consumer). In all cases, the same number and type of libraries should be installed on every computer that will run your application; the order in which they are installed, however, is not important.

To determine the number of GenTL libraries installed on your computer, use MappInquire() with M_GENTL_PRODUCER_COUNT or use the General Default Values page of the MILConfig utility.

For identifying the instance of the GenTL library to use

Combination value

Description

MIL system-specific
tooltip (‡)

M_GENTL_PRODUCER(

MIL_INT IndexValue

)

Specifies the GenTL Producer (library) for which to allocate this MIL GenTL system.

(summarize)

Specifies the GenTL Producer (library) for which to allocate this MIL GenTL system.

(more details...)

‡

Parameters

IndexValue

Specifies the index of the GenTL Producer.

‡

0 <= Value <= 127

Specifies the index.

‡

InitFlag INQ

Specifies how to perform the allocation.

To specify the type of initialization to perform on the selected system, set this parameter to one of the following:

For specifying the type of initialization setup
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	w U53	y U75	z	aa
		MIL system specific
		Same as M_COMPLETE.	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36		w U53	y U75	z	aa
		Same as M_MIXED.	‡															v
M_CL	Specifies to initialize Camera Link transport layer technology.		‡															v
M_COMPLETE +	Specifies to initialize the system completely; the system is initialized to its default state and any required resident software is downloaded. At least one complete initialization is necessary after you power-up your system. (summarize) Specifies to initialize the system completely; the system is initialized to its default state and any required resident software is downloaded. (more details...)		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36		w U53	y U75	z	aa
M_CXP	Specifies to initialize CoaXPress transport layer technology.		‡															v
M_GEV	Specifies to initialize Ethernet transport layer technology.		‡															v
M_MIXED	Specifies to initialize the transport layer technology specified by the GenTL Producer (library).		‡															v
M_U3V	Specifies to initialize USB transport layer technology.		‡															v

Combination value that can be used alone or as combination value for M_COMPLETE.

You can use the following value on its own, or add it to the above-mentioned value, to set that the target board is identified using its user-defined name.

This InitFlag is also available for the Matrox Concord PoE base model.

For specifying that the target board is identified using its user-defined name
Value	Description	MIL system-specific tooltip (‡)
M_DEVICE_NAME	Specifies that the SystemNum parameter identifies the target board using its user-defined name.	‡	z

SysIdPtr

Specifies the address of the variable in which to write the system identifier. Since the MsysAlloc() function also returns the system 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 system 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 MsysAlloc(), ensure that the call is not made from the DllMain() function, because MsysAlloc() might load a required DLL and you cannot load a DLL from DllMain(). If necessary, call MsysAlloc() from an initialization function in your DLL instead.

Compilation information

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