MbufImportSequence

MIL_CONST_TEXT_PTR FileName,	//in
MIL_INT64 FileFormat,	//in
MIL_INT64 Operation,	//in
MIL_ID SystemId,	//in
MIL_ID *BufArrayPtr,	//in-out
MIL_INT StartImage,	//in
MIL_INT NumberOfImages,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function imports a sequence of images from an AVI file into separate image buffers. MbufImportSequence() can automatically allocate the necessary buffers or you can use previously allocated buffers. In the latter case, the BufArrayPtr parameter should point to an array containing the buffer identifiers. In the former case, MbufImportSequence() will write the identifiers of the new buffers into the array pointed to by BufArrayPtr.

Rather than importing all the required images at once, you can also use this function to only open the AVI file for reading. Then, call this function as many times as required to import different sets of images from the file. Once you have finished importing images from the file, you must call this function again to close the file.

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 function handles the opening and/or closing of the file depending on the ControlFlag parameter setting.

This parameter can be set to the following value:

For specifying 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

Specifies the format of the file. This parameter can be set to one of the values listed below.

For specifying the file format
Value	Description
M_DEFAULT	Specifies that MIL automatically determines the file format.
M_AVI_DIB	Specifies an AVI format containing non-compressed images.
M_AVI_MIL	Specifies an AVI format containing images in their MIL format.
M_AVI_MJPG	[For essential MIL-Lite information, see remarks ] Specifies an AVI format containing compressed images.

Operation

Specifies whether to import the specified sequence of images into automatically allocated buffers or previously allocated buffers. If not importing images, this parameter should be set to M_NULL.

When importing images, this parameter can be set to one of the following:

For importing images
Value	Description
M_LOAD	Imports the sequence into previously allocated buffers.
M_RESTORE	Imports the sequence into automatically allocated buffers.

SystemId

Specifies the system on which to allocate the buffers for an M_RESTORE operation. In other cases, this parameter should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

For specifying the system
Value	Description
M_DEFAULT_HOST	Specifies the default Host system of the current MIL application.
MIL system identifier	Specifies a valid system identifier, previously allocated using MsysAlloc().

BufArrayPtr

Accepts the address of one of the following:

array of type MIL_ID [optionally, in C++: a reference to a std::vector<MIL_ID> ] (and a maximum array rank for C# of 1)
Required array size:(NumberOfImages)

Specifies the address of the array containing the buffer identifiers for an M_LOAD operation, or the address of the array in which to store the new buffer identifiers for an M_RESTORE operation. If not importing images, this parameter should be set to M_NULL.

If specifying an image buffer, it must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

For an M_LOAD operation, the destination buffers should be large enough to hold the imported images.

For an M_RESTORE operation, the destination buffers will be allocated with an appropriate size and type to hold the images. If an M_RESTORE operation fails, zero will be written for the buffer identifiers.

[MIL-Lite with restriction]

When importing compressed images with the M_LOAD operation, if the destination buffers have only an M_IMAGE attribute, the images will automatically be decompressed. When importing uncompressed images with the M_LOAD operation, if the destination buffers have an M_IMAGE + M_COMPRESS attribute, the images will automatically be compressed.

When importing compressed images with the M_RESTORE operation, the M_COMPRESS attribute will automatically be added to the destination buffer (M_IMAGE + M_COMPRESS) and the images will remain compressed in the destination buffer.

StartImage

Specifies the frame number of the image from which to begin importing. If not importing images, this parameter should be set to M_NULL.

If importing images, this parameter can be set to one of the following values:

For specifying the frame number of the image from which to begin importing
Value	Description
M_DEFAULT	Specifies to import the image at the current read position.
Value >= 0	Specifies the frame number of the image from which to begin importing. Note that the frame number of the first image in the sequence is zero. (summarize) Specifies the frame number of the image from which to begin importing. (more details...)

NumberOfImages

Specifies the number of images, starting at StartImage, to import. If not importing images, this parameter should be set to M_NULL.

When importing images, this number cannot be larger than the size of the array pointed to by BufArrayPtr. Note that you can inquire about the number of frames (images) in the AVI file using MbufDiskInquire().

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

ControlFlag

Specifies the function's control flag. This parameter can be set to one of the following:

For specifying the function's control flag
Value	Description
M_DEFAULT	Opens the AVI file, imports the specified images, and then closes the file.
M_CLOSE	Closes the AVI file, and (re)sets the pointer position to the first image. No images are imported. (summarize) Closes the AVI file, and (re)sets the pointer position to the first image. (more details...)
M_OPEN	Opens the AVI file for reading, and sets the pointer to the first image. No images are imported. (summarize) Opens the AVI file for reading, and sets the pointer to the first image. (more details...)
M_READ	Imports the specified images from the AVI file, starting at the specified StartImage position. After the importing the images, the file pointer is left at the position of the next image, ready for the next M_READ operation. (summarize) Imports the specified images from the AVI file, starting at the specified StartImage position. (more details...)

Remarks

When a "remote" path is specified (the FileName parameter begins with "remote:///"), the SystemId parameter must point to the remote system when the AVI file is being opened or closed (M_OPEN or M_CLOSE). The buffers that are receiving the images are allocated on this same remote system.

[MIL-Lite]

Note that during development and at runtime, compression support, particularly for M_AVI_MJPG format and 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.