MbufCreateColor

Specifies the MIL system on which to create 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().

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

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

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

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

Specifies the buffer usage. This allows you to specify the type of buffer, intended purpose, 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.

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.

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_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...)

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.

Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.

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 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...)		‡	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. You must specify a combination value from the following table: To set a color buffer format (summarize) Specifies an image buffer that can be displayed. (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_GRAB +	Specifies an image buffer in which to grab data. The physical nature of the buffers (using the ControlFlag) must be set to M_PHYSICAL_ADDRESS. You must specify a combination value from the following table: To set a color buffer format (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 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 that can be processed. You must specify a combination value from the following table: To set a color buffer format (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 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 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, 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 buffers (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 buffers (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) buffers.	‡		c U85								o					v
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) buffers.	‡		c U85								o					v
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) buffers.	‡		c U85								o					v
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) buffers.	‡		c U85								o					v

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 buffers (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 planar (M_PLANAR) grab (M_GRAB) buffers.	‡						j	k M10	l	m		p	r U27	t U28				y U75		aa
		This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.	‡		c M10								o					v
M_RGB48	Specifies 48-bit color depth (RGB 16:16:16). packed or planar pixels. (summarize) Specifies 48-bit color depth (RGB 16:16:16). (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) grab (M_GRAB) buffers.	‡		c M10				j	k M10	l	m	o	p	r U27			v		y U75		aa
		This value can be used with planar (M_PLANAR) grab (M_GRAB) buffers.	‡						j	k M10	l	m		p	r U27					y U75		aa
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) grab (M_GRAB) buffers.	‡	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 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...)

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 buffer has the M_GRAB attribute.	‡	a	c M10								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.

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

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.

Specifies the address of the variable in which to write the buffer identifier. Since the MbufCreateColor() function also returns the buffer identifier, you can set this parameter to M_NULL. If mapping fails, M_NULL is written as the identifier.