| MIL 10 Reference
| Customize Help
| Save Settings

MbufAlloc2d


See also
Availability
Available in MIL-Lite with restrictions (see remarks)
Available in MIL

Available on Windows with restrictions
Available on Linux with restrictions

Partially supported on:
Partially supported on Host system
Partially supported on Matrox CronosPlus
Partially supported on Matrox GPU processing driver
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
3dmodelheightdefect.cpp
3dplanefit.cpp
adaptivethresholder.cpp
aimdpmgrading.cpp
bestplanefitter.cpp
binarybasedcircledetection.cpp
blisterpackinspection.cpp
blobmerge.cpp
bottlecapinspection.cpp
calibrationfromlist.cpp
cameraevents.cpp
cameraonrobotarmcalibration.cpp
caninspection.cpp
chromasens3dpixa.cpp
chunkmode.cpp
codegrading.cpp
cookiedetection.cpp
defectdetectionexample.cpp
defectdetectionprocfunc.cpp
defectdetectionprocfunc_capandcontent.cpp
defectdetectiontask.cpp
depthdatamgr.cpp
dmilobjecttracking.cpp
dmilobjecttrackingslave.cpp
dotspacing.cpp
exampleinterface.cpp
examplemanagerfor3d.cpp
fdkaddconstantmain.cpp
fdkhistogrammain.cpp
fdklutmapmain.cpp
fdkminmaxmain.cpp
fdkoffsetgainlutmapmain.cpp
fdkoffsetgainmain.cpp
fdkoffsetgainminmaxmain.cpp
featurefinder.cpp
findimageorientation.cpp
fixturingusingblob.cpp
flatfieldcorrection.cpp
foodinspection_cereal.cpp
foodinspection_mango.cpp
foodinspectioncereal.cpp
foodinspectionmango.cpp
histogramdisplay.cpp
imagedownscalingmodes.cpp
imageupscalingmodes.cpp
inspectiontask.cpp
kinect.cpp
lmigocator2000.cpp
m3dmap.cpp
m3dmap.cs
m3dmap.vb
mapptrace.cpp
mapptrace.cs
mapptrace.vb
matroxgatoreye.cpp
mblob.cpp
mblob.cs
mblob.vb
mbufpointeraccess.cpp
mbufpointeraccess.cs
mcol.cpp
mcol.cs
mcol.vb
mcolorwarp.cpp
mdigautofocus.cpp
mdigautofocus.cs
mdigautofocus.vb
mdigdoublebuffering.cpp
mdigdoublebuffering.cs
mdigdoublebuffering.vb
mdiggrabmultiple.cpp
mdigprocess.cpp
mdigprocess.cs
mdigprocess.vb
mdigprocessmultiple.cpp
mechanicalpartscan.cpp
mfunc.cpp
mfunc.cs
mfunc.vb
mgrainteractive.cpp
mgrainteractive.cs
mgrainteractive.vb
microsoftkinect.cpp
milgige.cpp
mimbinarizeadaptive.cpp
mimconvolve.cpp
mimconvolve.cs
mimconvolve.vb
mimfft.cpp
mimfft.cs
mimfft.vb
mimlocatepeak1d.cpp
mimlocatepeak1d.cs
mimlocatepeak1d.vb
mimmorphic.cpp
mimwarp.cpp
mimwarp.cs
mimwarp.vb
mmeas.cpp
mmeas.cs
mmeas.vb
mmodeltracking.cpp
mmodeltracking.cs
mmodeltracking.vb
mocr.cpp
mocr.cs
mocr.vb
morphology.cpp
mprotateprocessing.cpp
mpwarpprocessing.cpp
mthread.cpp
mthread.cs
mthread.vb
multipledatamatrixcoderead.cpp
multiviewannotations.cpp
objectlocalization3d.cpp
objectseparation.cpp
pcbmodelmatching.cpp
pfocus.cpp
processingfpga.cpp
profiledisplay.cpp
regionmanager.cpp
registeredgoldentemplate.cpp
scriptpreprocessing.cpp
segmentationandanalysisofcells.cpp
semiocr.cpp
sickrangerc.cpp
sickrangere.cpp
simpledilateerode.cpp
superresolution.cpp
tirestringread.cpp
utilmatchcolormap.cpp
variouscodereadings.cpp
MbufAlloc1d
MbufAllocColor
Synopsis
Allocate a 2D data buffer.
Syntax
MIL_ID MbufAlloc2d(
MIL_ID SystemId, //in
MIL_INT SizeX, //in
MIL_INT SizeY, //in
MIL_INT Type, //in
MIL_INT64 Attribute, //in
MIL_ID *BufIdPtr //out
)
Description

This function allocates a two-dimensional 1-band data buffer on the specified system.

After allocating a buffer, we recommend that you check if the operation was successful, using MappGetError() or by verifying that the buffer identifier returned is not M_NULL.

When a buffer is no longer required, release it, using MbufFree().

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 MIL system on which to allocate the buffer. This parameter should be set to one of the following values:

function map For specifying the MIL system
CollapseValue Description
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

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

Specifies the buffer width. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, specify the width in pixels.

[Matrox GPU processing driver]

When dealing with monochrome (1-band) buffers, the buffer width must be a multiple of 4.

SizeY INQ

Specifies the buffer height. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, specify the height in pixels.

Type INQ

Specifies a combination of two values: the depth and type of the data. Specify the depth of the buffer as one of the following:

function map For the data depth of the buffer
CollapseValue Description
Collapse 1 +

Specifies a 1-bit (packed binary) buffer. Note that you cannot allocate a 1-bit LUT, kernel, or structuring element buffer.

(summarize)
Collapse 8 +

Specifies an 8-bit buffer.
Collapse 16 +

Specifies a 16-bit buffer.
Collapse 32 +

Specifies a 32-bit buffer.
Combination constants for any of the possible values of the Type parameter.

You can add one of the following values to the above-mentioned values to set the data type.

Supported data types depend on the specified depth.

function map For specifying the data type of the buffer
CollapseCombination value Description
Collapse M_FLOAT

Specifies that the type of data is floating-point. The valid data depth is 32 bits.

(summarize)
Collapse M_SIGNED

Specifies that the type of data is signed. The valid data depths are 8, 16, or 32 bits.

(summarize)
Collapse M_UNSIGNED

Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16, or 32 bits.

This is the default value.

(summarize)
Attribute INQ

Specifies the buffer usage. MIL uses this information to determine where to allocate the buffer in physical memory.

Set this parameter to one of the following values:

function map For specifying the buffer usage
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_ARRAY +

Specifies a buffer to store array type data. Note that some functions take an M_ARRAY buffer rather than a user-defined array.

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

Specifies a buffer to store image data.


You must specify a combination value from the following table:
(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

Only single-band (monochrome) buffers with a depth of 8 or 16 bits can have an M_IMAGE attribute.

 † d
Collapse M_KERNEL +
[For essential MIL-Lite information, see remarks ]

Specifies a kernel buffer to store a custom filter for convolution functions.

The depth must be 8, 16, or 32-bit integer or floating-point.

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

Specifies a buffer to store lookup table data.

The valid data depths are 8, 16, or 32 bits.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_STRUCT_ELEMENT +
[For essential MIL-Lite information, see remarks ]

Specifies a buffer to store structuring element data for morphology functions.

The data depth must be 32-bit. If signed, the range is -32767 to +32767. If unsigned, the range is 0 to +32767.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Combination constants for M_IMAGE.

You must add one or more of the following values to the above-mentioned value to set the intended purpose of the image buffer.

function map For specifying the intended purpose of the image buffer
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_COMPRESS +
[For essential MIL-Lite information, see remarks ]

Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.

When allocating buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

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

Specifies an image buffer that can be displayed.

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

Single-band display buffers with a depth greater than 16 bits cannot be allocated. 3-band display buffers can only be allocated with 8 bits per band.

 † f
Collapse M_GRAB

Specifies an image buffer in which to grab data. This type of buffer is usually allocated in MIL-reserved, physically contiguous, non-paged memory.

For Host buffers (M_HOST_MEMORY), the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL-reserved, non-paged memory (specified at installation time or using the MILConfig utility).

For on-board buffers (M_ON_BOARD), maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of on-board memory.

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

Only single-band (monochrome) buffers with a depth of 8 or 16 bits can have an M_GRAB attribute.

 † c j k l m o p q r s

Only single-band (monochrome) buffers with a depth of 8 bits can have an M_GRAB attribute.

 † b f g h n
Collapse M_PROC +

Specifies an image buffer that can be processed.

 † a b c d e f g h i j k l m n o p q r s
Combination constant for M_PROC.

You can add the following value to the above-mentioned value to set the allocation of an overscan region.

This overrides the MsysControl() M_ALLOCATION_OVERSCAN system control setting and forces the allocation of an overscan region. When this attribute is set, the setting of the M_ALLOCATION_OVERSCAN_SIZE system control determines the size of the overscan region and the M_ALLOCATION_OVERSCAN setting is ignored.

Note that this attribute is only useful when added to a buffer on which you want to perform neighborhood processing operations.

function map For allocating an overscan region
CollapseCombination value Description
Collapse M_ALLOCATION_OVERSCAN

Specifies that the buffer is allocated with an overscan region. Specify the size of the region using MsysControl() with M_ALLOCATION_OVERSCAN_SIZE.

(summarize)
Combination constants for M_COMPRESS.

You can add one of the following values to the above-mentioned value to set the compression type.

The image buffer's data depth dictates which compression type can be selected.

function map For specifying the compression type INQ
CollapseCombination value Description
Collapse M_JPEG2000_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Collapse M_JPEG2000_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Collapse M_JPEG_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Collapse M_JPEG_LOSSLESS_INTERLACED
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossless data in separate fields. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Collapse M_JPEG_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossy data. The supported data format is 1-band, 8-bit data.

This is the default value.

(summarize)
Collapse M_JPEG_LOSSY_INTERLACED
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossy data in separate fields. The supported data format is 1-band, 8-bit data.

(summarize)
Combination constants for M_IMAGE.

You can add one of the following values to the above-mentioned value to set a storage format and a location specifier.

MIL automatically selects the most appropriate storage format according to the specified intended usage attribute. For general processing, MIL will convert the data when the function requires a different format. If the default storage format is not appropriate and you want to avoid conversion during a time critical operation, you can add a storage format and a location specifier.

function map For specifying a storage format and a location specifier
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_DIB
[This is only applicable to Windows]

Forces the buffer to be a DIB buffer. This ensures your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DIRECTX
[This is only applicable to Windows]

Forces the buffer to be a DirectX surface.

 † a b c d e g h i j k l m n o p q r s
Collapse M_GDI

Forces the buffer to be compatible with GDI.

When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_LINUX_MXIMAGE
[This is only applicable to Linux]

Forces the buffer to be an X11 Ximage.

 † a b c d e g h i j k l m n o p q r s
Combination constant for M_IMAGE; M_LUT.

You can add the following value to the above-mentioned values to specify that the buffer is FPGA accessible.

Note that the following value cannot be used with M_COMPRESS or values in the For specifying a storage format and a location specifier table.

function map For specifying that the buffer is FPGA accessible
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_FPGA_ACCESSIBLE +

Forces the buffer to be allocated in a bank of memory that is accessible from the Processing FPGA. The exact bank of on-board memory is determined by the other attributes used with this value.

If combined with the M_HOST_MEMORY attribute, the memory allocated will be in non-paged Host memory.

If combined with the M_GRAB, or M_GRAB + M_PROC attribute, the Matrox Solios will allocate a buffer in memory bank 0.

If combined with the M_PROC attribute, the Matrox Solios will allocate a buffer in memory bank 1.

If combined with the M_PROC + M_FAST_MEMORY attribute, the Matrox Solios will allocate a buffer in memory bank 2.

(summarize)
† j l m p r
Combination constants for any of the possible values of the Attribute parameter.

You can add one of the following values to the above-mentioned values to set a location for a buffer.

function map For specifying a location for a buffer
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_HOST_MEMORY +

Forces the buffer in Host memory.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific
This is a MIL system specific default value. † a b c e f g h i j k l m n o p q r s
Collapse M_MAPPABLE

Forces the buffer to be allocated in non-paged memory that can be set in the address space of the process (Host memory). By default, however it is not mapped to Host memory (that is, by default the buffer will have a physical address, but not a Host address). Use MbufControl() with M_MAP to enable or disable the mapping to Host memory.

This setting is useful when dealing with many large buffers that cannot all be mapped in Host memory at the same time. By allocating a buffer as M_MAPPABLE, it can be mapped and unmapped as needed.

Note that, if used with the M_PAGED attribute, an error will be generated.

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

Ensures that the buffer is not in on-board memory.

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

To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer section of the board, the buffer must be allocated in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED).

 † f g h j k l m n p q r
Collapse M_ON_BOARD +

Forces the buffer in on-board memory.

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

By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values below (M_SHARED) to change this default behavior.

 † j k l m p q r

This is only available for grab buffers (M_GRAB).

 † f

This is only available for image buffers (M_IMAGE).

 † g h i k n

This is only available for image (M_IMAGE) and LUT buffers (M_LUT).

 † j l m p q r
Collapse M_VIDEO_MEMORY
[This is only applicable to Windows]

Forces the buffer in (off-screen) display memory of your graphics controller.

If Direct3D hardware acceleration mode is being used for display, the buffer cannot be allocated in display memory when any of the following attributes are used: M_GRAB or M_NON_PAGED. This is also the case when using DirectDraw 7 hardware acceleration mode if also using a non-Matrox graphics controller.

If Direct3D hardware acceleration mode is being used for display and you allocate the buffer in display memory, you must use the lock-unlock mechanism to access the buffer (MbufControl() with M_LOCK / M_UNLOCK).

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

Buffers cannot be allocated in display memory when any of the following attributes are used: M_COMPRESS, M_DIB, M_GDI, or M_NON_PAGED.

 † d
This is a MIL system specific default value. † d
Combination constant for the values listed in For specifying that the buffer is FPGA accessible; and for the following values: M_HOST_MEMORY; M_ON_BOARD.

You can add the following value to the above-mentioned values to specify a memory bank to be used.

function map For specifying a memory bank to be used
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_MEMORY_BANK_n

Forces the buffer to be allocated in the specified memory bank.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Operating system specific
[This is only applicable to Windows]

Valid values for n are between 0 and 6, inclusive. However, not all memory banks are necessarily present on a given system. Typically, if there is more than 1 memory bank, it is NUMA-enabled. Note that, to ensure that you are accessing a NUMA-enabled memory bank, you must specify the M_HOST_MEMORY combination value.

To determine the actual number of memory banks available on the MIL system, use MappInquireMp() with M_MEMORY_BANK_NUM and MappInquireMp() with M_MEMORY_BANK_AFFINITY_MASK. For more information, refer to the NUMA Support subsection of the Transparent multi-core use section of Chapter 30: Multi-processing, multi-core, and multi-threading.

Note that this value cannot be used with M_COMPRESS or M_NON_PAGED.

Also note that the combination of M_HOST_MEMORY with this value, in paged memory, is only useful when doing multi-core processing on a Host system.
[This is only applicable to Linux]

Note that this value is not available with the M_HOST_MEMORY combination value.
MIL system specific

Valid values for n are between 0 and 1, inclusive. Refer to your MIL Hardware-specific Notes for more information about on-board memory. Note that, to assure you are accessing an on-board memory bank, you must specify the M_ON_BOARD combination value.

Memory bank number

Type of memory

Description

0

Acquisition (SDRAM)

This is the default memory bank for an on-board buffer created with the M_GRAB attribute.

1

Fast (SRAM)

This is the default memory bank for an on-board buffer created with the M_PROC + M_FAST_MEMORY attribute.
† j p r

In this case, n must be set to 0. This is the default memory bank for an on-board buffer created with the M_GRAB attribute. Refer to your MIL Hardware-specific Notes for more information about on-board memory. Note that, to assure you are accessing an on-board memory bank, you must specify the M_ON_BOARD combination value.

 † k q

Valid values for n are between 0 and 2, inclusive. Refer to your MIL Hardware-specific Notes for more information about on-board memory. Note that, to assure you are accessing an on-board memory bank, you must specify the M_ON_BOARD combination value.

Memory bank number

Type of memory

Description

0

Acquisition (SDRAM)

This is the default memory bank for an on-board buffer created with the M_GRAB attribute.

1

Processing (SDRAM)

This is the default memory bank for an on-board buffer created with the M_PROC attribute.

2

Fast (SRAM)

This is the default memory bank for an on-board buffer created with the M_PROC + M_FAST_MEMORY attribute.
† l m
Combination constants for the values listed in For specifying that the buffer is FPGA accessible; and for the following value: M_ON_BOARD.

You can add one of the following values to the above-mentioned values to set a location in a specific type of memory.

function map For specifying a location in a specific type of memory
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_FAST_MEMORY

Specifies that the buffer is in the fastest memory available.

Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was allocated in fast processing memory.

This attribute can only be combined with M_GRAB + M_FPGA_ACCESSIBLE.

(summarize)
† j l m p r
MIL system specific

For Matrox Solios eA/XA and eCL/XCL, the fasted memory available is the SRAM. If SRAM is not present on your Matrox Solios, SDRAM will be used instead. This value is typically the same as using M_MEMORY_BANK_2.

 † l m

For Matrox Radient, the fasted memory available is the SRAM. If SRAM is not present on your Matrox Radient, SDRAM will be used instead. This value is typically the same as using M_MEMORY_BANK_1.

 † j p r
Collapse M_SHARED

Specifies that the buffer is in shared processing memory. This memory is mapped on the PCI bus.

Note that this combination value can only be added to M_ON_BOARD.

(summarize)
† j k l m p q r
Combination constants for any of the possible values of the Attribute parameter.

You can add one of the following values to the above-mentioned values to set the attribute of the specified physical memory type.

function map For specifying the attribute of the specified physical memory type
CollapseCombination value Description
Collapse M_NON_PAGED

Forces the buffer in MIL-reserved, non-pageable memory.
Collapse M_PAGED

Forces the buffer in pageable memory.
BufIdPtr

Specifies the address of the variable in which to write the buffer identifier. Since the MbufAlloc2d() function also returns the buffer 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 buffer identifier. If allocation fails, M_NULL is returned.
Remarks
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST FLOAT SIGNED UNSIGNED ARRAY IMAGE KERNEL LUT STRUCT ELEMENT COMPRESS DISP GRAB PROC ALLOCATION OVERSCAN JPEG2000 LOSSLESS JPEG2000 LOSSY JPEG LOSSLESS JPEG LOSSLESS INTERLACED JPEG LOSSY JPEG LOSSY INTERLACED DIB DIRECTX GDI LINUX MXIMAGE FPGA ACCESSIBLE HOST MEMORY MAPPABLE OFF BOARD ON BOARD VIDEO MEMORY MEMORY BANK n FAST MEMORY SHARED NON PAGED PAGED ARRAY IMAGE IMAGE M COMPRESS IMAGE M PROC IMAGE M GRAB KERNEL LUT STRUCT ELEMENT