MbufGetColor2d

See also

User Guide:

Managing data buffers

Reference:

MbufInquire

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

Function Map

- SrcBufId

- Band

Table:

For specifying the index of the band to copy

- OffX

- OffY

- SizeX

- SizeY

- UserArrayPtr

Parameter Associations

Table:	For specifying the data format
+ combination:	For setting the packed data format

Compilation information

Synopsis

Get data from an area of one or all bands of a buffer and place it in a user-supplied array.

Syntax

void MbufGetColor2d(

MIL_ID SrcBufId,	//in
MIL_INT64 DataFormat,	//in
MIL_INT Band,	//in
MIL_INT OffX,	//in
MIL_INT OffY,	//in
MIL_INT SizeX,	//in
MIL_INT SizeY,	//in
void *UserArrayPtr	//out

)

Description

This function copies data from a specific area of one or all bands of a specified MIL source buffer to a user-supplied array.

If the source buffer is compressed, MIL decompresses the data before copying it to the user-supplied array.

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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

SrcBufId

Specifies the identifier of the source buffer.

If the specified buffer is an image buffer with an associated region of interest (ROI), an error will occur.

DataFormat

Specifies the data format to use to save the data in the user array. The internal data format of the source buffer need not match the specified data format of the user-supplied array; an internal conversion will be performed if necessary. Note, however, if the formats do match, the operation will be much faster.

See the Parameter associations section for possible values that can be specified.

Band

Specifies the index of the band to copy. This parameter can be set to one of the values below.

For specifying the index of the band to copy

Value

Description

M_ALL_BANDS

Copies from all bands.

M_BLUE

Copies from the blue band (for RGB buffers).

M_GREEN

Copies from the green band (for RGB buffers).

M_HUE

Copies from the hue band (for HSL and HSV buffers).

M_LUMINANCE

Copies from the luminance band (for HSL buffers).

M_RED

Copies from the red band (for RGB buffers).

M_SATURATION

Copies from the saturation band (for HSL and HSV buffers).

M_V

Copies from the V band (for HSV buffers).

0 <= Value < #bands

Specifies the index of the band to copy.

The relationship between index value and band for RGB, HSL, and HSV buffers is the following:

0	Corresponds to the red band for RGB buffers, the hue band for HSL and HSV buffers.
1	Corresponds to the green band for RGB buffers or the saturation band for HSL and HSV buffers.
2	Corresponds to the blue band for RGB buffers, or the luminance band for HSL buffers, or the V band for HSV buffers.

(summarize)

Specifies the index of the band to copy.

(more details...)

OffX

Specifies the horizontal offset (relative to the top-left source buffer coordinate) of the source buffer area from which to get the data.

OffY

Specifies the vertical offset (relative to the top-left source buffer coordinate) of the source buffer area from which to get the data.

SizeX

Specifies the width of the source buffer area from which to get the data.

SizeY

Specifies the height of the source buffer area from which to get the data.

UserArrayPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer]
array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ]

Specifies the address of the user array in which to copy the data from the source buffer. Ensure that the user array is large enough to receive the data from the specified area and one or all bands of the source buffer.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The table below lists possible values for the DataFormat parameter and possible values returned to the UserArrayPtr parameter.

For specifying the data format

Note that SizeX and SizeY denote the source buffer's width and height, respectively.

For specifying the data format
DataFormat		Description
	UserArrayPtr - Possible values returned	Description
M_PACKED +		Copies the bands in an interleaved manner (for example, RGB RGB RGB...). This format is only valid when the Band parameter is set to M_ALL_BANDS. You must specify a combination value from the following table: To set the packed data format (summarize) Copies the bands in an interleaved manner (for example, RGB RGB RGB...). (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(defined elsewhere) * (defined elsewhere) * (defined elsewhere) Note: For the number of bytes (n), refer to the combination constants For setting the packed data format. Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(defined elsewhere) * (defined elsewhere) * (defined elsewhere) Note: For the number of bytes (n), refer to the combination constants For setting the packed data format.
M_PLANAR		Copies the bands one after the other in RGB planar format (for example, RRR...GGG...BBB...). This format is to be used when copying from all bands of the source buffer. (summarize) Copies the bands one after the other in RGB planar format (for example, RRR...GGG...BBB...). (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] MORE Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] Required array size:(SizeX) * (SizeY) * MbufInquire ( M_SIZE_BAND ) Data type info: Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] MORE Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] Required array size:(SizeX) * (SizeY) * MbufInquire ( M_SIZE_BAND )
M_SINGLE_BAND		Copies a single band. This format is not valid when the Band parameter is set to M_ALL_BANDS. (summarize) Copies a single band. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] MORE Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] Required array size:(SizeX) * (SizeY) Data type info: Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] MORE Data type: array of the same type as the buffer (SrcBufId) [optionally, in C++: a reference to a std::vector of the same type as the buffer] Required array size:(SizeX) * (SizeY)

Combination values for M_PACKED.

You must add one of the following values to the above-mentioned value to set the packed data format.

For more information on these formats, see the RGB buffers section of Chapter 21: Data buffers.

For setting the packed data format
DataFormat		Description
	UserArrayPtr - Possible values returned	Description
M_BGR24		Stores the data in a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes. (summarize) Stores the data in a BGR24 packed format. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(3 * (SizeX)) * (SizeY) Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(3 * (SizeX)) * (SizeY)
M_BGR32		Stores the data in a BGR32 packed format. In this format, each pixel is internally stored as four consecutive bytes. Every fourth byte is a "don't care" byte. (summarize) Stores the data in a BGR32 packed format. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(4 * (SizeX)) * (SizeY) Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(4 * (SizeX)) * (SizeY)
M_RGB15		Stores the data in an RGB15 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 5-bit green value, a 5-bit red value, and a "don't care" bit (most significant), in little-endian order (RGB 5:5:5). (summarize) Stores the data in an RGB15 packed format. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(2 * (SizeX)) * (SizeY) Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(2 * (SizeX)) * (SizeY)
M_RGB16		Stores the data in an RGB16 packed format. In this format, each pixel is internally stored as a 16-bit word with a 5-bit blue value (least significant), a 6-bit green value, and a 5-bit red value (most significant), in little-endian order (RGB 5:6:5). (summarize) Stores the data in an RGB16 packed format. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(2 * (SizeX)) * (SizeY) Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(2 * (SizeX)) * (SizeY)
M_RGB24		Stores the data in an RGB24 packed format. In this format, each pixel is internally stored as three consecutive bytes. (summarize) Stores the data in an RGB24 packed format. (more details...)
	UserArrayPtr extra info	Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(3 * (SizeX)) * (SizeY) Data type info: Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] MORE Data type: array of type unsigned-char [optionally, in C++: a reference to a std::vector<unsigned-char> ] Required array size:(3 * (SizeX)) * (SizeY)

Compilation information

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