MbufCopyComponent

See also

User Guide:

3D containers overview Child containers Components Using components individually Working with non-compliant cameras

Reference:

MbufAllocColor MbufAllocComponent MbufControl MbufControlContainer MbufFreeComponent MbufInquire MbufInquireContainer

Availability

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/GPm

Available on Matrox Supersight

Function map

Examples

3dmodelheightdefect.cpp
studinspection.cpp

Function Map

- SrcContainerOrBufId

- DstContainerBufId

- SrcComponent

Table:	For specifying which component to copy using a uniquely identifying criterion
Table:	For specifying which component(s) to copy using a generalized criterion
Table:	For specifying which component(s) to copy by component type

- Operation

Table:

For specifying the operation to perform

- ControlFlag

Table:	For specifying how the buffer or container is copied
+ combination:	For specifying how the source is used

Compilation information

Synopsis

Copy a data buffer, or components of a container, to components of a destination container.

Syntax

void MbufCopyComponent(

MIL_ID SrcContainerOrBufId,	//in
MIL_ID DstContainerBufId,	//in
MIL_INT64 SrcComponent,	//in
MIL_INT64 Operation,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function copies the specified data buffer, or components of the specified source container, to the specified destination container. If the source is a container, you must specify which components to copy using SrcComponent.

By default, this function allocates one or more buffers and adds them as components of the destination container. The allocated buffers have the same buffer type, size, number of bands, component type, and some settings (such as 3D settings) as the source buffers. All data and other settings are also copied, unless you set the ControlFlag parameter to M_NO_COPY_SOURCE_DATA. Some attributes (such as M_COMPRESS) are not copied by default. You can specify that these attributes are also copied by setting the ControlFlag parameter to M_IDENTICAL.

Optionally, you can specify to replace matching components in the destination container (in some cases, reusing the existing buffers) by specifying the M_REPLACE operation.

When copying components from a container, you can force MIL to use the destination components as-is and not free or reallocate them. To do so, set the ControlFlag parameter to M_USE_DESTINATION. If there is a mismatch between a component in the source and destination container (for example, the destination component is smaller than the source component), MIL will attempt to compensate (for example, by only copying some of the data). If there are not the same number of components that meet the specified criteria in the source and destination containers, an error is generated.

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

SrcContainerOrBufId

Specifies the identifier of the source data buffer or container. When copying a buffer to a container, you should first set the buffer's component type using MbufControl() with M_COMPONENT_TYPE.

DstContainerBufId

Specifies the identifier of the destination container.

SrcComponent

Specifies the criterion which will be used to determine which components of the source container to copy. If the source is a data buffer, this parameter must be set to M_DEFAULT.

The following settings can be used to uniquely identify a component of the source container.

For specifying which component to copy using a uniquely identifying criterion
Value	Description
M_COMPONENT_BY_ID( MIL_ID ID )	Specifies the component with the specified MIL identifier. (summarize) Specifies the component with the specified MIL identifier. (more details...)
		Parameters
		ID Specifies the MIL identifier of the component.
M_COMPONENT_BY_INDEX( MIL_INT ComponentIndex )	Specifies the component with the specified index in the container. (summarize) Specifies the component with the specified index in the container. (more details...)
		Parameters
		ComponentIndex Specifies the index of the component.

The following settings can be used to copy one or more components of the source criteria.

For specifying which component(s) to copy using a generalized criterion
Value	Description
M_COMPONENT_BY_GROUP_ID( MIL_INT GroupIndex )	Specifies that the component(s) have the specified group ID. The group ID of a component can be inquired using MbufInquireContainer() with M_COMPONENT_GROUP_ID. (summarize) Specifies that the component(s) have the specified group ID. (more details...)
		Parameters
		GroupIndex Specifies the group ID.
M_COMPONENT_BY_REGION_ID( MIL_INT RegionID )	Specifies that the component(s) have the specified region ID. The region ID of a component can be inquired using MbufInquireContainer() with M_COMPONENT_REGION_ID. (summarize) Specifies that the component(s) have the specified region ID. (more details...)
		Parameters
		RegionID Specifies the region ID.
M_COMPONENT_BY_SOURCE_ID( MIL_INT SourceID )	Specifies that the component(s) have the specified source ID. The source ID of a component can be inquired using MbufInquireContainer() with M_COMPONENT_SOURCE_ID. (summarize) Specifies that the component(s) have the specified source ID. (more details...)
		Parameters
		SourceID Specifies the source ID.
M_COMPONENT_ALL	Specifies all components of the container. When used with the M_REPLACE operation, this frees all existing components in the destination container and copies all components of the source container (unless the ControlFlag parameter is set to M_USE_DESTINATION). (summarize) Specifies all components of the container. (more details...)

The following settings can be used to copy one or more components with the specified component type.

For specifying which component(s) to copy by component type
Value	Description
M_COMPONENT_CONFIDENCE	Specifies the components that store confidence information for a M_COMPONENT_RANGE or M_COMPONENT_DISPARITY component of the container. INFO
M_COMPONENT_CUSTOM + n	Specifies the components that have the specified custom component type , identified by n, where n can be a value between 0 and 254. INFO
M_COMPONENT_DISPARITY	Specifies the components that store a disparity map. INFO
M_COMPONENT_INFRARED	Specifies the components that store an intensity image of infrared light.
M_COMPONENT_INTENSITY	Specifies the components that store an intensity image of visible light.
M_COMPONENT_MESH_MIL	Specifies the components that store mesh information for a M_COMPONENT_RANGE component of the container. INFO
M_COMPONENT_METADATA	Specifies the components that store metadata information. INFO
M_COMPONENT_MULTISPECTRAL	Specifies the components that store an intensity image where each band represents the intensity of a specific wavelength of light. INFO
M_COMPONENT_NORMALS_MIL	Specifies the components that store normals information for each point in the M_COMPONENT_RANGE component of the container. INFO
M_COMPONENT_RANGE	Specifies the components that store 3D distance/position information. INFO
M_COMPONENT_REFLECTANCE	Specifies the components that store a reflectance map. INFO
M_COMPONENT_SCATTER	Specifies the components that store a scatter map. INFO
M_COMPONENT_ULTRAVIOLET	Specifies the components that store an intensity image of ultraviolet light.
M_COMPONENT_UNDEFINED	Specifies the components that store information of an unknown type.

Operation

Specifies how to copy the source buffer or component(s) to the destination container.

For specifying the operation to perform
Value	Description
M_APPEND	Specifies that a new buffer is allocated and added as a component of the destination container for each buffer to be copied.
M_REPLACE	Specifies that existing component(s) in the destination container are replaced with the copied buffer(s). This operation is not available when SrcComponent is set to a setting from the table For specifying which component to copy using a uniquely identifying criterion. For each buffer to be copied, MIL determines if an existing component meets the same specified criteria and has the same buffer attributes (such as M_SIZE_X) as the source component; if so, it reuses the existing component. If no matching component is found, a new buffer is allocated with the correct attributes and added to the destination container. Any components in the destination container that meet the same specified criterion, but are not used during the copy operation, are freed. If the source is a buffer, its M_COMPONENT_TYPE setting is used to determine which component in the destination to replace. An error will be generated if there is more than one component with this component type in the destination container. (summarize) Specifies that existing component(s) in the destination container are replaced with the copied buffer(s). (more details...)

ControlFlag

Specifies whether to copy the data, settings, and attributes. This parameter can be set to one of the following:

For specifying how the buffer or container is copied
Value	Description
M_DEFAULT	Same as M_BASIC_ATTRIBUTE.
M_BASIC_ATTRIBUTE +	Specifies to copy the specified buffer (or component(s) of the specified container) to the destination container, including all data and settings. Optional attributes of buffers are not copied. For example, if the source buffer was allocated with the M_COMPRESS attribute, the destination buffer will be uncompressed. (summarize) Specifies to copy the specified buffer (or component(s) of the specified container) to the destination container, including all data and settings. (more details...)
M_IDENTICAL +	Specifies to copy the specified buffer (or component(s) of the specified container) to the destination container including all data, settings, and attributes (except M_PROC, M_GRAB and M_DISP which are always the same as the attributes of the destination container).
M_USE_DESTINATION	Specifies that all components in the source container that meet the criteria (specified in the SrcComponent parameter) are copied by rank to existing components in the destination container that meet the criteria. For example, if SrcComponent is set to M_COMPONENT_BY_GROUP_ID(), the first component with the specified group ID in the source container is copied to the first component with that group ID in the destination container, the second component with the specified group ID in the source container is copied to the second component with that group ID in the destination container, and so on. If the number of components that meet the specified criteria differs between the source container and destination container, an error is generated. MIL attempts to compensate for any mismatch in the size and attributes of the source and destination components. For example, if the destination component has the M_COMPRESS attribute but the source component does not, MIL automatically compresses the data. If MIL cannot compensate, an error is generated. This setting is only available for the M_REPLACE operation, with a container as a source. (summarize) Specifies that all components in the source container that meet the criteria (specified in the SrcComponent parameter) are copied by rank to existing components in the destination container that meet the criteria. (more details...)

Combination values for M_BASIC_ATTRIBUTE; M_IDENTICAL.

You can add one or more of the following values to the above-mentioned values to specify how the source is used for the copy operation.

For specifying how the source is used
Combination value	Description
M_NO_COPY_SOURCE_DATA	Specifies to allocate component(s) in the destination container with the same component type and attributes as the source buffer or component(s), without copying data from the source. In addition, some settings (such as 3D settings, from the table For specifying settings useful with components that store 3D data) are copied. (summarize) Specifies to allocate component(s) in the destination container with the same component type and attributes as the source buffer or component(s), without copying data from the source. (more details...)
M_SOURCE_MUST_EXIST	Specifies to generate an error if there is not at least one component in the source container that fits the specified criterion. This setting is only available when the source is a container. (summarize) Specifies to generate an error if there is not at least one component in the source container that fits the specified criterion. (more details...)

Compilation information

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