| MIL 10 Reference
| Customize Help
| Save Settings

MbufExport


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

Available on Windows
Available on Linux

Partially supported on:
Partially supported on Matrox Iris GT

Fully supported on:
Fully supported on Host system
Fully supported on Matrox CronosPlus
Fully supported on Matrox GPU processing driver
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 Orion HD
Fully supported on Matrox Radient eCL
Fully supported on Matrox Radient eV-CXP
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
MbufDiskInquire
MbufExportSequence
Synopsis
Export a data buffer to a file.
Syntax
void MbufExport(
MIL_CONST_TEXT_PTR FileName, //in
MIL_INT64 FileFormat, //in
MIL_ID SrcBufId //in
)
Description

This function exports a data buffer to a file, in the specified output file format.

If exporting an image, all the pixel information in the buffer is exported to the file. Additionally, if the image buffer includes any region of interest (ROI) information, set using MbufSetRegion(), the ROI information is also exported to the file when you export the image in M_MIL file format. If you specify a different file format (for example, M_TIFF), the ROI information cannot be exported to the file. To avoid exporting ROI information to the file when exporting the image in M_MIL file format, set FileFormat to M_MIL + M_NO_REGION.

Note that you can also save a buffer in an M_MIL file format, using MbufSave(). The M_MIL file format is TIFF compatible.

To export an image with a LUT (color palette), associate the LUT to the image, using MbufControl(). Upon export, the image is saved with its associated color palette (MIM, TIFF, and BMP file formats).

[MIL-Lite with restriction]

When exporting uncompressed data to a file in an M_JPEG_... or M_JPEG2000_... file format, this function will automatically compress the data, according to the specified file format. The buffer does not need an M_COMPRESS attribute. If you are exporting compressed data to a file in an uncompressed file format, this function will automatically decompress the data.

To save the calibration information associated with the buffer (if applicable), use M_WITH_CALIBRATION.

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
FileName

Specifies the name and path of the file in which to save the data buffer. It is recommended that you use the MIM file extension for easier use with other Matrox Imaging software products. The function handles (internally) the opening and closing of the file. If the file already exists, it will be overwritten.

This parameter can be set to the following value:

function map For specifying the file name and path
CollapseValue Description
Collapse MIL_TEXT("FileName") 1

Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile").

To specify a file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\mydirectory\myfile").

(summarize)

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

FileFormat INQ

Specifies the file format. This parameter can be set to one of the following values. Note that, except for the M_MIL and M_RAW file formats, the source buffer should have an M_IMAGE attribute; otherwise, the data is saved as if it were image data.

function map For specifying the file format
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_BMP

Specifies that the buffer is saved in a BMP file format. The standard Windows BMP format is used.

This file format supports images that are grayscale or RGB. Images in a different format are internally converted before being saved.

This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG2000_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG2000 lossless file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG2000_LOSSLESS_JP2
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG2000 lossless file format using the standard JP2 format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG2000_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG2000 lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG2000_LOSSY_JP2
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JP2000 lossy file format using the standard JP2 file format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG lossless file format. If the buffer is 3-band, the data will be stored in RGB format.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG_LOSSLESS_INTERLACED
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in an interlaced JPEG lossless file format. This file format is only applicable to 1-band image buffers.

This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG_LOSSY attribute, the data will be stored in YUV16 packed format; otherwise, it will be stored in the same color format as the buffer.

This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG_LOSSY_INTERLACED
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in an interlaced JPEG lossy file format. If the buffer is 3-band, the data will be stored in YUV16 packed format.

This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_JPEG_LOSSY_RGB
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer is saved in a JPEG lossy file format. If the buffer is 3-band, the data will be stored in RGB format.

This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band.

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

Specifies that the buffer is saved in a MIL file format. It uses a baseline TIFF 6.0 file format with extra information included in the comment field. The buffer attributes and data type are also saved in the file.

This file format supports images that are binary, grayscale, and RGB, as well as palette-color images.

The MIL file format is a single-page, uncompressed TIFF file format.

By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format).

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

Specifies that the buffer is saved in a PNG file format.

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

Specifies that the buffer is saved as raw data. The contents are dumped directly (byte stream) into the file and no header is added. If the buffer is multi-band, the buffer is saved in planar format (one band after another).

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

Specifies that the buffer is saved in a TIFF file format. The TIFF file format that is used respects the baseline TIFF 6.0 specification.

The TIFF file format that is used supports images that are binary, grayscale, and RGB, as well as palette-color images. Also, this TIFF format supports any data type and depth that MIL supports for buffers.

An image buffer cannot be saved using a multi-page TIFF file format; it is always saved as a single-page TIFF file. In addition, MIL only supports uncompressed TIFF files.

By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format).

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

You can add one of the following values to the above-mentioned value to set whether to save the calibration information or region of interest data associated with the buffer.

function map For saving calibration information or ROI data
CollapseCombination value Description
Collapse M_NO_REGION

Specifies that any ROI data associated with the buffer is not saved with the buffer contents.
Collapse M_WITH_CALIBRATION

Specifies that any calibration information associated with the buffer is saved. To restore the associated calibration, use McalRestore().

(summarize)
Combination constant for M_MIL; M_TIFF.

You can add the following value to the above-mentioned values to set whether to save the color image buffer in a planar format.

function map For saving a color image in a planar format
CollapseCombination value Description
Collapse M_PLANAR

Specifies that the color image buffer is saved in a planar format.
Combination constant for M_TIFF.

You can add the following value to the above-mentioned value to set whether to save the image buffer in big endian format.

function map For saving an image in big endian format
CollapseCombination value Description
Collapse M_BIG_ENDIAN

Specifies that the image buffer is saved in big endian format.
Combination constants for M_TIFF.

You can add one of the following values to the above-mentioned value to set whether to use compression when saving a TIFF image file.

function map For compressing a TIFF image file
CollapseCombination value Description
Collapse M_COMPRESSION_CCITTFAX3

Specifies to use CCITT FAX3 compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Collapse M_COMPRESSION_CCITTFAX4

Specifies to use CCITT FAX4 compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Collapse M_COMPRESSION_CCITTRLE

Specifies to use CCITT RLE compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Collapse M_COMPRESSION_CCITTRLEW

Specifies to use CCITT RLEW compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Collapse M_COMPRESSION_LZW

Specifies to use LZW compression.
Collapse M_COMPRESSION_NONE

Specifies to use no compression.
Collapse M_COMPRESSION_PACKBITS

Specifies to use PackBits compression.
SrcBufId

Specifies the identifier of the data buffer to save. This image buffer can have an ROI set using MbufSetRegion().

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.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
BMP JPEG2000 LOSSLESS JPEG2000 LOSSLESS JP2 JPEG2000 LOSSY JPEG2000 LOSSY JP2 JPEG LOSSLESS JPEG LOSSLESS INTERLACED JPEG LOSSY JPEG LOSSY INTERLACED JPEG LOSSY RGB MIL PNG RAW TIFF NO REGION WITH CALIBRATION PLANAR BIG ENDIAN COMPRESSION CCITTFAX3 COMPRESSION CCITTFAX4 COMPRESSION CCITTRLE COMPRESSION CCITTRLEW COMPRESSION LZW COMPRESSION NONE COMPRESSION PACKBITS