| MIL 10 Reference
| Customize Help
| Save Settings

MbufControl


See also
Availability
Available in MIL-Lite with restrictions (see remarks)
Available in MIL

Available on Windows with restrictions
Available on Linux with restrictions

Partially supported on:
Partially supported on Host system
Partially supported on Matrox GPU processing driver
Partially supported on Matrox Iris GT
Partially supported on Matrox Orion HD
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP

Fully supported on:
Fully supported on Matrox CronosPlus
Fully supported on Matrox GigE Vision driver
Fully supported on Matrox IEEE 1394 IIDC driver
Fully supported on Matrox Morphis
Fully supported on Matrox Morphis QxT
Fully supported on Matrox Solios eA/XA
Fully supported on Matrox Solios ecl/xcl/ev-cl
Fully supported on Matrox USB3 Vision driver (requires Update 19)
Fully 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
MbufClone
MbufControlArea
Synopsis
Control a specified data buffer setting.
Syntax
void MbufControl(
MIL_ID BufId, //in
MIL_INT64 ControlType, //in
MIL_DOUBLE ControlValue //in
)
Description

This function allows you to control a specified data buffer setting.

When compiling C code in 64-bit mode, MbufControl() internally calls the MIL_INT64 version of this function (MbufControlInt64()). If you need to pass floating-point values, call the MIL_DOUBLE version of this function (MbufControlDouble()).
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
BufId

Specifies the identifier of the buffer to control.

ControlType

Specifies the buffer setting to control.

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

ControlValue

Specifies the value needed for the setting.

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

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

The following ControlType and corresponding ControlValue parameter settings are used to control general buffer settings.

function map For specifying general buffer settings
CollapseControlType Description
MIL system-specific
tooltip (†)
ControlValue
Collapse M_ASSOCIATED_LUT

Sets whether to associate or disassociate a LUT buffer with the specified image buffer. The image buffer must be a 1-band 8-bit or 16-bit buffer. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies to remove the association between the LUT buffer and the image buffer.

 † a b c d e f g h i j k l m n o p q r s
Collapse MIL LUT buffer identifier

Specifies the MIL identifier of the LUT buffer to associate with the image buffer. If and when the image buffer is selected to a display, the required changes occur to produce the display effect of the LUT, unless the display is also associated with a LUT (MdispLut()). If associated with a LUT buffer, the image buffer cannot be selected to a display whose view mode is set to M_AUTO_SCALE or M_MULTI_BYTES.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DC_ALLOC
[This is only applicable to Windows]

Allocates a device context (DC) for drawing. Determine the DC handle (HDC) using MbufInquire() with the M_DC_HANDLE inquire type. When using this control type, the buffer should be internally stored in M_GDI format, and cannot be a child buffer. No MIL operation can be done between a device context allocation and free, therefore you should use the device context for a short period of time.

(summarize)
† b c d e g h l m n o s
Collapse M_DEFAULT

Implements the default behavior.

 † b c d e g h l m n o s
Collapse M_DC_FREE
[This is only applicable to Windows]

Frees a device context (DC).

(summarize)
† b c d e g h l m n o s
Collapse M_DEFAULT

Implements the default behavior.

 † b c d e g h l m n o s
Collapse M_LOCK +

Locks the specified buffer to allow a memory pointer to obtain a valid buffer address. The address is valid while the buffer is locked, but becomes invalid after it is unlocked. The calling thread will be blocked if the buffer is already locked by a different thread.

To unlock the specified buffer, use M_UNLOCK.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Implements the default behavior.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_MAP

Maps or unmaps the buffer to the memory address space of the process. Note that, to use this control, the buffer must be allocated with the M_MAPPABLE attribute.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_DISABLE

Unmaps the buffer from the address space of the process. This sets the buffer's Host address to M_NULL.

This is the default value.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_ENABLE

Maps the buffer to the address space of the process. This associates the buffer with a logical Host address.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_MAX

Sets the expected maximum pixel value of the buffer. This information is used to optimize certain processing operations on the buffer and the display of the buffer. Note that this information is not validated against the content of the buffer.

M_MIN and M_MAX should specify the expected range of pixel values in the buffer. Values larger than the maximum value or smaller than the minimum value can result in undetermined effects upon processing and display. Pixel values between M_MIN and M_MAX are remapped linearly to values between the minimum and maximum possible display values. With processing, the values of the buffer could be truncated producing undesirable effects.

Note that these two values are static and not updated automatically. For example, if you set M_MAX to 50, and during computation you multiplied the buffer by 2, M_MAX would still be 50 and not 100.

Note that M_MIN and M_MAX cannot be used with child buffers; this information is obtained directly from the parent buffer. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse Value

Specifies the expected maximum pixel value within the range of the buffer type. For example, for an 8-bit unsigned buffer, set this value to a value between 0 and 255, inclusive.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_MIN

Sets the expected minimum pixel value possible in the buffer. This information is used to optimize certain procesing operations on the buffer and the display of the buffer. Note that this information is not validated against the content of the buffer.

M_MIN and M_MAX should specify the expected range of pixel values in the buffer. Values larger than the maximum value or smaller than the minimum value can result in undetermined effects upon processing and display. Pixel values between M_MIN and M_MAX are remapped linearly to values between the minimum and maximum possible display values. With processing, the values of the buffer could be truncated producing undesirable effects.

Note that these two values are static and not updated automatically. For example, if you set M_MAX to 50, and during computation you multiplied the buffer by 2, M_MAX would still be 50 and not 100.

Note that M_MIN and M_MAX cannot be used with child buffers; this information is obtained directly from the parent buffer. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse Value

Specifies the expected minimum pixel value within the range of the buffer type. For example, for an 8-bit unsigned buffer, set this value to a value between 0 and 255, inclusive.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_MODIFICATION_HOOK

Sets whether to run the user-defined functions hooked to the buffer's modification event upon the event. These user-defined functions are initially hooked to the buffer modification event using MbufHookFunction(). INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DISABLE

Specifies that the user-defined functions should not be called.

Note that the modification counter of the image buffer will still be incremented. To inquire the count, use MbufInquire() with M_MODIFICATION_COUNT.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_ENABLE

Specifies that the user-defined functions should be called.

This is the default value.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_MODIFIED

Signals MIL that the buffer content was modified without using MIL. This control must be used to ensure that MIL updates its internal information on the buffer. For example, if a display buffer was modified outside MIL, the display will not be updated until you use this control. Note, if only a certain region of the buffer was modified, it is more efficient to specify an appropriate child buffer as BufId.

If a specific area of the buffer was modified without using MIL, it is faster to use MbufControlArea() with the control type to signal MIL to update the content of the specified area of the buffer.

M_MODIFIED increments the buffer's modification counter. You can inquire about the counter's current value using MbufInquire() with M_MODIFICATION_COUNT.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Implements the default behavior.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_RESOLUTION_X

Sets the X resolution of the image buffer in pixels per inch (PPI). INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies an X resolution of 72 PPI.

 † a b c d e f g h i j k l m n o p q r s
Collapse Value

Specifies the X resolution in PPI.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_RESOLUTION_Y

Sets the Y resolution of the image buffer in pixels per inch (PPI). INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Specifies a Y resolution of 72 PPI.

 † a b c d e f g h i j k l m n o p q r s
Collapse Value

Specifies the Y resolution in PPI.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_UNLOCK

Unlocks the specified buffer.

The buffer must have been previously locked with M_LOCK.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Implements the default behavior.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_XPIXMAP_ALLOC
[This is only applicable to Linux]

Allocates a device context for drawing. Determine the device context handle using MbufInquire() with the M_XPIXMAP_HANDLE inquire type. When using this control type, the buffer should be internally stored in M_LINUX_MXIMAGE format. No MIL operation can be done between a device context allocation and free, therefore you should use the device context for a short period of time.

(summarize)
† b c d e g h j k l m n o p q r s
Collapse M_DEFAULT

Implements the default behavior.

 † b c d e g h j k l m n o p q r s
Collapse M_XPIXMAP_FREE
[This is only applicable to Linux]

Frees a pixmap.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Implements the default behavior.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_YCBCR_RANGE

Specifies whether the YUV buffer's pixel values are YCbCr encoded, which limits the range of the buffer's pixel values. The Y-band's pixel values are limited between 16 and 235. The Cb- and Cr-bands are limited to pixel values between 16 and 240.

Note that YCbCr is a scaled and offset version of the YUV color space. Calling M_YCBCR_RANGE on an RGB buffer will generate an error. The buffer must be of an uncompressed packed YUV16 type. INQ

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DEFAULT

Same as M_DISABLE.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_DISABLE

Specifies not to YCbCr encode the YUV buffer's pixel values.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_YCBCR_HD

Specifies to encode the YUV buffer's pixel values using the high-definition YCbCr standard.

 † a b c d e f g h i j k l m n o p q r s
Collapse M_YCBCR_SD

Specifies to encode the YUV buffer's pixel values using the standard-definition YCbCr standard.

 † a b c d e f g h i j k l m n o p q r s
Combination constants for M_LOCK.

You can add one of the following values to the above-mentioned value to set which processor can access the locked buffer.

function map For M_LOCK (Processor access privileges)
CollapseCombination value Description
Collapse M_GPU_ACCESS

Locks the buffer and gives access to the GPU processor.
Collapse M_HOST_ACCESS

Locks the buffer and gives access to the Host processor.

This is the default value.

(summarize)
Combination constants for M_LOCK.

You can add one or more of the following values to the above-mentioned value to set the buffer's read and write permission.

function map For M_LOCK (Read and write permission)
CollapseCombination value Description
Collapse M_READ

Locks the buffer to be read only.
Collapse M_READ+M_WRITE

Locks the buffer to be read and write.

This is the default value.

(summarize)
Collapse M_WRITE

Locks the buffer to be write only.

For buffers with an M_IMAGE + M_COMPRESS attribute, ControlType and ControlValue can also be set to one of the values below.

Note that, if the buffer contains any data, setting one of these control types automatically deletes the data. This is because, for MIL to decompress the buffer's data, it must know the control values that were used in the compression. If you change one of these controls, MIL will be unable to decompress the data and the data is therefore irrelevant. Note that the control type M_TARGET_SIZE is the only control type that can be changed without affecting the data. For more information, see Chapter 27: JPEG and JPEG2000 compression.

function map For M_IMAGE + M_COMPRESS image buffers
CollapseControlType Description
ControlValue
Collapse M_DECOMPOSITION_LEVEL +

Sets the number of iterations (decomposition levels) the discrete wavelet transform is applied to the image. This control type is only supported with JPEG2000 buffers (both lossy and losseless).

The number of decomposition levels is applied to all bands by default. INQ

(summarize)
Collapse Value >= 0

Specifies the number of iterations (decomposition levels). Only integer values are accepted.

(summarize)
Collapse M_HUFFMAN_AC

Associates an AC Huffman table to the buffer. This control type is only supported with JPEG lossy buffers. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table. If the buffer is 3-band, the same table is applied to all bands.

(summarize)
Collapse M_HUFFMAN_AC_CHROMINANCE

Associates an AC Huffman table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_HUFFMAN_AC_LUMINANCE

Associates an AC Huffman table to the Y band (luminance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_HUFFMAN_DC

Associates a DC Huffman table to the buffer. This control type is only supported with JPEG buffers (both lossy and lossless). INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table. If the buffer is 3-band, the same table is applied to all bands.

(summarize)
Collapse M_HUFFMAN_DC_CHROMINANCE

Associates a DC Huffman table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_HUFFMAN_DC_LUMINANCE

Associates a DC Huffman table to the Y band (luminance) of the buffer. This control type is only supported with JPEG lossy buffers in YUV format. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_PREDICTOR

Sets the type of predictor. This control type is only supported with JPEG lossless buffers. If the buffer is 3-band, the same predictor is applied to all bands. INQ

(summarize)
Collapse 0

Specifies predictor #0 (no prediction).
Collapse 1

Specifies predictor #1 (the "pixel-to-the-left" predictor).

This is the default value.

(summarize)
Collapse 2

Specifies predictor #2 (the "pixel-above" predictor).
Collapse M_Q_FACTOR +

Sets the quantization factor. This control type is only supported with lossy buffers.

For JPEG lossy buffers, the Q factor is always applied to all bands.

For JPEG2000 lossy buffers, the Q factor is applied to all bands by default. To change this default behavior, see the combination values below. INQ

(summarize)
Collapse 1 <= Value <= 99

Specifies the quantization factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The default value is 50.

(summarize)
Collapse M_Q_FACTOR_CHROMINANCE

Sets the chrominance quantization factor. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. INQ

(summarize)
Collapse 1 <= Value <= 99

Specifies the factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The factor is applied to the U and V bands (chrominance).

The default value is 50.

(summarize)
Collapse M_Q_FACTOR_LUMINANCE

Sets the luminance quantization factor. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format. INQ

(summarize)
Collapse 1 <= Value <= 99

Specifies the factor. Only integer values are accepted. The higher the factor, the more the compression, but the lower the image quality.

The factor is applied only to the Y band (luminance).

The default value is 50.

(summarize)
Collapse M_QUANTIZATION +

Associates a quantization table to the buffer. This control type is only supported with lossy buffers.

For JPEG lossy buffers, this table is associated with all bands.

For JPEG2000 lossy buffers, this table is associated with all bands by default.

Note that setting this control type will reset the M_Q_... control types to their default value (50). If you set the M_Q_FACTOR control type after specifying a custom table with the M_QUANTIZATION control type, the custom table will be scaled accordingly. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_QUANTIZATION_CHROMINANCE

Associates a quantization table to the U and V bands (chrominance) of the buffer. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format.

Note that setting this control type will reset the M_Q_FACTOR_CHROMINANCE control type to its default value (50). If you set a M_Q_... control type after specifying a custom table with the M_QUANTIZATION_CHROMINANCE control type, the custom table will be scaled accordingly. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_QUANTIZATION_LUMINANCE

Associates a quantization table to the Y band (luminance) of the buffer. This control type is only supported with JPEG or JPEG2000 lossy buffers in YUV format.

Note that setting this control type will reset the M_Q_FACTOR_LUMINANCE control type to its default value (50). If you set a M_Q_... control type after specifying a custom table with the M_QUANTIZATION_LUMINANCE control type, the custom table will be scaled accordingly. INQ

(summarize)
Collapse MIL M_ARRAY buffer identifier

Specifies the identifier of the array buffer containing the table.
Collapse M_RESTART_INTERVAL

Sets the number of rows or 8x8 blocks between restart markers in a compressed image. INQ

(summarize)
Collapse Value >= 0

Specifies after how many rows (for JPEG lossless buffers) or 8x8 blocks (for JPEG lossy buffers) of data to place restart markers. Only integer values are accepted. The default value is 8 for JPEG lossy buffers and 2 for JPEG lossless buffers.

(summarize)
Collapse M_TARGET_SIZE

Sets the size of the buffer into which the source image is compressed. This control type is only supported with JPEG2000 lossy buffers.

To ensure that the compressed data fits into the specified buffer size, less-significant data is discarded. INQ

(summarize)
Collapse Value > 0

Specifies the size, in bytes. Only integer values are accepted.

(summarize)

You can add one of the following values to the above-mentioned values to specify the color bands to affect.

When dealing with M_Q_FACTOR and M_QUANTIZATION, the following values are only supported with JPEG2000 lossy buffers.

function map For specifying the color bands to affect
CollapseCombination value Description
Collapse M_ALL_BANDS
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to all bands of the buffer.

This is the default value.

(summarize)
Collapse M_BLUE
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the blue band only (for RGB buffers).
Collapse M_GREEN
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the green band only (for RGB buffers).
Collapse M_RED
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the red band only (for RGB buffers).
Collapse M_U
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the U band only (for YUV buffers).
Collapse M_V
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the V band only (for YUV buffers).
Collapse M_Y
[For essential MIL-Lite information, see remarks ]

Applies the specified control value to the Y band only (for YUV buffers).
Remark
  • [MIL-Lite]
    Note that during development and at runtime, compression support, particularly for an M_IMAGE + M_COMPRESS buffer type, requires the presence of a MIL license that grants access to the compression/decompression package. This access is only granted by default with the development license dongle for the full version of MIL. In other cases, you must purchase access to this package separately.
Type-specific versions of the function
void MbufControlDouble (MIL_ID BufId, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)
Details
Parameters

BufId

See BufId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.
void MbufControlInt64 (MIL_ID BufId, MIL_INT64 ControlType, MIL_INT64 ControlValue)
Details
Parameters

BufId

See BufId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
ASSOCIATED LUT DEFAULT DC ALLOC DEFAULT DC FREE DEFAULT LOCK DEFAULT MAP DISABLE ENABLE MAX MIN MODIFICATION HOOK DISABLE ENABLE MODIFIED DEFAULT RESOLUTION X DEFAULT RESOLUTION Y DEFAULT UNLOCK DEFAULT XPIXMAP ALLOC DEFAULT XPIXMAP FREE DEFAULT YCBCR RANGE DEFAULT DISABLE YCBCR HD YCBCR SD GPU ACCESS HOST ACCESS READ READM WRITE WRITE DECOMPOSITION LEVEL HUFFMAN AC ARRAY buffer identifier HUFFMAN AC CHROMINANCE ARRAY buffer identifier HUFFMAN AC LUMINANCE ARRAY buffer identifier HUFFMAN DC ARRAY buffer identifier HUFFMAN DC CHROMINANCE ARRAY buffer identifier HUFFMAN DC LUMINANCE ARRAY buffer identifier PREDICTOR Q FACTOR Q FACTOR CHROMINANCE Q FACTOR LUMINANCE QUANTIZATION ARRAY buffer identifier QUANTIZATION CHROMINANCE ARRAY buffer identifier QUANTIZATION LUMINANCE ARRAY buffer identifier RESTART INTERVAL TARGET SIZE ALL BANDS BLUE GREEN RED U V Y COMPRESS