Synopsis
Restore MIL file format data from a file into an automatically allocated data buffer.
Format
MIL_ID MbufRestore(FileName, SystemId, BufIdPtr)
| char *FileName; | Source file name |
| MIL_ID SystemId; | System identifier |
| MIL_ID *BufIdPtr; | Storage location for MIL buffer identifier |
Description
This function restores a data buffer that was previously saved to a file in an M_MIL file format, using MbufSave or MbufExport (with its FileFormatBufId parameter set to M_MIL). This function automatically allocates a buffer and loads it with the same contents as the original buffer. The buffer 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 MbufRestore function tries to allocate the 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 for 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 MbufLoad to load the image in a previously allocated buffer.
When restoring an image file that was saved with an associated LUT (color palette), the LUT is also restored and associated with the restored image buffer. You can obtain the identifier of the associated LUT, using MbufInquire.
After restoring a buffer, we recommend that you check that the operation was successful by using MappGetError or by checking that the buffer identifier returned is not M_NULL.
Note, you can perform the same operation as MbufRestore by using MbufImport with its FileFormatBufId parameter set to M_MIL and its Operation parameter set to M_RESTORE.
The FileName parameter specifies the name of the file from which to restore the data buffer.
The SystemId parameter specifies the system on which the MIL buffer will be allocated. This parameter must be given a valid system identifier or 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).
The BufIdPtr parameter specifies the address of the variable in which the buffer identifier is to be written. Since the MbufRestore function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.
Returned value
The returned value is the buffer identifier. If allocation fails, M_NULL is returned.
See also
MbufLoad, MbufSave, MbufExport, MbufImport, MbufInquire, MbufControl