MappAlloc

See also

User Guide:

2D graphics context Controlling configuration MIL Function Development module MIL functions and constants in Python Mandatory allocations: allocating an application context and its systems Matrox Profiler and trace logs Monitoring configuration Multi-threading Supported hardware acceleration modes Transparent multi-core use Using MIL add-on to Visual Studio Using the defaults

Reference:

M3dmapDraw MappControl MappGetError MdispControl

Availability

Available in MIL-Lite

Available in MIL

Available on Windows with restrictions

Available on Linux with restrictions

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

3dcadregistration.cpp
3dgapandflush.cpp
3dmodelheightdefect.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
caninspection.cpp
centeredlabelinspection.cpp
circlemeasurement.cpp
classcnncompletetrain.cpp
classprintedchar.cpp
classseafoodinspect.cpp
classsurfacesteel.cpp
classtreeensembletrain.cpp
codedetect.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
extendeddepthoffield.cpp
fixturedcoderead.cpp
fixturingusingblob.cpp
flatfieldcorrection.cpp
foodinspectioncereal.cpp
foodinspectionmango.cpp
gearinspection.cpp
gentl.cpp
isodpmgrading.cpp
laserprofilemetrologyanalysis.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
mbufcreate.cpp
mbufcreate.cs
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
measoverviewexample.cpp
measuredfeaturesoverview.cpp
mechanicalpartscan.cpp
metrologyonblobs.cpp
milapplication.cs
milapplication.vb
milsamplegrabber.cpp
mimiirfilter.cpp
morphischannelswitchingdlg.cpp
morphology.cpp
msysio.cpp
muart.cpp
multicameradisplay.cpp
multicameralasercalibration.cpp
multipledatamatrixcoderead.cpp
multiprocessing.cpp
multiviewannotations.cpp
objectlocalization3d.cpp
pcbmodelmatching.cpp
pointcloudprojection.cpp
pointconstructions.cpp
productidentificationoasis.cpp
registeredgoldentemplate.cpp
scriptpreprocessing.cpp
semiocr.cpp
simple3dbinpicking.cpp
simple3dstitching.cpp
simplehdr.cpp
sphereinspection.cpp
stereocalibration.cpp
stereorectification.cpp
studinspection.cpp
superresolution.cpp
superresolutioncode.cpp
systemdetection.cpp
systemdetection.cs
systemdetection.vb
tirestringread.cpp
tolerancesoverview.cpp
triggeroverethernet.cpp
variouscodereadings.cpp

Function Map

Table:

For specifying the cluster manager

- InitFlag

Table:	For specifying the type of initialization
+ combination:	For specifying the hardware-acceleration display mode
+ combination:	For specifying a cluster node value

- ContextAppIdPtr

Return value

Remarks

Compilation information

Synopsis

Allocate a MIL application context.

Syntax

MIL_ID MappAlloc(

MIL_CONST_TEXT_PTR ServerDescription,	//in
MIL_INT64 InitFlag,	//in
MIL_ID *ContextAppIdPtr	//out

)

Description

This function allocates a MIL application context. A MIL application context must be allocated prior to using any other MIL functions.

In multi-thread environments, an application context is allocated in the main thread and is shared by all threads. Mapp...() function calls from any thread apply to all threads, unless specifically localized to that thread by specifying M_THREAD_CURRENT when calling the function.

In addition, a default 2D graphics context is also allocated upon allocation of a MIL application context. You can use this default 2D graphics context in MIL graphic function calls by specifying M_DEFAULT wherever a 2D graphics context identifier is required. In multi-thread applications, a default 2D graphics context is allocated for each thread to avoid inter-thread interference.

When allocating a new MIL application context that will be used in a Distributed MIL monitoring configuration (either the monitoring application or publishing application), you should specify the cluster manager. The cluster manager is a server that prevents duplicate application context identifiers by supplying each new MIL application context with a range of allowable identifiers to choose from.

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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ServerDescription

Specifies the computer name or IP address of the cluster manager. When not in a Distributed MIL environment, set this parameter to M_NULL.

For specifying the cluster manager
Value	Description
MIL_TEXT("M_DEFAULT") ¹	Specifies to use the cluster manager specified in the MILConfig utility (Cluster Manager pane, accessible from the Distributed MIL item). This only applies when allocating a MIL application within a Distributed MIL monitoring configuration. (summarize) Specifies to use the cluster manager specified in the MILConfig utility (Cluster Manager pane, accessible from the Distributed MIL item). (more details...)
M_NULL	Specifies that no cluster manager will be used. This applies to MIL applications in the controlling configuration and any MIL application not part of a Distributed MIL configuration. (summarize) Specifies that no cluster manager will be used. (more details...)
MIL_TEXT("ClusterManagerName") ¹	Specifies the computer name or IP address of the cluster manager. Replace "ClusterManagerName" with a string specifying the computer name or IP address of the server used as the cluster manager; MIL supports both IPv4 and IPv6 addresses. This only applies when allocating a MIL application within a Distributed MIL monitoring configuration. (summarize) Specifies the computer name or IP address of the cluster manager. (more details...)

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

InitFlag

Specifies the type of initialization to perform on the MIL application context. This parameter should be set to one of the following values:

For specifying the type of initialization
Value	Description
M_DEFAULT	Specifies the default initialization. During the allocation of the application context, reported error messages are displayed. (summarize) Specifies the default initialization. (more details...)
M_QUIET +	Specifies to suppress the displaying of error messages during the allocation of the application context. Note that this value can be combined with M_TRACE_LOG_DISABLE. (summarize) Specifies to suppress the displaying of error messages during the allocation of the application context. (more details...)
M_TRACE_LOG_DISABLE +	Specifies to disable the creation of trace logs by any external program, such as Matrox Profiler or the MILConfig utility Interactive Troubleshooting. Calling MappControl() with M_TRACE set to M_LOG_ENABLE will override M_TRACE_LOG_DISABLE from the point in the code that the function appears. Disabling trace logs with M_TRACE_LOG_DISABLE helps to protect intellectual property against reverse engineering because no external program will be able to generate a trace for this application. Note that this value can be combined with M_QUIET. (summarize) Specifies to disable the creation of trace logs by any external program, such as Matrox Profiler or the MILConfig utility Interactive Troubleshooting. (more details...)

Combination values for M_QUIET; M_TRACE_LOG_DISABLE.

You can add one of the following values to the above-mentioned values to set which hardware-acceleration display mode to use.

By default, MIL uses the mode set using the MILConfig utility.

For specifying the hardware-acceleration display mode

Combination value

Description

M_DX_VERSION(

MIL_INT Version

)

[This is only applicable to Windows]

Specifies the version of DirectX that MIL can use for display purposes. This determines the hardware-acceleration display mode. For advantages and restrictions of each mode, see the Supported hardware acceleration modes section of Chapter 23: Displaying an image.

(summarize)

[This is only applicable to Windows]

Specifies the version of DirectX that MIL can use for display purposes.

(more details...)

Parameters

Version INQ

This parameter specifies the version of DirectX that MIL can use for display purposes. Note that MIL does not support all versions of DirectX.

You can set this parameter to one of the following:

Specifies that DirectX cannot be used. In this case, MIL uses the standard hardware acceleration mode for display. Under Windows, this mode uses the Windows graphics device interface (GDI) functions of the Windows API to render images on the screen. This mode does not use graphics acceleration hardware; therefore, it works the same under all Windows implementations.

9 <= Value <= 11

Specifies that either DirectX version 9.0, 10.0, or 11.0 can be used, respectively. In this case, MIL uses Direct3D hardware acceleration mode for display. MIL uses Direct3D to manipulate internal display buffers, when possible. In addition, the final blit to screen is done using Direct3D if you disable the possibility of drawing directly into the display's window (MdispControl() with M_WINDOW_ANNOTATIONS); otherwise, the final blit is done using GDI functions.

M_X11_ACCELERATION(

MIL_INT Status

)

[This is only applicable to Linux]

Specifies whether MIL can use X11 acceleration for display purposes. This determines the hardware acceleration display mode.

(summarize)

[This is only applicable to Linux]

Specifies whether MIL can use X11 acceleration for display purposes.

(more details...)

Parameters

Status INQ

This parameter specifies whether MIL can use X11 acceleration. You can set this parameter to one of the following:

0	Specifies that X11 acceleration cannot be used. In this case, MIL uses the standard hardware acceleration mode for display. Rendering might be slow.

1	Specifies that X11 acceleration can be used. In this case, MIL uses X11 hardware acceleration mode for display.

Combination value for M_QUIET; M_TRACE_LOG_DISABLE.

You can add the following value to the above-mentioned values to specify a cluster node value without using a cluster manager.

For specifying a cluster node value

Combination value

Description

M_CLUSTER_NODE(

MIL_INT ClusterNodeValue

)

Specifies a cluster node value when none is specified with a cluster manager. A Distributed MIL publishing application requires a cluster node value that identifies the publishing application. If you have not specified a cluster manager for this application, ensure that each publishing application in the cluster has a unique, non-zero value.

Note that a cluster manager automatically assigns a cluster node value to an application. It is the preferred method of managing cluster node values.

(summarize)

Specifies a cluster node value when none is specified with a cluster manager.

(more details...)

Parameters

ClusterNodeValue

Specifies the cluster node value.

Value > 0

Specifies the cluster node value.

ContextAppIdPtr

Specifies the address of the variable in which to write the application context identifier. Since the MappAlloc() function also returns the application context identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier. After allocating an application context, we recommend that you check if the operation was successful, using MappGetError(), or by verifying that the application context identifier returned is not M_NULL.

Return value

The returned value is the application context identifier. If allocation fails, M_NULL is returned.

Remark

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

Compilation information

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