MbufAlloc1d

• See also
User Guide:
Adjusting the intensity distribution Attribute Color and display settings for 3D data Controlling configuration Custom spatial filters Data buffers overview Dealing with color Enhancing and detecting edges General steps Grabbing large images Grabbing to the display LUTs and data buffers Mapping 1-band images through a LUT upon display Mapping a data buffer to user-allocated memory Mathematics with images Monitoring configuration Processing an image with a Processing FPGA Source and destination image buffers Steps to performing annotations Transparent multi-core use Using 3D cameras that output uncorrected depth maps Using child buffers, ROIs, or a copy to manipulate specific data areas Using images acquired with a Bayer color filter Warping Working with non-compliant cameras
Reference:
MappGetError MappInquireMp MbufAlloc1d MbufControl MbufFree MbufInquire MsysAlloc MsysControl
Availability
Available in MIL-Lite with restrictions (see remarks)
Available in MIL


Available on Windows with restrictions
Available on Linux with restrictions


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
3dprofilemetrology.cpp
cielabconversion.cpp
classtreeensembletrain.cpp
defectdetectionprocfunc.cpp
defectdetectionprocfunc_capandcontent.cpp
depthfromfocus.cpp
dmilobjecttracking.cpp
dmilremapslave.cpp
fdklutmapmain.cpp
interactivebayer.cpp
m3dmap.cpp
m3dmap.cs
m3dmap.vb
mbufbayer.cpp
mdiggrabdynamic.cpp
mdighandler.cpp
mdispwindowleveling.cpp
mdispwindowleveling.cs
mdispwindowleveling.vb
medgecustomderivatives.cpp
mgenlutfunction.cpp
mimwarpquadrilateral.cpp
morphology.cpp
mpwarpprocessing.cpp
offsetgainlutmap.cpp
processingfpga.cpp
semiocr.cpp

Previous
MbufAlloc2d

Description

Parameters

SystemId INQ

Specifies the MIL system on which to allocate the buffer. This parameter should be set to one of the following values:

For specifying the MIL system
Value	Description
M_DEFAULT_HOST	Specifies the default Host system of the current MIL application.
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 a LUT buffer attribute, specify the number of LUT entries to allocate.

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:

For the data depth of the buffer
Value	Description
1 +	Specifies a 1-bit (packed binary) buffer. Note that you cannot allocate a 1-bit LUT, kernel, or structuring element buffer. (summarize) Specifies a 1-bit (packed binary) buffer. (more details...)
8 +	Specifies an 8-bit buffer.
16 +	Specifies a 16-bit buffer.
32 +	Specifies a 32-bit buffer.

Combination values 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.

For specifying the data type of the buffer
Combination value	Description
M_FLOAT	Specifies that the type of data is floating-point. The valid data depth is 32 bits. (summarize) Specifies that the type of data is floating-point. (more details...)
M_SIGNED	Specifies that the type of data is signed. The valid data depths are 8, 16, or 32 bits. (summarize) Specifies that the type of data is signed. (more details...)
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) Specifies that the type of data is unsigned. (more details...)

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:

For specifying the buffer usage
Value	Description
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) Specifies a buffer to store array type data. (more details...)
M_IMAGE +	Specifies a buffer to store image data. You must specify a combination value from the following table: To set the intended purpose of this buffer (summarize) Specifies a buffer to store image data. (more details...)
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) [For essential MIL-Lite information, see remarks ] Specifies a kernel buffer to store a custom filter for convolution functions. (more details...)
M_LUT +	Specifies a buffer to store lookup table data. The valid data depths are 8, 16, or 32 bits. (summarize) Specifies a buffer to store lookup table data. (more details...)
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. Note that the data can be set to M_DONT_CARE to ignore specific structuring elements. (summarize) [For essential MIL-Lite information, see remarks ] Specifies a buffer to store structuring element data for morphology functions. (more details...)

Combination values for M_IMAGE.

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

For specifying the intended purpose of the image buffer
Combination value	Description		MIL system-specific tooltip (‡)
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 must have the M_UNSIGNED 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 specifies but different compression types, the data will be re-compressed according to the settings of the destination buffer. (summarize) [For essential MIL-Lite information, see remarks ] Specifies an image buffer that can hold compressed data. (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_DISP	Specifies an image buffer that can be displayed.		‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
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) Specifies an image buffer in which to grab data. (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
		Single-band (monochrome) buffers must have a depth of 8 or 16 bits to have an M_GRAB attribute.	‡		c M10				j	k M10	l	m	o	p	r U27			v		y U75		aa
		Single-band (monochrome) buffers must have a depth of 8 bits to have an M_GRAB attribute.	‡			g	h									t U28
M_PROC +	Specifies an image buffer that can be processed. If you intend to use the buffer as the source or destination buffer of a processing or analysis operation, you must allocate the buffer with an M_PROC attribute. (summarize) Specifies an image buffer that can be processed. (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

Combination value 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.

For allocating an overscan region
Combination value	Description
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) Specifies that the buffer is allocated with an overscan region. (more details...)

Combination values 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.

For specifying the compression type INQ
Combination value	Description
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) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG2000 lossless data. (more details...)
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) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG2000 lossy data. (more details...)
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) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG lossless data. (more details...)
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) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG lossless data in separate fields. (more details...)
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. If no attribute is specified, M_JPEG_LOSSY is assumed. This is the default value. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG lossy data. (more details...)
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) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold JPEG lossy data in separate fields. (more details...)

Combination values 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.

For specifying a storage format and a location specifier
Combination value	Description	MIL system-specific tooltip (‡)
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) [This is only applicable to Windows] Forces the buffer to be a DIB buffer. (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_DIRECTX	[This is only applicable to Windows] Forces the buffer to be a DirectX surface.	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27		u U36	v		y U75		aa
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) Forces the buffer to be compatible with GDI. (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_LINUX_MXIMAGE	[This is only applicable to Linux] Forces the buffer to be an X11 Ximage.	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27		u U36	v		y U75		aa

Combination value for the values listed in For specifying the buffer usage.

You can add the following value to the above-mentioned values to set a location for a buffer that 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.

For specifying that the buffer is FPGA accessible
Combination value	Description	MIL system-specific tooltip (‡)
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_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) Forces the buffer to be allocated in a bank of memory that is accessible from the Processing FPGA. (more details...)	‡						j		l	m		p	r U27							aa

Combination values 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.

For specifying a location for a buffer
Combination value	Description		MIL system-specific tooltip (‡)
M_HOST_MEMORY +	Forces the buffer in Host memory. This is the default value. (summarize) Forces the buffer in Host memory. (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_MAPPABLE	Forces the buffer in non-paged memory. This memory 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) Forces the buffer in non-paged memory. (more details...)		‡	a	c M10	g	h		j	k M10	l	m	o	p	r U27	t U28		v		y U75		aa
M_OFF_BOARD	Ensures that the buffer is not in on-board memory. (summarize) Ensures that the buffer is not in on-board memory. (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
		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).	‡			g	h		j	k M10	l	m		p	r U27	t U28				y U75		aa
M_ON_BOARD +	Forces the buffer in on-board memory. (summarize) Forces the buffer in on-board memory. (more details...)		‡			g	h	i	j	k M10	l	m		p	r U27	t U28	u U36			y U75		aa
		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 M10	l	m		p	r U27					y U75		aa
		This is only available for grab buffers (M_GRAB).	‡													t U28
		This is only available for image buffers (M_IMAGE).	‡			g	h	i		k M10							u U36			y U75
		This is only available for image (M_IMAGE) and LUT buffers (M_LUT).	‡						j		l	m		p	r U27							aa
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) [This is only applicable to Windows] Forces the buffer in (off-screen) display memory of your graphics controller. (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

Combination value 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.

For specifying a memory bank to be used
Combination value	Description		MIL system-specific tooltip (‡)
M_MEMORY_BANK_n	Forces the buffer to be allocated in the specified memory bank. (summarize) Forces the buffer to be allocated in the specified memory bank. (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	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
		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 51: 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 supported 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 U27							aa
		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 M10										y U75
		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 values 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.

For specifying a location in a specific type of memory
Combination value	Description		MIL system-specific tooltip (‡)
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) Specifies that the buffer is in the fastest memory available. (more details...)		‡						j		l	m		p	r U27							aa
		MIL system specific
		For Matrox Solios eA/XA and eCL/XCL, the fastest 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 fastest 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 U27							aa
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) Specifies that the buffer is in shared processing memory. (more details...)		‡						j	k M10	l	m		p	r U27					y U75		aa

Combination values 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.

For specifying the attribute of the specified physical memory type
Combination value	Description
M_NON_PAGED	Forces the buffer in MIL reserved, non-pageable memory.
M_PAGED	Forces the buffer in pageable memory.

BufIdPtr

Specifies the address of the variable in which to write the buffer identifier. Since the MbufAlloc1d() 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

If you are creating a DLL that includes a call to MbufAlloc1d(), ensure that the call is not made from the DllMain() function, because MbufAlloc1d() might load a required DLL and you cannot load a DLL from DllMain(). If necessary, call MbufAlloc1d() from an initialization function in your DLL instead.
[MIL-Lite]
Note that during development and at runtime, compression support, particularly for an M_COMPRESS buffer type, requires the presence of a MIL license that grants access to the compression/decompression package. This access is only granted by default with the development license dongle for the full version of MIL. In other cases, you must purchase access to this package separately.
[MIL-Lite]
You can allocate an image buffer with an M_KERNEL or an M_STRUCT_ELEMENT attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.