| MIL 10 Reference
| Customize Help
| Save Settings

MbeadStream


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
None.
MbeadSave
MbeadTemplate
Synopsis
Load, restore, or save a MIL bead context from/to a file or memory stream.
Syntax
void MbeadStream(
MIL_TEXT_PTR MemPtrOrFileName, //in-out
MIL_ID SysId, //in
MIL_INT64 Operation, //in
MIL_INT64 StreamType, //in
MIL_DOUBLE Version, //in
MIL_INT64 ControlFlag, //in
MIL_ID *ContextBeadIdPtr, //in-out
MIL_INT *SizeByteVarPtr //out
)
Description

This function can load or restore a bead context from a file or memory stream. All of the bead context's settings that were in effect when the bead context was saved will be restored. The templates contained within a loaded or restored bead context are not preprocessed, therefore you must call MbeadTrain() before performing a verification with MbeadVerify(). If you had associated a training image with a calibration context and you did not save it with the context, you must re-associate the calibration context, using MbeadControl() with M_ASSOCIATED_CALIBRATION.

This function can also save a bead context to a file or memory stream. All information about the previously allocated bead context (and the templates therein) is saved.

To inquire the number of bytes necessary to save a bead context, you should call MbeadStream() first with the Operation parameter set to M_INQUIRE_SIZE_BYTE.

The content saved to a memory stream is equivalent to the content saved to a file. In addition, any file saved with MbeadSave() is equivalent to a file saved using MbeadStream().

You can use this and other MIL stream functions, for example, to save all required MIL objects, as well as any other custom data, for your application to a memory stream. Once in a memory stream, you can write the stream to a single file or transfer it over a network. You are responsible for concatenating the streams and for saving the stream to 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
MemPtrOrFileName

Specifies the file or memory stream. This parameter should be set to one of the following values:

function map For specifying the name and path of a file or memory stream
CollapseValue Description
Collapse M_NULL

Specifies to ignore this parameter (MemPtrOrFileName). This parameter must be set to M_NULL when performing an M_INQUIRE_SIZE_BYTE operation.

(summarize)
Collapse MIL_TEXT("FileName") 1

Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"), when the StreamType parameter is set to M_FILE.

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

For easier use with other Matrox Imaging software products, when saving a bead context to a file, use the BCF file extension. The function internally handles the opening and closing of the file. If the file already exists, it will be overwritten when M_SAVE is performed.

(summarize)
Collapse MemPtr

Specifies the address of the block of memory, when the StreamType parameter is set to M_MEMORY. The designated block must be large enough to stream the entire object. To ascertain the required size, call this function (MbeadStream()) first with the Operation parameter set to M_INQUIRE_SIZE_BYTE.

When you allocate the block of memory, the memory pointer is of type MIL_UINT8. In this case, you must cast the MIL_UINT8 pointer to a MIL_TEXT_PTR.

(summarize)

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

SysId

Specifies the system on which to restore the bead context. For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, SysId is ignored and should be set to M_NULL.

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

function map For M_RESTORE
CollapseValue Description
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().
Operation

Specifies the operation to perform. This parameter should be set to one of the following values:

function map For specifying the operation to perform
CollapseValue Description
Collapse M_INQUIRE_SIZE_BYTE

Inquires the number of bytes required to save a bead context. This operation is not supported when you set the StreamType parameter to M_FILE.

(summarize)
Collapse M_LOAD

Loads the content of a specified file or memory stream into a previously allocated bead context.
Collapse M_RESTORE

Restores a bead context from a file or memory stream and assigns it an identifier.
Collapse M_SAVE

Saves a bead context to a specified file or memory stream.
StreamType

Specifies the type of stream in which to store/from which to restore the bead context. This parameter should be set to one of the following values:

function map For the type of stream
CollapseValue Description
Collapse M_FILE

Specifies a file stream.
Collapse M_MEMORY

Specifies a memory stream. You are responsible for allocating a block of memory for the stream.

(summarize)
Version

Specifies the MIL version of the bead context. This parameter should be set to one of the following values:

function map For specifying the MIL version
CollapseValue Description
Collapse M_DEFAULT

Specifies the default version.

For an M_SAVE or M_INQUIRE_SIZE_BYTE operation, M_DEFAULT sets the version to the current version of MIL.

For an M_LOAD or M_RESTORE operation, M_DEFAULT reads the file or stream for the version information. This is the only possible setting for these operations.

(summarize)
Collapse M_PROC_VERSION_90_PP2

Sets the version to MIL 9.0 Processing Pack 2.

This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.

(summarize)
Collapse M_PROC_VERSION_100

Sets the version to MIL 10.0.

This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.

(summarize)
Collapse M_PROC_VERSION_100_PP1

Sets the version to MIL 10.0 Processing Pack 1.

This option is available only for M_INQUIRE_SIZE_BYTE and M_SAVE operations.

(summarize)
ControlFlag

Specifies whether to restore the calibration context from the bead context, or save the calibration context with the bead context.

function map For specifying whether to restore or save the calibration context
CollapseValue Description
Collapse M_DEFAULT

Specifies that the calibration is not saved or restored.
Collapse M_WITH_CALIBRATION

Specifies that the calibration is saved or restored, depending on the MemPtrOrFileName parameter. When restored, the calibration must have been previously saved with the context, using MbeadSave() or MbeadStream() with M_WITH_CALIBRATION.

The calibration information is restored from/ saved to the same file as the bead context. The calibration cannot be managed independently from the bead context. When the bead context is freed, the calibration is automatically freed as well.

(summarize)
ContextBeadIdPtr

Specifies the address of the variable in which to write or from which to read the identifier of the bead context.

For M_INQUIRE_SIZE_BYTE and M_SAVE operations, ContextBeadIdPtr specifies the address of the variable from which to read the bead context identifier.

For an M_LOAD operation, ContextBeadIdPtr specifies the address of the variable from which to read the identifier of the bead context where the file or memory stream content will be loaded.

For an M_RESTORE operation, ContextBeadIdPtr specifies the address of the variable in which to return the identifier of the restored bead context. If the operation is not successful, M_NULL is returned.

SizeByteVarPtr

Specifies the address of the variable in which to write the size of the bead context, in bytes.

If the size is not required, you can set this parameter to M_NULL.

The size of the bead context varies depending on the MIL version that you specify.

Compilation information
Header Include mil.h.
Library Use mil.lib; milbead.lib.
DLL Requires mil.dll; milbead.dll.
NULL DEFAULT HOST INQUIRE SIZE BYTE LOAD RESTORE SAVE FILE MEMORY DEFAULT PROC VERSION 90 PP2 PROC VERSION 100 PROC VERSION 100 PP1 DEFAULT WITH CALIBRATION LOAD) RESTORE) SAVE) LOAD RESTORE SAVE