MbufStream

See also

Reference:

MbufAllocColor MbufInquireContainer MbufSave MsysAlloc

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux with restrictions

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

None.

Function Map

- StreamType

Table:

For the type of stream

- Version

- ControlFlag

- ContainerOrBufIdPtr

- SizeByteVarPtr

Parameter Associations

Table:	For performing the stream operation.
+ combination:	For specifying that the stream is GenDC-compatible

Compilation information

Synopsis

Load, restore, or save a buffer or container from/to a file or memory stream.

Syntax

void MbufStream(

MIL_TEXT_PTR MemPtrOrFileName,	//in-out
MIL_ID SystemId,	//in
MIL_INT64 Operation,	//in
MIL_INT64 StreamType,	//in
MIL_DOUBLE Version,	//in
MIL_INT64 ControlFlag,	//in
MIL_ID *ContainerOrBufIdPtr,	//in-out
MIL_INT *SizeByteVarPtr	//out

)

Description

This function can load, restore, or save a buffer or container from/to a file or memory stream.

To inquire the number of bytes necessary to save a buffer or container, you should first call this function (MbufStream()) with M_INQUIRE_SIZE_BYTE.

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

Typically the stream is saved in the MIL native file format. Optionally, you can save a container in a GenDC-compatible format by setting the ControlFlag parameter to M_GENDC. You must specify M_GENDC when loading or restoring a stream saved in a GenDC-compatible format.

Optionally, when saving a container, you can specify to losslessly compress the data in the stream by setting the ControlFlag parameter to M_COMPRESS. This is not available when saving a container in a format that is GenDC-compatible.

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 which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

MemPtrOrFileName

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

MIL_TEXT_PTR [optionally, in C++: a reference to a MIL_STRING]
Optionally, in C++: a reference to a std::vector of type MIL_UINT8

Specifies the file or memory stream.

See the Parameter associations section for possible values that can be returned/specified.

SystemId

Specifies the system on which to restore the buffer or container.

See the Parameter associations section for possible values that can be specified.

Operation

Specifies the operation to perform.

See the Parameter associations section for possible values that can be specified.

StreamType

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

For the type of stream
Value	Description
M_FILE	Specifies a file stream. The file is saved in the MIL native file format, unless ControlFlag is set to M_GENDC; in which case, the file is saved in the GenDC file format. The GenDC file format is only available when saving/loading a container. (summarize) Specifies a file stream. (more details...)
M_MEMORY	Specifies a memory stream. You are responsible for allocating a block of memory for the stream. The memory stream is saved in the MIL native file format, unless ControlFlag is set to M_GENDC; in which case, the memory stream is saved in the GenDC file format. The GenDC file format is only available when saving/loading a container. (summarize) Specifies a memory stream. (more details...)

Version

Specifies the MIL version of the buffer or container.

See the Parameter associations section for possible values that can be specified.

ControlFlag

Specifies the control flag for the operation. Set this parameter to M_DEFAULT if not used.

See the Parameter associations section for possible values that can be specified.

ContainerOrBufIdPtr

Specifies the address of the variable in which to write, or from which to read, the buffer or container identifier.

See the Parameter associations section for possible values that can be returned/specified.

SizeByteVarPtr

Specifies the address of the variable in which to write the size of the buffer or container, in bytes.

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

The size of the buffer or container varies depending on the MIL version that you specify.

Parameter associations

The table below lists possible values for the MemPtrOrFileName, SystemId, Operation, Version, ControlFlag, and ContainerOrBufIdPtr parameters.

For performing the stream operation.

For performing the stream operation.
Operation			Description
	MemPtrOrFileName - Possible values passed or returned
	SystemId
	Version
	ControlFlag
	ContainerOrBufIdPtr - Possible values passed or returned
M_INQUIRE_SIZE_BYTE			Inquires the number of bytes required to save a buffer or container to a 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 buffer or container to a memory stream. (more details...)
	MemPtrOrFileName		This parameter must be set to M_NULL. (summarize) This parameter must be set to M_NULL. (more details...)
	SystemId		This parameter must be set to M_NULL. (summarize) This parameter must be set to M_NULL. (more details...)
	Version		Specifies the MIL version with which the buffer or container must be compatible when saved. The size of a buffer or container might differ from one MIL version to another. (summarize) Specifies the MIL version with which the buffer or container must be compatible when saved. (more details...)
		M_DEFAULT	Specifies the current version of MIL.
		M_PROC_VERSION_100_SP4	Specifies the version as being MIL 10.0 Service Pack 4.
	ContainerOrBufIdPtr		Specifies the address of the variable containing the identifier of the buffer or container. (summarize) Specifies the address of the variable containing the identifier of the buffer or container. (more details...)
	ControlFlag		Specifies how the data is stored in the file or memory stream. (summarize) Specifies how the data is stored in the file or memory stream. (more details...)
		M_DEFAULT	Specifies the default behavior.
		M_GENDC	Specifies that the data is saved using a GenDC-compatible format. This setting is only available for a container, not a buffer. (summarize) Specifies that the data is saved using a GenDC-compatible format. (more details...)
M_LOAD			Loads the content of a specified file or memory stream into a previously allocated buffer or container. (summarize) Loads the content of a specified file or memory stream into a previously allocated buffer or container. (more details...)
	MemPtrOrFileName		Specifies the file or memory stream from which to load the buffer or container. (summarize) Specifies the file or memory stream from which to load the buffer or container. (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"), when the StreamType parameter is set to M_FILE. Files that store a buffer or container in the MIL native format typically have the mbuf or mbufc extension respectively. Files that store a format in the GenDC format typically have the gendc extension. The function handles (internally) the opening and closing of the 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"). (summarize) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"), when the StreamType parameter is set to M_FILE. (more details...)
		MemPtr	Specifies the address of the block of memory, when the StreamType parameter is set to M_MEMORY. The block of memory should be of type MIL_UINT8. The specified address must correspond to the first memory address in which the object is located, and the block of memory must contain the entire object. Note that when using a C compiler (not a C++ or other compiler), 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...)
	SystemId		This parameter must be set to M_NULL. (summarize) This parameter must be set to M_NULL. (more details...)
	Version		This parameter must be set to M_DEFAULT. (summarize) This parameter must be set to M_DEFAULT. (more details...)
	ContainerOrBufIdPtr		Specifies the address of the variable containing the identifier of the buffer or container. All previous settings are overwritten with those of the loaded buffer or container, or are set to the default value if the settings didn't exist in the version of MIL from which the buffer or container is being loaded. (summarize) Specifies the address of the variable containing the identifier of the buffer or container. (more details...)
	ControlFlag		Specifies how to load the data from the file or memory stream into the buffer or container. (summarize) Specifies how to load the data from the file or memory stream into the buffer or container. (more details...)
		M_DEFAULT	Specifies the default behavior. When loading a container, this is equivalent to M_BASIC_ATTRIBUTE. (summarize) Specifies the default behavior. (more details...)
		M_BASIC_ATTRIBUTE +	Specifies to load the contents of the file or memory stream (that stores data suitable for loading into a container) to automatically allocated components that might have different attributes than the original stored components. This setting is only available for a container, not a buffer. (summarize) Specifies to load the contents of the file or memory stream (that stores data suitable for loading into a container) to automatically allocated components that might have different attributes than the original stored components. (more details...)
		M_IDENTICAL +	Specifies to load the contents of the file or memory stream, including all data, settings, and attributes. An error will be generated if there is a mismatch between the size, number of bands, or attributes (such as M_RGB24) of the destination buffer and the contents of the file. (summarize) Specifies to load the contents of the file or memory stream, including all data, settings, and attributes. (more details...)
		M_USE_DESTINATION +	Specifies to load the contents of the file or memory stream (that stores data suitable for loading into a container) into the existing components of the destination container. An error will be generated if the file or memory stream has a different number of components than the destination container. This setting is only available for a container, not a buffer. (summarize) Specifies to load the contents of the file or memory stream (that stores data suitable for loading into a container) into the existing components of the destination container. (more details...)
M_RESTORE			Restores a buffer or container from a file or memory stream and assigns it a MIL identifier. (summarize) Restores a buffer or container from a file or memory stream and assigns it a MIL identifier. (more details...)
	MemPtrOrFileName		Specifies the file or memory stream from which to load the buffer or container. (summarize) Specifies the file or memory stream from which to load the buffer or container. (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"), when the StreamType parameter is set to M_FILE. Files that store a buffer or container in the MIL native format typically have the mbuf or mbufc extension respectively. Files that store a format in the GenDC format typically have the gendc extension. The function handles (internally) the opening and closing of the 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"). (summarize) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"), when the StreamType parameter is set to M_FILE. (more details...)
		MemPtr	Specifies the address of the block of memory, when the StreamType parameter is set to M_MEMORY. The block of memory should be of type MIL_UINT8. The specified address must correspond to the first memory address in which the object is located, and the block of memory must contain the entire object. Note that when using a C compiler (not a C++ or other compiler), 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...)
	SystemId		Specifies the system on which to allocate the buffer or container. (summarize) Specifies the system on which to allocate the buffer or container. (more details...)
		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().
	Version		This parameter must be set to M_DEFAULT. (summarize) This parameter must be set to M_DEFAULT. (more details...)
	ContainerOrBufIdPtr		Specifies the address of the variable in which to write the identifier of the buffer or container. If the operation is not successful, M_NULL is written as the identifier. (summarize) Specifies the address of the variable in which to write the identifier of the buffer or container. (more details...)
	ControlFlag		Specifies how the data is stored in the file or memory stream. (summarize) Specifies how the data is stored in the file or memory stream. (more details...)
		M_DEFAULT	Specifies the default behavior.
		M_GENDC	Specifies that the data is saved using a GenDC-compatible format. This setting is only available for a container, not a buffer. (summarize) Specifies that the data is saved using a GenDC-compatible format. (more details...)
M_SAVE			Saves a buffer or container to a specified file or memory stream. (summarize) Saves a buffer or container to a specified file or memory stream. (more details...)
	MemPtrOrFileName		Specifies the file or memory stream from which to load the buffer or container. (summarize) Specifies the file or memory stream from which to load the buffer or container. (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"), when the StreamType parameter is set to M_FILE. File streams that store a buffer or container in the MIL native format typically have the mbuf or mbufc extension respectively. File streams that store a format in the GenDC format typically have the gendc extension. The function handles (internally) the opening and closing of the 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"). (summarize) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"), when the StreamType parameter is set to M_FILE. (more details...)
		MemPtr	Specifies the address of the block of memory, when the StreamType parameter is set to M_MEMORY. The block of memory should be of type MIL_UINT8. The specified address must correspond to the first memory address in which to write, and the block of memory must be large enough to stream the entire object. To determine the required size, call this function with M_INQUIRE_SIZE_BYTE. Note that when using a C compiler (not a C++ or other compiler), 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...)
	SystemId		This parameter must be set to M_NULL. (summarize) This parameter must be set to M_NULL. (more details...)
	Version		Specifies the MIL version with which the buffer or container must be compatible when saved. (summarize) Specifies the MIL version with which the buffer or container must be compatible when saved. (more details...)
		M_DEFAULT	Specifies the current version of MIL.
		M_PROC_VERSION_100_SP4	Specifies the version as being MIL 10.0 Service Pack 4.
	ContainerOrBufIdPtr		Specifies the address of the variable containing the identifier of the buffer or container. (summarize) Specifies the address of the variable containing the identifier of the buffer or container. (more details...)
	ControlFlag		Specifies how to save the data in the fiel or memory stream. (summarize) Specifies how to save the data in the fiel or memory stream. (more details...)
		M_DEFAULT	Specifies the default behavior.
		M_COMPRESS	Specifies to losslessly compress the data in the stream. This setting is only available for a container, not a buffer. (summarize) Specifies to losslessly compress the data in the stream. (more details...)
		M_GENDC	Specifies to save the data using a GenDC-compatible format. When saving using a GenDC-compatible format, some attributes and settings of the container and its components might be removed. This setting is only available for a container, not a buffer. An error is generated if the source container has one of the following: A component that is not an M_IMAGE or M_ARRAY buffer. A component with M_COMPONENT_TYPE set to M_COMPONENT_MESH_MIL or M_COMPONENT_NORMALS_MIL. A component with M_COMPONENT_GROUP_ID, M_COMPONENT_REGION_ID, or M_COMPONENT_SOURCE_ID set to a value larger than 65535. A component that is an image buffer compressed in a format other than JPEG or JPEG 2000. (summarize) Specifies to save the data using a GenDC-compatible format. (more details...)

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

Combination value for M_BASIC_ATTRIBUTE (when Operation=M_LOAD and ControlFlag=M_BASIC_ATTRIBUTE); M_IDENTICAL (when Operation=M_LOAD and ControlFlag=M_IDENTICAL); M_USE_DESTINATION (when Operation=M_LOAD and ControlFlag=M_USE_DESTINATION).

You can add the following value to the above-mentioned values to specify that the stream to load is in a GenDC-compatible format..

For specifying that the stream is GenDC-compatible
Combination value	Description
M_GENDC	Specifies that the stream is in a GenDC-compatible format. This setting is only available for a container, not a buffer. (summarize) Specifies that the stream is in a GenDC-compatible format. (more details...)

Compilation information

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