MbufTransfer

Copy a two-dimensional region of one or all bands from the source buffer into a two-dimensional region of one or all bands in the destination buffer, using a specified transfer function and transfer type.

Syntax

void MbufTransfer(

MIL_ID SrcBufId,	//in
MIL_ID DestBufId,	//in
MIL_INT SrcOffX,	//in
MIL_INT SrcOffY,	//in
MIL_INT SrcSizeX,	//in
MIL_INT SrcSizeY,	//in
MIL_INT SrcBand,	//in
MIL_INT DestOffX,	//in
MIL_INT DestOffY,	//in
MIL_INT DestSizeX,	//in
MIL_INT DestSizeY,	//in
MIL_INT DestBand,	//in
MIL_INT64 TransferFunction,	//in
MIL_INT64 TransferType,	//in
MIL_INT64 OperationFlag,	//in
void *ExtraParameterPtr	//in

)

Description

This function copies a two-dimensional region of one or all color bands of the source buffer to a two-dimensional region of one or all bands of the destination buffer, using a specified transfer function and transfer type.

If the size of the regions in the source and destination buffers differ, the size of the largest region is reduced so that the size of the source and destination regions become equal.

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

SrcBufId

Specifies the identifier of the source buffer. When the TransferFunction parameter is set to M_CLEAR, you must set this parameter to M_NULL; when the TransferFunction parameter is set to M_BYTE_SWAP, you can set this parameter to M_NULL to swap bytes within the same buffer.

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

[All except Matrox Concord PoE with ToE (Update 82), Matrox Indio (introduced U53), Matrox Radient eV-CXP (introduced M10), and Matrox Rapixo CXP (introduced U75)]

Floating-point buffers are only supported when the TransferFunction parameter is set to M_COPY.

DestBufId

Specifies the identifier of the destination buffer.

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

[All except Matrox Concord PoE with ToE (Update 82) and Matrox Indio (introduced U53)]

Floating-point buffers are only supported when the TransferFunction parameter is set to M_COPY.

SrcOffX

Specifies the horizontal offset of the source region, relative to the top-left coordinate of the source buffer.

For the horizontal offset of the source region
Value	Description
M_DEFAULT	Specifies the default value; the default value is 0 pixels.
M_NULL	Specifies that the horizontal offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.
Value	Specifies the horizontal offset of the source region, in pixels.

SrcOffY

Specifies the vertical offset of the source region, relative to the top-left coordinate of the source buffer.

For the vertical offset of the source region
Value	Description
M_DEFAULT	Specifies the default value; the default value is 0 pixels.
M_NULL	Specifies that the vertical offset of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.
Value	Specifies the vertical offset of the source region, in pixels.

SrcSizeX

Specifies the width of the source region.

For the width of the source region
Value	Description
M_DEFAULT	Specifies the default width of the source region. The default is equal to the difference between the width of the source buffer and the horizontal offset of the source region. (summarize) Specifies the default width of the source region. (more details...)
M_NULL	Specifies that the width of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.
Value	Specifies the width of the source region, in pixels.

SrcSizeY

Specifies the height of the source region.

For the height of the source region
Value	Description
M_DEFAULT	Specifies the default height of the source region. The default is equal to the difference between the height of the source buffer and the vertical offset of the source region. (summarize) Specifies the default height of the source region. (more details...)
M_NULL	Specifies that the height of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.
Value	Specifies the height of the source region, in pixels.

SrcBand

Specifies the color band of the region from which to copy. This parameter can be set to one of the following values:

For the color band of the region from which to copy

Value

Description

M_DEFAULT

Same as M_ALL_BANDS.

M_NULL

Specifies that the band of the source region is ignored when the TransferFunction parameter is set to M_CLEAR.

M_ALL_BANDS

Specifies all color bands (for RGB, HSL, and YUV buffers).

M_BLUE

Specifies the blue band (for RGB buffers).

M_GREEN

Specifies the green band (for RGB buffers).

M_HUE

Specifies the hue band (for HSL buffers).

M_LUMINANCE

Specifies the luminance band (for HSL buffers).

M_RED

Specifies the red band (for RGB buffers).

M_SATURATION

Specifies the saturation band (for HSL buffers).

M_U

Specifies the U band (for YUV buffers).

M_V

Specifies the V band (for YUV buffers).

M_Y

Specifies the Y band (for YUV buffers).

0 <= Value < #bands

Specifies the index of the band to copy.

The relationship between the 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)

Specifies the index of the band to copy.

(more details...)

DestOffX

Specifies the horizontal offset of the destination region, relative to the top-left coordinate of the destination buffer.

For the horizontal offset of the destination region
Value	Description
M_DEFAULT	Specifies the default horizontal offset of the destination region. The default is equal to the horizontal offset of the source region. (summarize) Specifies the default horizontal offset of the destination region. (more details...)
Value	Specifies the horizontal offset of the destination region, in pixels.

DestOffY

Specifies the vertical offset of the destination region, relative to the top-left coordinate of the destination buffer.

For the vertical offset of the destination region
Value	Description
M_DEFAULT	Specifies the default vertical offset of the destination region. The default is equal to the vertical offset of the source region. (summarize) Specifies the default vertical offset of the destination region. (more details...)
Value	Specifies the value of the vertical offset of the destination region, in pixels.

DestSizeX

Specifies the width of the destination region.

For the width of the destination region
Value	Description
M_DEFAULT	Specifies the default width of the destination region. The default is equal to the difference between the destination buffer width and the horizontal offset of the destination region. (summarize) Specifies the default width of the destination region. (more details...)
Value	Specifies the width of the destination region, in pixels.

DestSizeY

Specifies the height of the destination region.

For the height of the destination region
Value	Description
M_DEFAULT	Specifies the default height of the destination region. The default is equal to the difference between the destination buffer height and the vertical offset of the destination region. (summarize) Specifies the default height of the destination region. (more details...)
Value	Specifies the height of the destination region, in pixels.

DestBand

Specifies the color band of the destination region in which to copy.

For the color band of the region in which to copy

Value

Description

M_DEFAULT

Same as M_ALL_BANDS.

M_ALL_BANDS

Specifies all color bands (for RGB, HSL, and YUV buffers).

M_BLUE

Specifies the blue band (for RGB buffers).

M_GREEN

Specifies the green band (for RGB buffers).

M_HUE

Specifies the hue band (for HSL buffers).

M_LUMINANCE

Specifies the luminance band (for HSL buffers).

M_RED

Specifies the red band (for RGB buffers).

M_SATURATION

Specifies the saturation band (for HSL buffers).

M_U

Specifies the U band (for YUV buffers).

M_V

Specifies the V band (for YUV buffers).

M_Y

Specifies the Y band (for YUV buffers).

0 <= Value < #bands

Specifies the index of the band in which to copy.

The relationship between the 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)

Specifies the index of the band in which to copy.

(more details...)

TransferFunction

Specifies the function to use in the transfer. This parameter can be set to one of the following:

For specifying the function to use in the transfer
Value	Description		MIL system-specific tooltip (‡)
M_ALPHA_BLENDING	Specifies a transfer function that combines an image with an overlay to create the appearance of partial transparency. The source and destination buffers must both be allocated on-board with a format of M_YUV16 + M_PACKED. When using MbufCreateColor(), the supported overlay buffer formats are M_YUV16 + M_PACKED and M_RGB16 + M_PACKED. Note that overlay buffers are only available when the TransferType parameter is set to M_DRIVER_MODE. (summarize) Specifies a transfer function that combines an image with an overlay to create the appearance of partial transparency. (more details...)		‡				h
M_BYTE_SWAP	Specifies a transfer function that extracts the bytes in each pixel of the source region, swaps them, and copies the new pixels into the destination region. Note that M_BYTE_SWAP is only supported when the source and destination buffers are both either 1-band 16-bit buffers or 1-band 32-bit buffers and have the same internal storage specifiers. When using 16-bit buffers, the first byte is swapped with the last byte. When using 32-bit buffers, the first byte is swapped with the last byte and the two middle bytes are swapped. You can swap bytes within the same buffer. To do so, set the SrcBufId parameter to M_NULL. (summarize) Specifies a transfer function that extracts the bytes in each pixel of the source region, swaps them, and copies the new pixels into the destination region. (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_CLEAR	Specifies a transfer function that clears the destination region. Set all source buffer parameters to M_NULL. (summarize) Specifies a transfer function that clears the destination region. (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_COMPOSITION	Specifies a transfer function that copies all pixels, except for pixels in the source region that are equal to the composition color specified by the OperationFlag parameter. (summarize) Specifies a transfer function that copies all pixels, except for pixels in the source region that are equal to the composition color specified by the OperationFlag parameter. (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
		Note that M_COMPOSITION is only supported with 1-band 8-bit buffers, 1-band 16-bit buffers, M_RGB16 buffers, M_BGR24 buffers, and M_BGR32 buffers.	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	y U75	aa
		The source and destination buffers must have the same number of bands, the same data-depth per band, and the same storage specifiers, unless the source is a 1-band, 8-bit buffer. In which case, the destination buffer can be a 3-band 8-bit buffer and the source region band is copied into each of the bands of the destination region. If both regions are multi-band, each source band is copied to the corresponding band of the destination.	‡		c M10	g	h		j	k M10	l	m	o	p	r U27	t U28		v	y U75	aa
		When the TransferType parameter is set to M_DRIVER_MODE, the source and destination buffers must also be allocated with the M_ON_BOARD attribute. The source buffer and destination buffer format is M_YUV16 + M_PACKED.	‡				h
M_COPY +	Specifies a transfer function that copies the data from the source region into the destination region. If the source and destination buffers are of different data types, MIL converts the data automatically. When copying from a floating-point buffer to an integer buffer, the values are truncated. If the source is a 3-band region of a YUV buffer and the destination is a 1-band region, only the Y band (luminance) is copied. If the source is a 3-band region of an RGB buffer and the destination is a 1-band region, only the red band is copied. If both regions are multi-band, each source band is copied to the corresponding band of the destination. Note that when copying from a non-binary buffer to a binary destination buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary destination buffer. When copying a binary buffer to a buffer of a different depth, each bit is copied into the least-significant bit of a different destination pixel using the specified transfer function. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize(). (summarize) Specifies a transfer function that copies the data from the source region into the destination region. (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
		In addition, if the source is a 1-band image buffer associated with a LUT buffer and the destination is 3-band, the source data is first mapped through the LUT before being copied to the destination.	‡	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_COPY.

You can add the following value to the above-mentioned value to set the scale of the M_COPY transfer function.

For specifying the scale of M_COPY transfer function
Combination value	Description
M_SCALE	Specifies that the data of the source region must be scaled to fit in the destination region.

TransferType

Specifies the type of transfer. If M_DEFAULT is not selected, then any combination of the transfer modes listed below can be specified for the TransferType parameter. From this combination of transfer modes, MIL selects the most efficient mode to transfer data. If the most efficient transfer mode fails, then MIL automatically selects the next most efficient transfer mode from the combination of transfer modes. If all selected transfer modes fail, an error is returned. The efficiency of the transfer mode depends on the internal format of the source and destination buffers, as well as the hardware available in your computer.

For specifying the type of transfer
Value	Description	MIL system-specific tooltip (‡)
M_DEFAULT	Transfers data using the most efficient transfer mode among the transfer modes listed.	‡	a	c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v	y U75	aa
M_DIB_MODE +	[This is only applicable to Windows] Transfers data using the DIB interface. Both the source and destination buffers must have the M_DIB attribute. This transfer mode is only possible when the TransferFunction parameter is set to M_COPY. (summarize) [This is only applicable to Windows] Transfers data using the DIB interface. (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_DIRECTX_MODE +	[This is only applicable to Windows] Transfers data using the DirectX interface. Both the source and destination buffers must have the M_DIRECTX attribute. This transfer mode is only possible when the TransferFunction parameter is set to M_CLEAR, M_COMPOSITION, or M_COPY. (summarize) [This is only applicable to Windows] Transfers data using the DirectX interface. (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_DRIVER_MODE +	Transfers data using the driver. Note that overlay buffers are only available when the TransferFunction parameter is set to M_ALPHA_BLENDING and the ExtraParameterPtr parameter is set to a MIL buffer identifier. This transfer mode is only possible when the TransferFunction parameter is set to M_ALPHA_BLENDING, M_COMPOSITION, or M_COPY. (summarize) Transfers data using the driver. (more details...)	‡				h
M_MIL_MODE +	Transfers data using the standard MIL mode. This transfer mode is always possible. (summarize) Transfers data using the standard MIL mode. (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 the values listed in For specifying the type of transfer.

You can add one of the following values to the above-mentioned values to set whether to transfer the data synchronously.

By default, the MbufTransfer() function chooses the value that is the most efficient for data transfer.

For specifying synchronous data transfer
Combination value	Description
M_ASYNCHRONOUS	Specifies that the transfer of data is not synchronous. This setting is only possible when the TransferType parameter is equal to M_DIRECTX_MODE. (summarize) Specifies that the transfer of data is not synchronous. (more details...)
M_SYNCHRONOUS	Specifies that the transfer of data is synchronous.

OperationFlag

Specifies the color value that is passed to the transfer function. If the TransferFunction parameter is set to M_COPY or M_BYTE_SWAP, this parameter must be set to M_NULL.

If the TransferFunction parameter is set to M_CLEAR or M_COMPOSITION, you can set this parameter to one of the following values for a 3-band image buffer:

[Matrox Morphis QxT]

When dealing with an overlay buffer, this value specifies the overlay transparency value. Supported values are from 0 to 255.

For specifying a color value
Value	Description
M_RGB888( MIL_INT Red, MIL_INT Green, MIL_INT Blue )	Specifies an RGB value. Specify an RGB value when the source buffer is a 3-band buffer. (summarize) Specifies an RGB value. (more details...)
		Parameters
		Red Specifies the red component, as a value between 0 and 255.
		Green Specifies the green component, as a value between 0 and 255.
		Blue Specifies the blue component, as a value between 0 and 255.
M_COLOR_BLACK	Specifies the color black.
M_COLOR_BLUE	Specifies the color blue.
M_COLOR_BRIGHT_GRAY	Specifies the color bright gray.
M_COLOR_CYAN	Specifies the color cyan.
M_COLOR_DARK_BLUE	Specifies the color dark blue.
M_COLOR_DARK_CYAN	Specifies the color dark cyan.
M_COLOR_DARK_GREEN	Specifies the color dark green.
M_COLOR_DARK_MAGENTA	Specifies the color dark magenta.
M_COLOR_DARK_RED	Specifies the color dark red.
M_COLOR_DARK_YELLOW	Specifies the color dark yellow.
M_COLOR_GRAY	Specifies the color gray.
M_COLOR_GREEN	Specifies the color green.
M_COLOR_LIGHT_BLUE	Specifies the color light blue.
M_COLOR_LIGHT_GRAY	Specifies the color light gray.
M_COLOR_LIGHT_GREEN	Specifies the color light green.
M_COLOR_LIGHT_WHITE	Specifies the color light white.
M_COLOR_MAGENTA	Specifies the color magenta.
M_COLOR_RED	Specifies the color red.
M_COLOR_WHITE	Specifies the color white.
M_COLOR_YELLOW	Specifies the color yellow.

For a 1-band or 3-band image buffer, you can set this parameter to the following grayscale value:

For specifying a grayscale value to be used with all bands
Value	Description		MIL system-specific tooltip (‡)
Value	Specifies a grayscale value used to clear the 1-band or multi-band buffer. This value is cast to the buffer type and depth. If the destination buffer is 3-band, this value will be replicated in each band. (summarize) Specifies a grayscale value used to clear the 1-band or multi-band 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
		MIL system specific
		Specifies the overlay transparency value. A value of 0 represents 100% of the source buffer and 0% of the overlay buffer. A value of 255 represents 0% of the source buffer and 100% of the overlay buffer. A value of 128 represents 50% of the source buffer and 50% of the overlay buffer. Note that overlay buffers are only available when the TransferFunction parameter is set to M_ALPHA_BLENDING and the TransferType parameter is set to M_DRIVER_MODE.	‡				h

ExtraParameterPtr

Accepts the following address:

Data type: address of a MIL_ID Note: When using M_ALPHA_BLENDING and M_DRIVER_MODE

Data type: Set this parameter to M_NULL Note: When not using M_ALPHA_BLENDING and M_DRIVER_MODE

Specifies a pointer to the MIL identifier of the overlay buffer, if applicable. Set this parameter to M_NULL in all other cases.

[Matrox Morphis QxT]

Note that overlay buffers are only available when the TransferFunction parameter is set to M_ALPHA_BLENDING and the TransferType parameter is set to M_DRIVER_MODE.

Compilation information

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