MbufCreateComponent

See also

User Guide:

3D containers overview Components Using components individually Working with non-compliant cameras

Reference:

MbufAlloc1d MbufAllocColor MbufAllocComponent MbufAllocContainer MbufControl MbufFree MbufFreeComponent MbufGetColor MbufInquire MbufInquireContainer MbufPutColor

Availability

Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Available on Windows

Available on Linux

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

None.

Function Map

- SizeBand

Table:

For specifying the number of surfaces

- SizeX

Table:

For the buffer width

- SizeY

Table:

For the buffer height

- Type

Table:	For the depth of the buffer
+ combination:	For specifying the data type

- Attribute

Table:	For specifying the buffer usage
+ combination:	For specifying the intended purpose of the image buffer
+ combination:	For specifying the compression type
+ combination:	For specifying a storage format for color buffers
+ combination:	For specifying a planar color buffer format
+ combination:	For specifying a packed color buffer format
+ combination:	For specifying a packed or planar color buffer format
+ combination:	For specifying location information

- ControlFlag

Table:	For specifying the physical nature of the buffer
+ combination:	For specifying how the pitch is measured

- Pitch

Table:

For specifying the size of the pitch

- ArrayOfDataPtr

- ComponentType

Table:

For specifying the type of component

- ComponentIdPtr

Return value

Remarks

Compilation information

Synopsis

Create a component in the specified container.

Syntax

MIL_ID MbufCreateComponent(

MIL_ID ContainerBufId,	//in
MIL_INT SizeBand,	//in
MIL_INT SizeX,	//in
MIL_INT SizeY,	//in
MIL_INT Type,	//in
MIL_INT64 Attribute,	//in
MIL_INT64 ControlFlag,	//in
MIL_INT Pitch,	//in
void **ArrayOfDataPtr,	//in
MIL_INT64 ComponentType,	//in
MIL_ID *ComponentIdPtr	//out

)

Description

This function creates a data buffer using memory at a specified location, and makes it a component of a specified container. The buffer is allocated on the same system as the container.

This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.

Typically, you should leave buffer allocation, data loading, and memory control to MIL (MbufAllocComponent(), MbufGetColor(), MbufPutColor()), since MIL might require special memory attributes (such as non-paged memory) or alignment to associate the buffer component with the same system as the container.

You must allocate the appropriate memory before calling MbufCreateComponent() (except when M_PHYSICAL_ADDRESS is specified), and you must free the created buffer when no longer required, either using MbufFreeComponent() or by freeing its container using MbufFree(), before freeing the memory. Freeing a buffer created with MbufCreateComponent() will free the internal structure required for a mapped buffer, but it will not free the memory used.

If creating a 3-band buffer, be as specific as possible when setting the buffer attributes (using the Attribute parameter) and make sure to specify the color format of the buffer. The more information known about the associated buffer, the better the results.

[Matrox Radient eCL; Matrox Radient eV-CL (introduced U27); Matrox Radient eV-CXP (introduced M10); Matrox RadientPro-CL (Update 7); Matrox Rapixo CL Pro (Update 96); Matrox Rapixo CXP (introduced U75); Matrox Solios eA/XA; Matrox Solios ecl/xcl/ev-cl]

Note that to create a buffer mapped to on-board memory, it must be shared memory. See your MIL Hardware-specific Notes for more information regarding shared memory.

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

ContainerBufId

Specifies the MIL identifier of the container in which to create the buffer component. The buffer will be allocated on the same system as the container.

SizeBand INQ

Specifies the number of (x,y) surfaces (also called color bands) that the buffer should have to contain each color component of the data. When acquiring or processing monochrome images, the buffer requires only one color band. For RGB color images, it requires three color bands.

For specifying the number of surfaces
Value	Description
M_DEFAULT	Specifies the same number of color bands as the source buffer when the ControlFlag parameter is set to M_MIL_ID.
1 <= Value <= 3	Specifies the number of bands. There are generally either 1 or 3 bands. (summarize) Specifies the number of bands. (more details...)

SizeX INQ

Specifies the buffer width.

For the buffer width
Value	Description
M_DEFAULT	Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.
Value	Specifies the buffer width. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, width is specified in pixels. (summarize) Specifies the buffer width. (more details...)

SizeY INQ

Specifies the buffer height.

For the buffer height
Value	Description
M_DEFAULT	Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.
Value	Specifies the buffer height. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, height is specified in pixels. (summarize) Specifies the buffer height. (more details...)

Type INQ

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

For the depth of the buffer
Value	Description
M_DEFAULT	Specifies that the data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.
1 +	Specifies a 1-bit (packed binary) buffer. Note that you cannot create a 1-bit LUT 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 the values listed in For the depth of the buffer.

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

For specifying the data type
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

Specifies the buffer usage. This allows you to specify the type of buffer, compression type, storage format, data direction, location, internal storage format, memory type, and overscan region of the created buffer; all of which provides additional information for other MIL functions.

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.
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 depth must be 8, 16, or 32-bit integer or floating-point and the internal storage format must be planar (M_PLANAR). (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 -32768 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 value for M_IMAGE.

You can add the following value 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
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. If M_COMPRESS is specified, the underlying data must already be compressed with the specified compression type and color format. The SizeBand, Type SizeX and SizeY parameters must also be set to the exact size of the compressed image stored in the underlying data. It is not possible to create a compressed buffer mapped on to only part of a compressed image. When mapping 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. Note that buffers created from preallocated memory with the M_COMPRESS attribute should typically only be passed to MIL functions as a source. If you pass a compressed buffer created from preallocated memory as a destination for a MIL function, an error will be generated if the compressed size in memory of the function output is not the same as the size of the allocated memory. This is true even if the ControlFlag parameter is set to M_MIL_ID. You must specify a combination value from the following table: To set a color buffer format (summarize) [For essential MIL-Lite information, see remarks ] Specifies an image buffer that can hold compressed data. (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.

Note that this value must not conflict with the compression format of the underlying data.

For specifying the compression type
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, 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_COMPRESS; M_IMAGE.

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

When dealing with color buffers, you must specify the appropriate internal storage format of the buffer by adding one of the following values. Note that MIL needs this information to manipulate the data; for example, you do not want MIL to interpret a packed data buffer as a planar.

Although there is no right or wrong storage format for MIL buffers, some operations are optimized for certain formats.

For specifying a storage format for color buffers INQ
Combination value	Description	MIL system-specific tooltip (‡)
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...). Typically, packed buffers are used for display. Note that it might be slower to process buffers with the M_PACKED attribute. Also, note that you cannot allocate a packed LUT buffer. You must specify a combination value from one of the following tables: To set a color buffer format To set a packed color buffer format (summarize) 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...). (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_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...). Typically, planar buffers are used for processing. You must specify a combination value from one of the following tables: To set a color buffer format To set a planar color buffer format (summarize) 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...). (more details...)	‡	a		g	h	i	j	k M10	l	m		p	r U27	t U28	u U36		y U75	aa

Combination values for M_PLANAR.

You must 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 containers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the data in memory (unless M_COMPRESS is specified). For example, data in an RGB24 format will be interpreted as YUV data if M_YUV24 is specified.

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	t U28	u U36	y U75	aa
M_YUV9	Specifies YUV9 planar standard.	‡	a	g	h	i	j	k M10	l	m	p	r U27	t U28	u U36	y U75	aa
M_YUV12	Specifies YUV12 planar standard.	‡	a	g	h	i	j	k M10	l	m	p	r U27	t U28	u U36	y U75	aa
M_YUV24	Specifies YUV24 planar standard.	‡	a	g	h	i	j	k M10	l	m	p	r U27	t U28	u U36	y U75	aa

Combination values for M_PACKED.

You must 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 containers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the data in memory (unless M_COMPRESS is specified). For example, data in an YUV24 format will be interpreted as RGB data if M_RGB24 is specified.

For specifying a packed color buffer format
Combination value	Description		MIL system-specific tooltip (‡)
M_BGR24	Specifies 24-bit color depth (BGR) packed pixels (BGRBGR). (summarize) Specifies 24-bit color depth (BGR) packed pixels (BGRBGR). (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 value can be used with grab (M_GRAB) containers.	‡		c U85								o
M_BGR32	Specifies 32-bit color depth (BGR) packed pixels (BGRXBGRX). The most-significant byte is a "don't care" byte. (summarize) Specifies 32-bit color depth (BGR) packed pixels (BGRXBGRX). (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 value can be used with grab (M_GRAB) containers.	‡		c U85								o
M_RGB15	Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5). Note that when accessing an M_RGB15 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0. (summarize) Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5). (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_RGB16	Specifies 16-bit color depth packed pixels (RGB 5:6:5). Note that when accessing an M_RGB16 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0. (summarize) Specifies 16-bit color depth packed pixels (RGB 5:6:5). (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_YUV16_UYVY	Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. For more information, see the YUV buffers section of Chapter 21: Data buffers. (summarize) Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. (more details...)		‡		c M10								o					v
		MIL system specific
		This value can be used with grab (M_GRAB) containers.	‡		c U85								o
M_YUV16_YUYV	Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. For more information, see the YUV buffers section of Chapter 21: Data buffers. (summarize) Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. (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 value can be used with grab (M_GRAB) containers.	‡		c U85								o

Combination values for the values listed in For specifying the intended purpose of the image buffer; the values listed in For specifying a storage format for color buffers.

You must add one of the following values to the above-mentioned values to set a 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 containers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the data in memory (unless M_COMPRESS is specified). For example, data in an RGB16 format will be interpreted as YUV data if M_YUV16 is specified.

For specifying a packed or planar color buffer format
Combination value	Description		MIL system-specific tooltip (‡)
M_RGB24	Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels. (summarize) Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels. (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 value can be used with packed (M_PACKED) buffers in grab (M_GRAB) containers.	‡		c U85								o
M_RGB48	Specifies 48-bit color depth (RGB 16:16:16) planar pixels. (summarize) Specifies 48-bit color depth (RGB 16:16:16) planar pixels. (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 value can be used with packed (M_PACKED) buffers in grab (M_GRAB) containers.	‡		c U85								o
M_RGB96	Specifies 96-bit color depth (RGB 32:32:32) packed or planar pixels.		‡	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	Specifies YUV16 packed or planar (4:2:2) standard. (summarize) Specifies YUV16 packed or planar (4:2:2) standard. (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 value can be used with packed (M_PACKED) buffers in grab (M_GRAB) containers.	‡	a

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 whether the buffer is mapped to Host memory by default.

This value is only available when ControlFlag is set to M_PHYSICAL_ADDRESS, or M_MIL_ID if ArrayOfDataPtr specifies a buffer with a physical address (that is, MbufInquire() with M_PHYSICAL_ADDRESS does not return M_NULL).

For specifying location information
Combination value	Description
M_MAPPABLE	Specifies that the buffer is not mapped to Host memory when it is created (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 mapping the buffer 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 creating a M_MAPPABLE buffer, it can be mapped and unmapped as needed. (summarize) Specifies that the buffer is not mapped to Host memory when it is created (that is, by default the buffer will have a physical address, but not a Host address). (more details...)

ControlFlag

Specifies the physical nature of the buffer. This parameter can be set to one of the values below.

For specifying the physical nature of the buffer
Value	Description		MIL system-specific tooltip (‡)
M_HOST_ADDRESS +	Specifies that ArrayOfDataPtr is a pointer to an array of 1 or 3 host addresses that point to the data. The number of pointers in the array depends on the number of bands and whether the data is compressed or packed. Note that when using logical addresses, memory protection errors could result. Note that you can use MbufInquire() with M_HOST_ADDRESS to get the logical address of a MIL allocated buffer. You must specify a combination value from the following table: To set how the pitch is measured (summarize) Specifies that ArrayOfDataPtr is a pointer to an array of 1 or 3 host addresses that point to the 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_MIL_ID +	Specifies that the new buffer maps to an existing source buffer. ArrayOfDataPtr is a pointer to an array that stores a pointer to the MIL identifier of the source buffer. You must specify a combination value from the following table: To set how the pitch is measured (summarize) Specifies that the new buffer maps to an existing source 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_PHYSICAL_ADDRESS +	Specifies that ArrayOfDataPtr is a pointer to an array of 1 or 3 physical addresses that point to the data. The number of pointers in the array depends on the number of bands and whether the data is compressed or packed. Note that using physical addresses provides direct access to any of your computer's memory mapped devices. Note that you can use MbufInquire() with M_PHYSICAL_ADDRESS to get the physical address of a MIL allocated buffer. You must specify a combination value from the following table: To set how the pitch is measured (summarize) Specifies that ArrayOfDataPtr is a pointer to an array of 1 or 3 physical addresses that point to the 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 must be used if the specified container has the M_GRAB attribute.	‡	a	c U85								o

Combination values for the values listed in For specifying the physical nature of the buffer.

You must add one of the following values to the above-mentioned values to set how the pitch is measured.

For specifying how the pitch is measured
Combination value	Description
M_PITCH	Specifies that the pitch is in pixels.
M_PITCH_BYTE	Specifies that the pitch is in bytes.

Pitch INQ

Specifies the size of the pitch. The pitch is the number of pixels or bytes (as specified by the ControlFlag parameter) between the start of any two adjacent rows of the buffer. The actual length of a row in the buffer, in physical memory, might be different from the value of the SizeX parameter (for example, due to use of buffer overscan).

Note that your code should not make assumptions about the actual pitch of the source memory. If the memory was allocated using an MbufAlloc...() function, use MbufInquire() with M_PITCH or M_PITCH_BYTE to establish the required pitch.

For specifying the size of the pitch
Value	Description
M_DEFAULT	Specifies that when dealing with a 1-bit buffer, the pitch is a multiple of 4 bytes; otherwise the pitch equals the SizeX parameter.
Value	Specifies the pitch in pixels or bytes (as determined by the ControlFlag parameter).

ArrayOfDataPtr

Specifies one or more data pointers that address the memory to which to map the created MIL buffer.

When pointing to a single-band buffer, a packed buffer, or a compressed buffer, a single pointer to the packed data must be provided. When pointing to an uncompressed planar buffer, one pointer per band must be provided (except when the ControlFlag parameter is set to M_MIL_ID). Pointers to a 3-band planar buffer must be ordered R-G-B or Y-U-V in the array.

When the ControlFlag parameter is set to M_MIL_ID, ArrayOfDataPtr specifies the address of an array that stores the MIL identifier of the source buffer.

When the ControlFlag parameter is set to M_HOST_ADDRESS, ArrayOfDataPtr specifies the address of an array that stores pointer(s) to the logical address(es) that points to the data.

When the ControlFlag parameter is set to M_PHYSICAL_ADDRESS, ArrayOfDataPtr specifies the address of an array that stores pointer(s) to the physical address(es) that points to the data.

ComponentType

Specifies the component type, which identifies what kind of information the buffer component stores.

For specifying the type of component
Value	Description
M_DEFAULT	Specifies the default component type. The default component type for image buffers is M_COMPONENT_INTENSITY. The default component type for all other buffers is M_COMPONENT_UNDEFINED. (summarize) Specifies the default component type. (more details...)
M_COMPONENT_CONFIDENCE	Specifies that the component stores confidence information for the M_COMPONENT_RANGE or M_COMPONENT_DISPARITY component of the container. Coordinates associated with the confidence value 0 are considered invalid data and will not be used by 3D image processing functions. A confidence component is associated with a range or disparity component in the same container when there are no other range, disparity, or confidence components in the container. If there is more than one range, disparity, and/or confidence component in a container (for example, because a single grab into the container transmitted multiple range and confidence components), you will need to either create a child container which contains only the required components using MbufChildContainer(), or free the extra components using MbufFreeComponent(). (summarize) Specifies that the component stores confidence information for the M_COMPONENT_RANGE or M_COMPONENT_DISPARITY component of the container. (more details...)
M_COMPONENT_CUSTOM + n	Specifies that the component has a custom component type, identified by n, where n can be a value between 0 and 254. You can use custom component types to identify components which store information that does not fit one of the standard component types. In addition, some cameras transmit components with custom component types. Refer to your camera manual to determine what type of information is stored in transmitted components. (summarize) Specifies that the component has a custom component type, identified by n, where n can be a value between 0 and 254. (more details...)
M_COMPONENT_DISPARITY	Specifies that the component stores a disparity map. Each pixel of a disparity map indicates the apparent distance (typically measured in pixel units) between where an object appears in the left and right images captured by a stereoscopic camera. (summarize) Specifies that the component stores a disparity map. (more details...)
M_COMPONENT_INFRARED	Specifies that the component stores an intensity image of infrared light.
M_COMPONENT_INTENSITY	Specifies that the component stores an intensity image of visible light.
M_COMPONENT_MESH_MIL	Specifies that the component stores mesh information for the M_COMPONENT_RANGE component of the container. A mesh component is associated with a range component in the same container when there are no other range or mesh components in that container. A point cloud container which has a mesh component is referred to as a meshed point cloud container. (summarize) Specifies that the component stores mesh information for the M_COMPONENT_RANGE component of the container. (more details...)
M_COMPONENT_METADATA	Specifies that the component stores metadata information. Metadata components are used by MIL internally. Typically, you should ignore metadata components in your application. (summarize) Specifies that the component stores metadata information. (more details...)
M_COMPONENT_MULTISPECTRAL	Specifies that the component stores an intensity image where each band represents the intensity of a specific wavelength of light. Unlike an intensity component, a multispectral component might include information about non-visible light. (summarize) Specifies that the component stores an intensity image where each band represents the intensity of a specific wavelength of light. (more details...)
M_COMPONENT_NORMALS_MIL	Specifies that the component stores normals information for each point in the M_COMPONENT_RANGE component of the container. A normals component is associated with a range component in the same container when there are no other range or normals components in that container. (summarize) Specifies that the component stores normals information for each point in the M_COMPONENT_RANGE component of the container. (more details...)
M_COMPONENT_RANGE	Specifies that the component stores 3D distance/position information. This can be either a 1-band buffer that stores a depth map, or a 3-band buffer that stores coordinates of 3D points. (summarize) Specifies that the component stores 3D distance/position information. (more details...)
M_COMPONENT_REFLECTANCE	Specifies that the component stores a reflectance map. Each pixel of a reflectance map indicates how much of the light hitting an object at that location is reflected back. Typically, this is an intensity image of the light spectrum used by a 3D sensor to detect 3D distance/position information. Typically, if the map was generated by a laser profiler, each row indicates the detected intensity of the laser for a single scan. (summarize) Specifies that the component stores a reflectance map. (more details...)
M_COMPONENT_SCATTER	Specifies that the component stores a scatter map. Each pixel of a scatter map indicates how much of the light hitting an object at that location is detected scattering beneath the object's surface. (summarize) Specifies that the component stores a scatter map. (more details...)
M_COMPONENT_ULTRAVIOLET	Specifies that the component stores an intensity image of ultraviolet light.
M_COMPONENT_UNDEFINED	Specifies that the component stores information of an unknown type.

ComponentIdPtr

Specifies the address of the variable in which to write the buffer identifier. Since the MbufCreateComponent() function also returns the buffer identifier, you can set this parameter to M_NULL. If mapping 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

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

Compilation information

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