M3dmapStream

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 *ContextOrGeometry3dmapIdPtr,	//in-out
MIL_INT *SizeByteVarPtr	//out

)

Description

This function can load or restore a 3D reconstruction context or geometry object from a file or memory stream. This function restores all of the object's settings that were in effect when the object was saved. A restored 3D reconstruction context or geometry object is ready to use, with no need to perform any calibration step.

This function can also save a 3D reconstruction context or geometry object to a file or memory stream. For a 3D reconstruction context, all calibration information is saved, so the context will be ready to use on reload.

To inquire the number of bytes necessary to save a 3D reconstruction context or geometry object, you should call M3dmapStream() 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 M3dmapSave() is equivalent to a file saved using M3dmapStream().

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.

When StreamType is set to M_FILE, you can set MemPtrOrFileName to M_INTERACTIVE to open a dialog box and choose interactively where to save/load the object. Otherwise, specify the drive, directory, and name of the file. Use the M3D file extension when saving a 3D reconstruction context or geometry object to a file for easier use with other Matrox Imaging software products, whether specifying a file name or using M_INTERACTIVE.

For specifying the name and path of a file, memory stream or opening an interactive dialog box
Value	Description
M_NULL	Specifies to ignore this parameter. The parameter must be set to M_NULL when performing an M_INQUIRE_SIZE_BYTE operation. (summarize) Specifies to ignore this parameter. (more details...)
M_INTERACTIVE	[This is only applicable to Windows] Opens a dialog box from which you can interactively specify the drive, directory, and name of the file, when the StreamType parameter is set to M_FILE.
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"). 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) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"). (more details...)
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 (M3dmapStream()) first with 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) Specifies the address of the block of memory, when the StreamType parameter is set to M_MEMORY. (more details...)

¹ 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 3D reconstruction context or geometry object.

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

For a restore operation
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().

For M_INQUIRE_SIZE_BYTE, M_LOAD, and M_SAVE, this parameter must be set to the following value:

For a load or save operation, or when inquiring the required number of bytes for a save operation
Value	Description
M_NULL	Specifies that this parameter is not applicable.

Operation

Specifies the operation to perform on the 3D reconstruction context or geometry object. This parameter must be set to one of the following values:

For specifying the type of operation to perform
Value	Description
M_INQUIRE_SIZE_BYTE	Inquires the number of bytes required to save a 3D reconstruction context or geometry object to memory stream. This operation is not supported when the StreamType parameter is set to M_FILE. (summarize) Inquires the number of bytes required to save a 3D reconstruction context or geometry object to memory stream. (more details...)
M_LOAD	Loads the content of a specified file or memory stream into a previously allocated 3D reconstruction context or geometry object.
M_RESTORE	Restores a 3D reconstruction context or geometry object from a file or memory stream and assigns it an identifier.
M_SAVE	Saves a 3D reconstruction context or geometry object to a specified file or memory stream.

StreamType

Specifies the type of stream in which to store/from which to restore the 3D reconstruction context or geometry object. This parameter must be set to one of the following values:

For specifying the type of stream
Value	Description
M_FILE	Specifies a file stream.
M_MEMORY	Specifies a memory stream. You are responsible for allocating a block of memory for the stream. (summarize) Specifies a memory stream. (more details...)

Version

Specifies the MIL version of the 3D reconstruction context or geometry object.

For specifying the version
Value	Description
M_DEFAULT	Specifies the current version of MIL.
M_PROC_VERSION_90_PP2	Sets the version to MIL 9.0 Processing Pack 2. This option is only available when Operation is set to M_SAVE or M_INQUIRE_SIZE_BYTE. (summarize) Sets the version to MIL 9.0 Processing Pack 2. (more details...)
M_PROC_VERSION_100	Sets the version to MIL 10.0. This option is only available when Operation is set to M_SAVE or M_INQUIRE_SIZE_BYTE. (summarize) Sets the version to MIL 10.0. (more details...)
M_PROC_VERSION_100_PP1	Sets the version to MIL 10.0 Processing Pack 1. This option is only available when Operation is set to M_SAVE or M_INQUIRE_SIZE_BYTE. (summarize) Sets the version to MIL 10.0 Processing Pack 1. (more details...)

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

ContextOrGeometry3dmapIdPtr

Specifies the address of the variable in which to write or from which to read the identifier of the 3D reconstruction context or geometry object.

For M_INQUIRE_SIZE_BYTE and M_SAVE operations, ContextOrGeometry3dmapIdPtr specifies the address of the variable from which to read the 3D reconstruction context or geometry object identifier.

For an M_LOAD operation, the ContextOrGeometry3dmapIdPtr specifies the address of the variable from which to read the identifier of the 3D reconstruction context or geometry object where the file or memory stream content will be loaded.

For an M_RESTORE operation, the ContextOrGeometry3dmapIdPtr specifies the address in which to return the identifier of the restored 3D reconstruction context or geometry object. 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 3D reconstruction context or geometry object, in bytes.

Note that the size of the 3D reconstruction context or geometry object varies depending on the MIL version specified.

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

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3dmap.lib.
DLL	Requires mil.dll; mil3dmap.dll.