MbufImport

This function imports data from a file into an existing or automatically allocated MIL data buffer. The function assumes that the data in the file is in the specified format.

Note, you can also import data using MbufLoad() or MbufRestore(); however, these functions try to determine the format from the data rather than allowing you to specify the format.

For an M_RESTORE operation, this function will allocate the destination buffer with the same attributes as the original buffer, with the exception of an M_IMAGE buffer. In the case of an M_IMAGE buffer, the MbufImport() function tries to allocate the buffer so that it can be used for acquisition (M_GRAB), display (M_DISP), and processing (M_PROC) operations. If there is insufficient appropriate memory to allocate such a buffer, it allocates one that can be used in all of the above operations except for acquisition (M_GRAB). Note that the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL non-paged (DMA) memory (specified at installation time or using the MILConfig utility). For systems with on-board processors, the total number of M_GRAB buffers and M_PROC buffers is limited by the amount of on-board memory.

If importing an image, all the pixel information in the file is imported and loaded into the buffer. Additionally, if the file was saved in M_MIL file format and includes any region of interest (ROI) information, the ROI information is also imported and loaded into the buffer when the FileFormat parameter is set to M_MIL. To load the M_MIL file without its ROI information, set FileFormat to M_MIL + M_NO_REGION.

If the vectorial information of an M_VECTOR_AND_RASTER ROI was input in M_WORLD units, the ROI will be imported as an M_VECTOR ROI.

When importing an image file that has been saved with an associated LUT (color palette) into a 3-band 8-bit image buffer, the LUT is automatically applied to the data to generate 3-band image data. In this case, a LUT buffer is not created and, therefore, is not associated with the 3-band 8-bit buffer. When importing an image file that has been saved with an associated LUT (color palette) into any other type of image buffer, the LUT is also imported and associated with the resulting image buffer. You can obtain the identifier of the associated LUT, using MbufInquire().

Note that the associated LUT will be automatically selected on the display (MdispLut()) if the image buffer is selected on a display and the default LUT has not been overridden by a former call to MdispLut().

Using MbufDiskInquire(), you can inquire about the dimensions of the data saved in a file (except for raw files) without importing it.

After restoring a buffer, we recommend that you check if the operation was successful, using MappGetError(), or by verifying that the returned buffer identifier is not M_NULL.