API function definitions for data components. More...

#include <mvtec/plugin/mv_decl.h>
#include <mvtec/plugin/mv_types.h>

Functions
MVLibExport MVCode_t	MV_DataComponentDescriptor_GetParameter (MVDataComponentDescriptor_t descriptor, uint32_t parameter, MVValue_t *pValue)
	Gets the value of a parameter of a data component descriptor. More...

MVLibExport MVCode_t	MV_DataComponentDescriptor_SetParameter (MVDataComponentDescriptor_t descriptor, uint32_t parameter, MVValue_t value)
	Sets a parameter of a data component descriptor to a given value. More...

MVLibExport MVDataComponentType_t	MV_DataComponentDescriptor_GetType (MVDataComponentDescriptor_t descriptor)
	Gets the type of a data component descriptor. More...

MVLibExport MVCode_t	MV_DataComponentDescriptor_SetType (MVDataComponentDescriptor_t descriptor, MVDataComponentType_t type)
	Sets a new type for a data component descriptor. More...

MVLibExport bool	MV_DataComponentDescriptor_Equal (MVDataComponentDescriptor_t lhsDescriptor, MVDataComponentDescriptor_t rhsDescriptor)
	Checks whether two data component descriptors refer to the same data component. More...

MVLibExport MVDataComponentType_t	MV_DataComponent_GetType (MVDataComponent_t component)
	Gets the type of a data component. More...

MVLibExport MVCode_t	MV_DataComponent_GetErrorCode (MVDataComponent_t component)
	Gets the error code of an erroneous data component. More...

MVLibExport MVCode_t	MV_DataComponent_GetErrorMessage (MVDataComponent_t component, MVValue_t *pValue)
	Gets the error message of an erroneous data component. More...

MVLibExport size_t	MV_DataComponent_GetByteCount (MVDataComponent_t component)
	Gets the size of the data component's internal data in bytes. More...

MVLibExport const void *	MV_DataComponent_GetPtr (MVDataComponent_t component, size_t *byteCount)
	Gets a pointer to the data component's internal data and the size of the data in bytes. More...

MVLibExport MVCode_t	MV_DataComponent_CopyTo (MVDataComponent_t component, void dest, size_t destSize, size_t offset, size_t pCount)
	Copies the internal data of the data component to a pre-allocated buffer. More...

Detailed Description

API function definitions for data components.

Function Documentation

◆ MV_DataComponent_CopyTo()

MVLibExport MVCode_t MV_DataComponent_CopyTo	(	MVDataComponent_t	component,
		void *	dest,
		size_t	destSize,
		size_t	offset,
		size_t *	pCount
	)

Copies the internal data of the data component to a pre-allocated buffer.

This function copies the data represented by the data component into an existing buffer. In case of large data components, it may be preferable for certain applications to process it in smaller chunks. For this purpose, an offset can be provided which can be successively incremented by the buffer size until the end of the data component is reached.

Parameters

[in]	component	is the handle to the data component whose data to copy.
[in,out]	dest	is the pre-allocated destination buffer to hold the internal data of the data component.
[in]	destSize	is the size of the destination buffer in bytes.
[in]	offset	is the number of bytes to be skipped prior to copying.
[out]	pCount	can point to a variable which will be set to the number of bytes which have actually been copied. This can be left as a `NULL` pointer if it is not of interest.

Returns

MV_CODE_OK The remainder of the data, starting from the offset position, has successfully been copied to the dest buffer.
MV_CODE_DATA_READ_MORE The dest buffer has successfully been filled with data but was not sufficient to hold all of it. The remainder can be copied by advancing the offset position by destSize and repeating this as necessary.
MV_CODE_INV_HANDLE The provided component is not valid.
MV_CODE_INV_VALUE The provided dest pointer is NULL or the destSize is zero. A non-empty buffer is required.
MV_CODE_OUT_OF_RANGE The provided offset is past the end of the data.
In case of a data component of type eMVDataComponentType_Error, the error code contained within is returned. See MV_DataComponent_GetErrorCode().

◆ MV_DataComponent_GetByteCount()

MVLibExport size_t MV_DataComponent_GetByteCount ( MVDataComponent_t component )

Gets the size of the data component's internal data in bytes.

Parameters

[in] component is the handle to the data component that is queried.

Returns: The number of bytes in the data component's internal data.

◆ MV_DataComponent_GetErrorCode()

MVLibExport MVCode_t MV_DataComponent_GetErrorCode ( MVDataComponent_t component )

Gets the error code of an erroneous data component.

When the vision system cannot comply with the type and parameters requested by a data component descriptor, or the data is not longer available in the system, the vision system will send a data component of type eMVDataComponentType_Error instead. This function can be used to obtain an error code which explains the absence of a proper data component.

Parameters

[in] component is the handle to the data component that is queried.

Returns

MV_CODE_OK The provided component is not actually an error.
MV_CODE_INV_HANDLE The data component handle is invalid.
MV_CODE_UNK_DATA_COMPONENT No data component matching the queried descriptor is available in the vision system's result store.
MV_CODE_DATA_PARAM_NOT_SUPPORTED The requested data component type or parameters cannot be satisfied by the vision system.
MV_CODE_DATA_CONVERSION_FAILED The conversion of the data component to the requested type failed.
Other error codes may be issued by the vision system.

◆ MV_DataComponent_GetErrorMessage()

MVLibExport MVCode_t MV_DataComponent_GetErrorMessage	(	MVDataComponent_t	component,
		MVValue_t *	pValue
	)

Gets the error message of an erroneous data component.

In addition to the error code accompanying a data component of type eMVDataComponentType_Error, the component may also store a decorating error message that further describes the error. This function can be used to obtain such a message.

Parameters

[in]	component	is the handle to the data component that is queried.
[out]	pValue	points to the value handle that is initialized with a copy of the decorating error message.

Returns

MV_CODE_OK The provided component is an error and the accompanying message has been stored at the given pValue.
MV_CODE_INV_HANDLE The data component handle is invalid.
MV_CODE_INV_VALUE The pointer pValue is NULL.
MV_CODE_FAILED The provided component is not an error.

◆ MV_DataComponent_GetPtr()

MVLibExport const void* MV_DataComponent_GetPtr	(	MVDataComponent_t	component,
		size_t *	byteCount
	)

Gets a pointer to the data component's internal data and the size of the data in bytes.

This function grants access to the data represented by the data component. The byteCount will hold the number of bytes which can safely be read, starting from the returned pointer. Note that the internal data must not be accessed after MV_DataContainer_Clear() has been called on the underlying data container.

Plug-ins may use this function to minimize copies of the data, particularly when interfacing with third-party libraries. If the data merely ought to be copied into a separate buffer, prefer using MV_DataComponent_CopyTo().

Parameters

[in]	component	is the handle to the data component that is queried.
[out]	byteCount	can point to a variable which will be set to the size of the data component in bytes. This can be left as a `NULL` pointer if the size is not of interest or already known.

Returns: The pointer to the beginning of the data component's internal data or NULL if there is no data or the component is invalid.

◆ MV_DataComponent_GetType()

MVLibExport MVDataComponentType_t MV_DataComponent_GetType ( MVDataComponent_t component )

Gets the type of a data component.

Parameters

[in] component is the handle to the data component that is queried.

Returns: The enumerator from MVDataComponentType_t corresponding to the type of the data component, or eMVDataComponentType_Null if the component is invalid.

◆ MV_DataComponentDescriptor_Equal()

MVLibExport bool MV_DataComponentDescriptor_Equal	(	MVDataComponentDescriptor_t	lhsDescriptor,
		MVDataComponentDescriptor_t	rhsDescriptor
	)

Checks whether two data component descriptors refer to the same data component.

Equality is defined regarding the data component on the vision system. It does neither take any differences in the specified type or parameters into account, nor does it consider which data container descriptor it is associated to.

For example, two data component descriptors which have been obtained independently from one another through MV_Event_GetDataContainerDescriptor() and MV_Result_GetDataContainerDescriptor(), respectively, will be considered equal and this will continue to hold after either one has been modified through MV_DataComponentDescriptor_SetType() or MV_DataComponentDescriptor_SetParameter(), respectively.

Parameters

lhsDescriptor	is a handle to one of the data component descriptors.
rhsDescriptor	is a handle to the other data component descriptor.

Returns: A Boolean indicating whether the two descriptors refer to the same data component. In case either or both of the handles are invalid, false is returned.

◆ MV_DataComponentDescriptor_GetParameter()

MVLibExport MVCode_t MV_DataComponentDescriptor_GetParameter	(	MVDataComponentDescriptor_t	descriptor,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets the value of a parameter of a data component descriptor.

Initializes a new MVValue_t with a copy of the requested parameter. It is the caller's responsibility to destroy this copy by way of MV_Value_Clear().

See mv_data_component_def.h for a table of applicable parameters.

Parameters

[in]	descriptor	is a handle to the data component descriptor that is queried.
[in]	parameter	is one of the parameter keys listed in mv_data_component_def.h.
[out]	pValue	points to the value handle that is initialized with a copy of the value of the queried parameter.

Returns

MV_CODE_OK The data component descriptor parameter value corresponding to the specified parameter key was successfully used to initialize the value pointed to by pValue.
MV_CODE_INV_HANDLE The provided descriptor is not valid.
MV_CODE_INV_VALUE The pointer pValue is NULL.
MV_CODE_INV_PARAM The provided parameter key does not match any parameters which apply to the data component descriptor.

◆ MV_DataComponentDescriptor_GetType()

MVLibExport MVDataComponentType_t MV_DataComponentDescriptor_GetType ( MVDataComponentDescriptor_t descriptor )

Gets the type of a data component descriptor.

Parameters

[in] descriptor is a handle to the data component descriptor.

Returns: The enumerator from MVDataComponentType_t corresponding to the type currently set on the data component descriptor, or eMVDataComponentType_Null if the descriptor is invalid.

◆ MV_DataComponentDescriptor_SetParameter()

MVLibExport MVCode_t MV_DataComponentDescriptor_SetParameter	(	MVDataComponentDescriptor_t	descriptor,
		uint32_t	parameter,
		MVValue_t	value
	)

Sets a parameter of a data component descriptor to a given value.

Depending on the current type of the data component descriptor, it is parametrized in different ways. The parameter is identified by numeric constants. See mv_data_component_def.h for a table of applicable parameters.

Remarks: Calling this function will copy the value of the parameter, such that the caller may destroy the value passed as an argument immediately after calling by way of MV_Value_Clear().

Parameters

[in]	descriptor	is a handle to the data component descriptor whose parameter is set.
[in]	parameter	identifies the parameter that is set; must match one of the parameters supported by a data component of the given type.
[in]	value	is the MVValue_t that is copied into the data component descriptor.

Returns

MV_CODE_OK The provided value was successfully stored in the data component descriptor for the given parameter. value may now be cleared.
MV_CODE_INV_HANDLE The data component descriptor handle is invalid.
MV_CODE_INV_VALUE The provided value is invalid. Either it is not properly initialized or its numeric value is out of range for the given parameter.
MV_CODE_INV_PARAM The provided parameter does not apply to the descriptor type. See mv_data_component_def.h for a table of supported parameters.
MV_CODE_VALUE_TYPE_MISMATCH The provided value's type does not match the expectation for the specified parameter.
MV_CODE_DATA_TYPE_MISMATCH The provided value's data type does not match the expectation for the specified parameter.

◆ MV_DataComponentDescriptor_SetType()

MVLibExport MVCode_t MV_DataComponentDescriptor_SetType	(	MVDataComponentDescriptor_t	descriptor,
		MVDataComponentType_t	type
	)

Sets a new type for a data component descriptor.

Overwrites the current type of a data component descriptor. When the corresponding data container descriptor is used to fetch the data container from the vision system, it will try to convert the data to the specified type. Note that the vision system may not be able to comply with this request and will instead send a data component of type eMVDataComponentType_Error.

Parameters

[in]	descriptor	is a handle to the data component descriptor.
[in]	type	is the new type which is to be set.

Returns

MV_CODE_OK The provided type was successfully set.
MV_CODE_INV_HANDLE The data component descriptor handle is invalid.
MV_CODE_INV_DATA_COMPONENT_TYPE The provided type is invalid.

Functions

Detailed Description

Function Documentation

◆ MV_DataComponent_CopyTo()

◆ MV_DataComponent_GetByteCount()

◆ MV_DataComponent_GetErrorCode()

◆ MV_DataComponent_GetErrorMessage()

◆ MV_DataComponent_GetPtr()

◆ MV_DataComponent_GetType()

◆ MV_DataComponentDescriptor_Equal()

◆ MV_DataComponentDescriptor_GetParameter()

◆ MV_DataComponentDescriptor_GetType()

◆ MV_DataComponentDescriptor_SetParameter()

◆ MV_DataComponentDescriptor_SetType()