MbufExportSequence

See also

User Guide:

General steps Grabbing a sequence of frames in real-time MIL Sequences module overview Managing data buffers

Reference:

MbufAllocColor MbufInquire

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/GPm

Available on Matrox Supersight

Function map

Examples

mdiggrabsequence.cpp
mdiggrabsequence.cs
mdiggrabsequence.vb

Function Map

- FileName

Table:

For the name and path of the AVI file

- FileFormat

Table:

For specifying the file format

- BufArrayPtrOrSystemIdPtr

- NumOfIds

- FrameRate

Table:

For specifying the frame rate

- ControlFlag

Parameter Associations

Table:

For specifying how to export the sequence

Remarks

Compilation information

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

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:

For the name and path of the AVI file
Value	Description
MIL_TEXT("FileName") ¹	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) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"). (more details...)

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

For specifying the file format
Value	Description
M_DEFAULT	Specifies that MIL automatically decides the appropriate format.
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) Specifies an AVI format used to hold non-compressed DIB image buffers. (more details...)
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) Specifies an AVI format used to hold image buffers in their MIL format. (more details...)
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 7/8 includes a sufficient version of DirectShow. (summarize) [For essential MIL-Lite information, see remarks ] Specifies an AVI format used to hold JPEG compressed sequences. (more details...)

BufArrayPtrOrSystemIdPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_ID [optionally, in C++: a reference to a constant std::vector<MIL_ID> ]

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

When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the BufArrayPtrOrSystemIdPtr parameter.

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.

For specifying the frame rate
Value	Description
M_DEFAULT	Same as M_NULL.
M_NULL	Specifies to not set or change the frame rate.
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.

For specifying how to export the sequence

For specifying how to export the sequence
ControlFlag			Description
	BufArrayPtrOrSystemIdPtr
	NumOfIds
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) Opens the AVI file, overwriting it in the process. (more details...)
	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) Specifies the address of an array containing the identifiers of the image buffers to export. (more details...)
	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) Specifies the number of image buffers to export. (more details...)
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) Appends the image buffers to the file without overwriting it. (more details...)
	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) Specifies the address of an array containing the identifiers of the image buffers to export. (more details...)
	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) Specifies the number of image buffers to export. (more details...)
M_CLOSE			Closes the AVI file. (summarize) Closes the AVI file. (more details...)
	BufArrayPtrOrSystemIdPtr		Specifies the computer on which the file is located. (summarize) Specifies the computer on which the file is located. (more details...)
		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) Specifies that the file to be closed is on a local computer. (more details...)
		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) Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. (more details...)
	NumOfIds		Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (summarize) Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (more details...)
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) Opens the AVI file, overwriting it in the process. (more details...)
	BufArrayPtrOrSystemIdPtr		Specifies the computer on which the file is located. (summarize) Specifies the computer on which the file is located. (more details...)
		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) Specifies that the file to be opened is on a local computer. (more details...)
		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) Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. (more details...)
	NumOfIds		Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (summarize) Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (more details...)
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) Opens the AVI file, and sets the pointer to the end of the file without overwriting the existing images. (more details...)
	BufArrayPtrOrSystemIdPtr		Specifies the computer on which the file is located. (summarize) Specifies the computer on which the file is located. (more details...)
		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) Specifies that the file to be opened is on a local computer. (more details...)
		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) Specifies the address of a variable containing the identifier of a remote system that is on the same remote computer as the AVI file. (more details...)
	NumOfIds		Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (summarize) Specifies the number of system identifiers passed to the BufArrayPtrOrSystemIdPtr parameter (either a single one, or none). (more details...)
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) Writes the specified number of images in the file starting from the current file pointer position. (more details...)
	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) Specifies the address of an array containing the identifiers of the image buffers to export. (more details...)
	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) Specifies the number of image buffers to export. (more details...)

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.