| MIL 10 Reference
| Customize Help
| Save Settings

MbufExportSequence


See also
Availability
Available in MIL-Lite with restrictions (see remarks)
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
MbufExport
MbufFree
Synopsis
Export a sequence of image buffers to an AVI file.
Syntax
void MbufExportSequence(
MIL_CONST_TEXT_PTR FileName, //in
MIL_INT64 FileFormat, //in
const MIL_ID *BufArrayPtrOrSystemIdPtr, //in
MIL_INT NumOfIds, //in
MIL_DOUBLE FrameRate, //in
MIL_INT64 ControlFlag //in
)
Description

This function exports a sequence of image buffers to an audio video interleave (AVI) file.

This function creates a new AVI file, or appends to an existing AVI file. If all your images have been acquired, call this function a single time (M_APPEND or M_DEFAULT) to automatically open (or create) the file, write to it, and then close the file. If your images are being acquired over time, call this function to open (or create) the file (M_OPEN or M_OPEN + M_APPEND), call the function again each time you want to write new images to the file (M_WRITE), and call the function once more to close the file (M_CLOSE).

Regions of interest (ROI) are not supported by this function. Using an image buffer with an ROI will cause an error.

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
FileName

Specifies the name and path of the AVI file.

This parameter can be set to the following value:

function map For the name and path of the AVI file
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 format of the file. This parameter can be set to one of the values below.

function map For specifying the file format
CollapseValue Description
Collapse M_DEFAULT

Specifies that MIL automatically decides the appropriate format.
Collapse M_AVI_DIB

Specifies an AVI format used to hold non-compressed DIB image buffers. If necessary, the image buffers will be converted to a non-compressed DIB format before exporting. This type of sequence is supported by Windows Media Player.

(summarize)
Collapse M_AVI_MIL

Specifies an AVI format used to hold image buffers in their MIL format. Since this function saves images in the format in which they are sent, it can be used with any format. Also, since the images are saved "as is", no additional loss is introduced in the images. To be supported by Windows Media Player, this type of sequence requires a codec. Contact Matrox customer support to acquire this codec.

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

Specifies an AVI format used to hold JPEG compressed sequences. When this format is specified, the image buffers must be in YUV16 packed format. In addition, image buffers must have a width that is a multiple of 16 pixels. For image buffers that have the M_JPEG_LOSSY compression type, the height must be a multiple of 8, and less than or equal to 240 pixels. For image buffers that have the M_JPEG_LOSSY_INTERLACED compression type, the height must be a multiple of 16 pixels, and greater than 240 pixels. If the image buffers are not already in these dimensions and format, MIL will automatically convert them appropriately. To be supported by Microsoft Windows Media Player, this type of sequence requires a codec or DirectShow 8.0 (or better); Microsoft Windows XP/7/8 includes a sufficient version of DirectShow.

(summarize)
BufArrayPtrOrSystemIdPtr

Specifies the image buffers to export or, when opening or closing (M_OPEN, M_OPEN + M_APPEND, or M_CLOSE) a file on a remote computer, a MIL system allocated on the remote computer.

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

NumOfIds INQ

Specifies the number of MIL identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (image buffers or system identifiers).

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

FrameRate

Specifies the frame rate (number of images/sec) of the sequence. The frame rate can be specified with any (or every) call to MbufExportSequence(), but it is only checked for validity when closing the AVI file (using M_CLOSE, M_APPEND, or M_DEFAULT). The last call that specifies a valid frame rate will be used.

function map For specifying the frame rate
CollapseValue Description
Collapse M_DEFAULT

Same as M_NULL.
Collapse M_NULL

Specifies to not set or change the frame rate.
Collapse Value > 0

Specifies the frame rate, in number of frames/sec.
ControlFlag

Specifies whether to write, overwrite, or append the image buffers to the AVI file.

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

Parameter associations

The table below lists possible values for the BufArrayPtrOrSystemIdPtr, NumOfIds, and ControlFlag parameters.

function map For specifying how to export the sequence
CollapseControlFlag Description
BufArrayPtrOrSystemIdPtr
NumOfIds
Collapse M_DEFAULT

Opens the AVI file, overwriting it in the process. The file is opened, written into, and then closed. If no file exists, one is created.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the address of an array containing the identifiers of the image buffers to export.

Note that the image buffers must be allocated on the same system as the AVI file.

The image buffers in this array must not have regions of interest (ROI) associated with them. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse NumOfIds

Specifies the number of image buffers to export. Note that if the supplied array of image buffers is larger than this number, the remaining buffer identifiers are ignored.

(summarize)
Collapse M_APPEND

Appends the image buffers to the file without overwriting it. The file is opened, the specified images are appended, and then the file is closed. If no file exists, one is created.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the address of an array containing the identifiers of the image buffers to export.

Note that the image buffers must be allocated on the same system as the AVI file.

The image buffers in this array must not have regions of interest (ROI) associated with them. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse NumOfIds

Specifies the number of image buffers to export. Note that if the supplied array of image buffers is larger than this number, the remaining buffer identifiers are ignored.

(summarize)
Collapse M_CLOSE

Closes the AVI file.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the computer on which the file is located.

(summarize)
Collapse M_NULL

Specifies that the file to be closed is on a local computer. In this case, the file name must not be prefixed with "remote:///".

(summarize)
Collapse Remote system ID

Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. In this case, the file name must be prefixed with "remote:///".

(summarize)
Collapse NumOfIds

Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none).

(summarize)
Collapse M_OPEN

Opens the AVI file, overwriting it in the process. Opens the AVI file for writing, and sets the pointer to the beginning of the file. If no file exists, one will be created.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the computer on which the file is located.

(summarize)
Collapse M_NULL

Specifies that the file to be opened is on a local computer. In this case, the file name must not be prefixed with "remote:///".

(summarize)
Collapse Remote system ID

Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. In this case, the file name must be prefixed with "remote:///".

(summarize)
Collapse NumOfIds

Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none).

(summarize)
Collapse M_OPEN + M_APPEND

Opens the AVI file, and sets the pointer to the end of the file without overwriting the existing images. New images are appended to the file. If no file exists, one is created.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the computer on which the file is located.

(summarize)
Collapse M_NULL

Specifies that the file to be opened is on a local computer. In this case, the file name must not be prefixed with "remote:///".

(summarize)
Collapse Remote system ID

Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. In this case, the file name must be prefixed with "remote:///".

(summarize)
Collapse NumOfIds

Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none).

(summarize)
Collapse M_WRITE

Writes the specified number of images in the file starting from the current file pointer position. After the write operation, the file pointer is left at the end of the file, ready for the next M_WRITE operation.

(summarize)
Collapse BufArrayPtrOrSystemIdPtr

Specifies the address of an array containing the identifiers of the image buffers to export.

Note that the image buffers must be allocated on the same system as the AVI file.

The image buffers in this array must not have regions of interest (ROI) associated with them. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse NumOfIds

Specifies the number of image buffers to export. Note that if the supplied array of image buffers is larger than this number, the remaining buffer identifiers are ignored.

(summarize)
Remark
  • [MIL-Lite]
    Note that during development and at runtime, compression support, particularly for M_AVI_MJPG format, 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.
DEFAULT AVI DIB AVI MIL AVI MJPG DEFAULT NULL DEFAULT NONE APPEND NONE CLOSE NULL OPEN NULL OPEN M APPEND NULL WRITE NONE