| MIL 10 Reference
| Customize Help
| Save Settings

MbufGetColor2d


See also
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
Available on Matrox Supersight
function map Function map
Examples
None.
MbufGetArc
MbufGetColor
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.

function map For specifying the index of the band to copy
CollapseValue Description
Collapse M_ALL_BANDS

Copies from all bands.
Collapse M_BLUE

Copies from the blue band (for RGB buffers).
Collapse M_GREEN

Copies from the green band (for RGB buffers).
Collapse M_HUE

Copies from the hue band (for HSL buffers).
Collapse M_LUMINANCE

Copies from the luminance band (for HSL buffers).
Collapse M_RED

Copies from the red band (for RGB buffers).
Collapse M_SATURATION

Copies from the saturation band (for HSL buffers).
Collapse 0 <= Value < #bands

Specifies the index of the band to copy.

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

0

Corresponds to the red band for RGB buffers or the hue band for HSL buffers.

1

Corresponds to the green band for RGB buffers or the saturation band for HSL buffers.

2

Corresponds to the blue band for RGB buffers or the luminance band for HSL buffers.
(summarize)
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 same type as the buffer
  • array of type 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.

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

function map For specifying the data format
CollapseDataFormat Description
UserArrayPtr
- Possible values returned
Collapse 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:
(summarize)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x n bytes (unsigned char)
Note: For the number of bytes (n), refer to the combination constants For setting the packed data format.

Collapse 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)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x number of bands of the source buffer

Collapse M_SINGLE_BAND

Copies a single band.

(summarize)
Collapse UserArrayPtr data type info

Data type: array of same type as the buffer
Array size: SizeX x SizeY

Combination constants 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 19: Data buffers.

function map For setting the packed data format
CollapseDataFormat Description
UserArrayPtr
- Possible values returned
Collapse M_BGR24

Stores the data in a BGR24 packed format. In this format, each pixel is internally stored as three consecutive bytes.

(summarize)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x 3 bytes (unsigned char)

Collapse 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)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x 4 bytes (unsigned char)

Collapse 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)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x 2 bytes (unsigned char)

Collapse 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)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x 2 bytes (unsigned char)

Collapse M_RGB24

Stores the data in an RGB24 packed format. In this format, each pixel is internally stored as three consecutive bytes.

(summarize)
Collapse UserArrayPtr data type info

Data type: array of type unsigned char
Array size: SizeX x SizeY x 3 bytes (unsigned char)

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
NONE ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION SIZE X SIZE Y SIZE X SIZE Y PACKED PLANAR SINGLE BAND BGR24 BGR32 RGB15 RGB16 RGB24