| MIL 10 Reference
| Customize Help
| Save Settings

MbufTransfer



See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux with restrictions

Partially supported on:
Partially supported on Host system
Partially supported on Matrox CronosPlus
Partially supported on Matrox GPU processing driver
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox IEEE 1394 IIDC driver
Partially supported on Matrox Iris GT
Partially supported on Matrox Morphis
Partially supported on Matrox Morphis QxT
Partially supported on Matrox Orion HD
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl
Partially supported on Matrox USB3 Vision driver (requires Update 19)
Partially supported on Matrox Vio

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
Available on Matrox Supersight
function map Function map
Examples
Next
Synopsis
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 GPU processing driver, Matrox Radient eV-CLHS (requires Update 21), and Matrox Radient eV-CXP]

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 GPU processing driver]

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.

function map For the horizontal offset of the source region
CollapseValue Description
Collapse M_DEFAULT

Specifies the default value; the default value is 0 pixels.

Collapse M_NULL

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

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

function map For the vertical offset of the source region
CollapseValue Description
Collapse M_DEFAULT

Specifies the default value; the default value is 0 pixels.

Collapse M_NULL

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

Collapse Value

Specifies the vertical offset of the source region, in pixels.

SrcSizeX

Specifies the width of the source region.

function map For the width of the source region
CollapseValue Description
Collapse 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)
Collapse M_NULL

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

Collapse Value

Specifies the width of the source region, in pixels.

SrcSizeY

Specifies the height of the source region.

function map For the height of the source region
CollapseValue Description
Collapse 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)
Collapse M_NULL

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

Collapse 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:

function map For the color band of the region from which to copy
CollapseValue Description
Collapse M_DEFAULT

Same as M_ALL_BANDS.

Collapse M_NULL

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

Collapse M_ALL_BANDS

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

Collapse M_BLUE

Specifies the blue band (for RGB buffers).

Collapse M_GREEN

Specifies the green band (for RGB buffers).

Collapse M_HUE

Specifies the hue band (for HSL buffers).

Collapse M_LUMINANCE

Specifies the luminance band (for HSL buffers).

Collapse M_RED

Specifies the red band (for RGB buffers).

Collapse M_SATURATION

Specifies the saturation band (for HSL buffers).

Collapse M_U

Specifies the U band (for YUV buffers).

Collapse M_V

Specifies the V band (for YUV buffers).

Collapse M_Y

Specifies the Y band (for YUV buffers).

Collapse 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)
DestOffX

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

function map For the horizontal offset of the destination region
CollapseValue Description
Collapse M_DEFAULT

Specifies the default horizontal offset of the destination region. The default is equal to the horizontal offset of the source region.

(summarize)
Collapse 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.

function map For the vertical offset of the destination region
CollapseValue Description
Collapse M_DEFAULT

Specifies the default vertical offset of the destination region. The default is equal to the vertical offset of the source region.

(summarize)
Collapse Value

Specifies the value of the vertical offset of the destination region, in pixels.

DestSizeX

Specifies the width of the destination region.

function map For the width of the destination region
CollapseValue Description
Collapse 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)
Collapse Value

Specifies the width of the destination region, in pixels.

DestSizeY

Specifies the height of the destination region.

function map For the height of the destination region
CollapseValue Description
Collapse 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)
Collapse Value

Specifies the height of the destination region, in pixels.

DestBand

Specifies the color band of the destination region in which to copy. This parameter can be set to the same values as the SrcBand parameter, except for M_NULL.

TransferFunction

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

function map For specifying the function to use in the transfer
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse 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)
h
Collapse 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)
a b c e f g h i j k l m n o p q r s
Collapse M_CLEAR

Specifies a transfer function that clears the destination region. Set all source buffer parameters to M_NULL.

(summarize)
a b c d e f g h i j k l m n o p q r s
Collapse 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)
a b c d e f g h i j k l m n o p q r s
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 b c e f g h i j k l m o p q r s

Note that M_COMPOSITION is only supported with 1-band 8-bit buffers, 1-band 16-bit buffers, M_RGB16 buffers, and M_BGR32 buffers.

n

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.

b c e f g h j k l m o p q r s

The source buffer can either be M_MONO8 or M_BGR32 packed. If the source buffer is M_MONO8, then the destination buffer must be M_MONO8, M_MONO16, or M_BGR32 packed. If the source buffer is M_BGR32 packed, then the destination buffer must be M_BGR32 packed as well.

d

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
Collapse 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)
a b c d e f g h i j k l m n o p q r s
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 b c e f g h i j k l m n o p q r s
Combination constant for M_COPY.

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

function map For specifying the scale of M_COPY transfer function
CollapseCombination value Description
Collapse 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.

function map For specifying the type of transfer
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT

Transfers data using the most efficient transfer mode among the transfer modes listed.

a b c d e f g h i j k l m n o p q r s
Collapse 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)
a b c e f g h i j k l m n o p q r s
Collapse 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)
a b c d e f g h i j k l m n o p q r s
Collapse 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.

(summarize)
h
Collapse M_MIL_MODE +

Transfers data using the standard MIL mode.

This transfer mode is always possible.

(summarize)
a b c e f g h i j k l m n o p q r s
Combination constants 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.

function map For specifying synchronous data transfer
CollapseCombination value Description
Collapse 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)
Collapse 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.

function map For specifying a color value
CollapseValue Description
Collapse
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)
Parameters

Specifies the red component, as a value between 0 and 255.

Specifies the green component, as a value between 0 and 255.

Specifies the blue component, as a value between 0 and 255.

Collapse M_COLOR_BLACK

Specifies the color black.

Collapse M_COLOR_BLUE

Specifies the color blue.

Collapse M_COLOR_BRIGHT_GRAY

Specifies the color bright gray.

Collapse M_COLOR_CYAN

Specifies the color cyan.

Collapse M_COLOR_DARK_BLUE

Specifies the color dark blue.

Collapse M_COLOR_DARK_CYAN

Specifies the color dark cyan.

Collapse M_COLOR_DARK_GREEN

Specifies the color dark green.

Collapse M_COLOR_DARK_MAGENTA

Specifies the color dark magenta.

Collapse M_COLOR_DARK_RED

Specifies the color dark red.

Collapse M_COLOR_DARK_YELLOW

Specifies the color dark yellow.

Collapse M_COLOR_GRAY

Specifies the color gray.

Collapse M_COLOR_GREEN

Specifies the color green.

Collapse M_COLOR_LIGHT_BLUE

Specifies the color light blue.

Collapse M_COLOR_LIGHT_GRAY

Specifies the color light gray.

Collapse M_COLOR_LIGHT_GREEN

Specifies the color light green.

Collapse M_COLOR_LIGHT_WHITE

Specifies the color light white.

Collapse M_COLOR_MAGENTA

Specifies the color magenta.

Collapse M_COLOR_RED

Specifies the color red.

Collapse M_COLOR_WHITE

Specifies the color white.

Collapse 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:

function map For specifying a grayscale value to be used with all bands
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse 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)
a b c d e f g h i j k l m n o p q r s
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

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.
NONE NONE DEFAULT NULL DEFAULT NULL DEFAULT NULL DEFAULT NULL DEFAULT NULL ALL BANDS BLUE GREEN HUE LUMINANCE RED SATURATION U V Y DEFAULT DEFAULT DEFAULT DEFAULT ALPHA BLENDING BYTE SWAP CLEAR COMPOSITION COPY SCALE DEFAULT DIB MODE DIRECTX MODE DRIVER MODE MIL MODE ASYNCHRONOUS SYNCHRONOUS COLOR BLACK COLOR BLUE COLOR BRIGHT GRAY COLOR CYAN COLOR DARK BLUE COLOR DARK CYAN COLOR DARK GREEN COLOR DARK MAGENTA COLOR DARK RED COLOR DARK YELLOW COLOR GRAY COLOR GREEN COLOR LIGHT BLUE COLOR LIGHT GRAY COLOR LIGHT GREEN COLOR LIGHT WHITE COLOR MAGENTA COLOR RED COLOR WHITE COLOR YELLOW