MbufClone

• See also
User Guide:
Managing data buffers
Reference:
MbufAllocColor MbufControl 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
classcnncompletetrain.cpp
classprintedchar.cpp
classseafoodinspect.cpp
classtreeensembletrain.cpp
extendeddepthoffield.cpp
flatfieldcorrection.cpp
m3ddisp.cpp
m3ddisp.cs
m3ddisp.vb
mimaugment.cpp
multicameralasercalibration.cpp
multiviewannotations.cpp
photometricstereowithmotion.cpp
specularreflectionreduction.cpp
variousdenoising.cpp
wavelettransformation.cpp

MbufClearCond
MbufControl

Description

Parameters

SrcContainerOrBufId

Specifies the identifier of the source buffer or container to clone.

If the source is an image buffer, it must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

SysId

Specifies the system on which to allocate the clone.

For specifying the system
Value	Description
M_DEFAULT	Specifies that the clone is allocated on the same system as the source buffer or container.
MIL system identifier	Specifies a valid system identifier, previously allocated using MsysAlloc().

SizeX

Specifies the width of the clone. If the source is a container, this parameter must be set to M_DEFAULT.

For specifying the width of the buffer
Value	Description
M_DEFAULT	Specifies that the width of the clone is the same as the source buffer, or that the destination is a container.
Value >= 1	Specifies the width of the clone buffer, in pixels.

SizeY

Specifies the height of the clone. If the source is a container, this parameter must be set to M_DEFAULT.

For specifying the height of the buffer
Value	Description
M_DEFAULT	Specifies that the height of the clone is the same as the source buffer.
Value >= 1	Specifies the height of the clone buffer, in pixels.

Type

Reserved for future expansion and must be set to M_DEFAULT.

Attribute

Specifies the attributes of the clone. For both buffers and containers, you can specify that the clone will retain the same attributes as the source by setting this parameter to M_DEFAULT.

For containers, you can specify that the clone will have different attributes than the source by setting this parameter to M_DISP, M_GRAB, and/or M_PROC.

For buffers, you can set this parameter to the following values. The intended usage attribute (such as M_IMAGE) of the clone must match the intended usage attribute of the source. The other attributes (such as M_GRAB) can be set to any combination supported for the data type of the source buffer and the system specified by SysId.

Note that some settings are only available for buffers with a specific usage attribute, data type, and/or number of bands. An error is generated if you specify attributes that are incompatible with the source buffer.

For specifying the clone attributes
Value	Description
M_DEFAULT	Specifies to allocate the clone with the same attributes as the source.
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 the image buffer or container (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 and only the planar internal storage format is valid. (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 that can be used alone or as combination values for M_IMAGE.

You must use one or more of the following values in combination with each other or with the above-mentioned value, to set the intended purpose of the image buffer or container.

Note that you can only use these values alone when the source is a container.

For specifying the intended purpose of the image buffer or container
Value	Description		MIL system-specific tooltip (‡)
M_DISP	Specifies an image buffer or container intended for display.		‡	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 or container in which to grab data. (summarize) Specifies an image buffer or container 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
		This setting is not supported for containers.	‡			g	h	i	j	k M10	l	m		p	r U27	t U28	u U36			y U75		aa
		Single-band (monochrome) buffers must have a depth of 8 bits or 16 bits to have an M_GRAB attribute. Only some three-band (color) buffers can have an M_GRAB attribute. See the constants for color buffer formats to determine which are supported with 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. Only some three-band (color) buffers can have an M_GRAB attribute. See the constants for color buffer formats to determine which are supported with an M_GRAB attribute.	‡			g	h
		Single-band (monochrome) buffers must have a depth of 8 bits or 16 bits to have an M_GRAB attribute. Only some three-band (color) buffers can have an M_GRAB attribute. See the constants for color buffer formats to determine which are supported with an M_GRAB attribute. Note that color buffers with an M_GRAB attribute are only available for color versions of Matrox Iris GTR (such as 1300C).	‡													t U28
M_PROC +	Specifies an image buffer or container intended for processing.		‡	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_IMAGE.

You can add one or more of the following value to the above-mentioned value to set that the image buffer is compressed.

For specifying that the image buffer is compressed
Combination value	Description
M_COMPRESS +	Specifies an image buffer that can hold compressed data. INFO

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

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
Combination value	Description
M_H264	[For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold H.264 data. This compression type is used when specifying a source of an input or a destination of an output for a sequence operation as an array of buffers (MseqDefine() with M_BUFFER_LIST). (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer will be used to hold H.264 data. (more details...)
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, and 3-band, 8- or 16-bit data in M_RGB24 + M_PLANAR, M_RGB48 + M_PLANAR, or M_YUV24 + M_PLANAR format. (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, and 3-band, 8- or 16-bit data in M_RGB24, M_RGB48, M_YUV9, M_YUV12, M_YUV16 + M_PLANAR, or M_YUV24 format. (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, and 3-band data in M_RGB24 or M_RGB48 format. (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 formats are: 1-band 8-bit data, and 3-band 8-bit data in M_RGB24, M_YUV24, M_YUV12, M_YUV9, M_YUV16 + M_PLANAR, or M_YUV16 + M_PACKED format. 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 formats are: 1-band 8-bit data, and 3-band 8-bit data in M_YUV16 + M_PACKED format. (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	Forces the buffer to be a DIB buffer. INFO	‡	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. INFO	‡	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 M_ARRAY; M_IMAGE; M_KERNEL; M_LUT; M_STRUCT_ELEMENT.

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.

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. INFO	‡						j		l	m		p	r U27							aa

Combination values for M_IMAGE.

You can add one of the following values to the above-mentioned value to set a storage format for color buffers.

Note that the buffer must be a color buffer. Also note that it might be slower to use buffers that have been forced with one of these attributes. Although there is no right or wrong storage format to use, certain operations are optimized for some formats.

For specifying a storage format for color buffers
Combination value	Description
M_PACKED +	Specifies that the buffer's bands are stored in packed format (color buffer only); that is, the pixel components are stored together (RGB RGB RGB...). INFO
M_PLANAR +	Specifies that the buffer's bands are stored in planar format (color buffer only); that is, each pixel is stored as three component planes (RRR... GGG... BBB...). INFO

Combination values for M_PLANAR.

You can add one of the following values to the above-mentioned value to set a planar color buffer format. Alternatively, you can add a value from For specifying a packed or planar color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

For specifying a planar color buffer format
Combination value	Description	MIL system-specific tooltip (‡)
M_RGB3	Specifies 3-bit color depth (RGB 1:1:1) planar pixels.	‡	a		g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
M_YUV9	Specifies YUV9 planar pixels.	‡	a		g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
M_YUV12	Specifies YUV12 planar pixels.	‡	a		g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa
M_YUV24	Specifies YUV24 planar pixels.	‡	a		g	h	i	j	k M10	l	m		p	r U27		u U36			y U75		aa

Combination values for M_PACKED.

You can add one of the following values to the above-mentioned value to set a packed color buffer format. Alternatively, you can add a value from For specifying a packed or planar color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

For specifying a packed color buffer format
Combination value	Description	MIL system-specific tooltip (‡)
M_BGR24	Specifies 24-bit color depth packed pixels (BGRBGR). INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_BGR32	Specifies 32-bit color depth packed pixels (BGRXBGRX). INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_RGB15	Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5). INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_RGB16	Specifies 16-bit color depth packed pixels (RGB 5:6:5). INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_YUV16_UYVY	Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. INFO	‡		c M10								o					v
M_YUV16_YUYV	Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Combination values for the values listed in For specifying a storage format for color buffers.

You can add one of the following values to the above-mentioned values to set a packed or planar color buffer format. Alternatively, you can add a value from For specifying a packed color buffer format or from For specifying a planar color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

For specifying a packed or planar color buffer format
Combination value	Description
M_RGB24	Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels. INFO
M_RGB48	Specifies 48-bit color depth (RGB 16:16:16). INFO
M_RGB96	Specifies 96-bit color depth (RGB 32:32:32) packed or planar pixels.
M_YUV16	Specifies YUV16 (4:2:2) pixels. INFO

Combination values for M_ARRAY; M_IMAGE; M_KERNEL; M_LUT; M_STRUCT_ELEMENT.

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 to be allocated in non-paged memory that can be set in the address space of the process (Host memory). INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_OFF_BOARD	Ensures that the buffer is not in on-board memory. INFO	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_ON_BOARD +	Forces the buffer in on-board memory. INFO	‡			g	h	i	j	k M10	l	m		p	r U27	t U28	u U36			y U75		aa
M_VIDEO_MEMORY	Forces the buffer in (off-screen) display memory of your graphics controller. INFO	‡	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
M_MEMORY_BANK_n	Forces the buffer to be allocated in the specified memory bank. INFO

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. INFO	‡						j		l	m		p
M_SHARED	Specifies that the buffer is in shared processing memory. INFO	‡						j	k M10	l	m		p	r U27					y U75		aa

Combination values for M_ARRAY; M_IMAGE; M_KERNEL; M_LUT; M_STRUCT_ELEMENT.

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.

ControlFlag

Specifies the control settings for the cloning operation.

For specifying which information to copy
Value	Description
M_DEFAULT	Specifies to copy only the number of bands, type, and attributes of the source buffer (or components of the source container). The data, information dependent on the content of the buffer (such as M_MIN and M_MAX), and the camera calibration information associated with the source buffer are not copied. (summarize) Specifies to copy only the number of bands, type, and attributes of the source buffer (or components of the source container). (more details...)
M_COPY_SOURCE_DATA	Specifies to copy the number of bands, type, attributes, and data of the source buffer (or components of the source container), including the camera calibration information and information dependent on the content of the buffer (such as M_MIN and M_MAX).

VarContainerOrBufIdPtr

Specifies the address of the variable in which to write the buffer or container identifier. Since the MbufClone() function also returns the buffer or container 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 identifier of the new, cloned buffer or container. If allocation fails, M_NULL is returned.

Remarks

[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 a 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.