MbufImport()函数

Synopsis

Import data from a file into a data buffer.

Format

MIL_ID MbufImport(FileName, FileFormatBufId, Operation, SystemId, BufIdPtr)

Description

This function imports data, of the specified format, from a file into a MIL data buffer on the specified system.

Note, you can also import data that has been saved in an M_MIL file format, using MbufLoad or MbufRestore.

The FileName parameter specifies the name of the file from which to get the data.

The FileFormatBufId parameter specifies the identifier of the information buffer containing the file conversion format. Predefined file format identifiers are available for the most commonly used file formats:

The Operation parameter specifies the import operation. This parameter can be set to one of the following:

When a buffer is automatically allocated during a restore operation, it is allocated with the same attribute as the original buffer, with the exception of M_IMAGE buffers. In the case of an M_IMAGE type buffer, the MbufImport function tries to allocate an image buffer so that it can be used for display (M_DISP), processing (M_PROC), and acquisition (M_GRAB) operations. If there is insufficient appropriate memory to allocate such a buffer, it tries to allocate one that can be used in all of the above operations except display (M_DISP). If it is still unsuccessful, it tries to remove the M_PROC attribute, then the M_GRAB attribute, leaving the buffer with the M_IMAGE attribute only. If it still cannot allocate the image buffer, it generates an error. If this happens, you can use MbufImport with M_LOAD to load the image into a previously allocated buffer.

When importing an image file that was saved with an associated LUT (color palette), the LUT is also imported and associated with the resulting image buffer. You can obtain the identifier of the associated LUT, using MbufInquire.

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

Note, you cannot restore (M_RESTORE) a RAW data file (M_RAW) because its dimensions are unknown.

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

The SystemId parameter specifies the system where the MIL buffer will be allocated. This parameter must be given a valid system identifier or it can be set to M_DEFAULT_HOST. In the latter case, the default Host system of the current MIL application is used. You can also specify M_DEFAULT, in which case MIL selects the most appropriate system on which to allocate the buffer (either the Host system or any currently allocated system).

Set SystemId to M_NULL if M_LOAD is specified as the operation.

The BufIdPtr parameter specifies the address of the variable that either gives or receives a data buffer identifier, depending on the setting of the Operation parameter. When Operation is set to M_RESTORE, MbufImport returns the buffer identifier and stores it at the specified variable address. Since MbufImport also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

When a buffer identifier is given, the buffer must be large enough in depth and dimensions to hold the data; if not, some data is clipped. For example, if the data is deeper than the buffer, the most-significant bits of the data are not written. If, however, the buffer is larger in depth or dimensions than the data, excess areas are unaffected.

Returned value

The returned value is the buffer identifier (for an M_RESTORE operation only). If allocation fails, M_NULL is returned.

Status

This function supports the baseline TIFF 6.0 format for grayscale and RGB images.

See also

MbufDiskInquire, MbufExport, MbufSave, MbufLoad, MbufRestore, MbufControl