API function definitions for querying the recipe store. More...

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

Macros
#define	MV_RecipeList_foreach(list, recipe)
	Macro for iterating over the recipes in a list. More...

#define	MV_Recipe_InputParam_foreach(recipe, param)
	Macro for iterating over the input parameters in a recipe. More...

#define	MV_Recipe_OutputParam_foreach(recipe, param)
	Macro for iterating over the output parameters in a recipe. More...

#define	MV_Recipe_OutputDataInfo_foreach(recipe, info)
	Macro for iterating over the output data information in a recipe. More...

Functions
MVLibExport MVCode_t	MV_GetRecipeList (MVPlugin_t handle, MVRecipeList_t *pList)
	Obtains the list of available recipes from the vision system. More...

MVLibExport MVCode_t	MV_RecipeList_GetRecipeById (MVRecipeList_t list, MVValue_t recipeId, MVRecipe_t *pRecipe)
	Looks up a recipe with the given recipe ID and copies it if one is found. More...

MVLibExport void	MV_RecipeList_Clear (MVRecipeList_t *pList)
	Destroys a recipe list. More...

MVLibExport size_t	MV_RecipeList_GetSize (MVRecipeList_t list)
	Gets the number of recipes in a recipe list. More...

MVLibExport MVCode_t	MV_RecipeList_SetFilter (MVRecipeList_t list, uint32_t filter, MVValue_t value)
	Filters a given recipe list according to predefined criteria. More...

MVLibExport MVRecipe_t	MV_RecipeList_Next (MVRecipeList_t list)
	Iterates over a recipe list. More...

MVLibExport MVCode_t	MV_RecipeList_Rewind (MVRecipeList_t list)
	Resets the built-in pointer to the beginning of a recipe list. More...

MVLibExport MVCode_t	MV_Recipe_GetParameter (MVRecipe_t recipe, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value of a given recipe. More...

MVLibExport void	MV_Recipe_Clear (MVRecipe_t *pRecipe)
	Destroys a recipe. More...

MVLibExport MVRecipeParam_t	MV_Recipe_InputParam_Next (MVRecipe_t recipe)
	Iterates over the input parameters of a given recipe. More...

MVLibExport MVRecipeParam_t	MV_Recipe_OutputParam_Next (MVRecipe_t recipe)
	Iterates over the output parameters of a given recipe. More...

MVLibExport MVDataInfo_t	MV_Recipe_OutputDataInfo_Next (MVRecipe_t recipe)
	Iterates over the output data information of a given recipe. More...

MVLibExport MVCode_t	MV_Recipe_InputParam_Rewind (MVRecipe_t recipe)
	Resets the built-in pointer to the beginning of a recipe input parameter list. More...

MVLibExport MVCode_t	MV_Recipe_OutputParam_Rewind (MVRecipe_t recipe)
	Resets the built-in pointer to the beginning of a recipe output parameter list. More...

MVLibExport MVCode_t	MV_Recipe_OutputDataInfo_Rewind (MVRecipe_t recipe)
	Resets the built-in pointer to the beginning of a recipe's output data info. More...

MVLibExport size_t	MV_Recipe_InputParam_GetSize (MVRecipe_t recipe)
	Gets the number of input parameters of a given recipe. More...

MVLibExport size_t	MV_Recipe_OutputParam_GetSize (MVRecipe_t recipe)
	Gets the number of output parameters of a given recipe. More...

MVLibExport size_t	MV_Recipe_OutputDataInfo_GetSize (MVRecipe_t recipe)
	Gets the number of output data components of a given recipe. More...

MVLibExport MVCode_t	MV_RecipeParam_GetParameter (MVRecipeParam_t recipeParam, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value of a given recipe input or output parameter. More...

MVLibExport MVCode_t	MV_DataInfo_GetParameter (MVDataInfo_t dataInfo, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value of a given recipe data component information. More...

Detailed Description

API function definitions for querying the recipe store.

Macro Definition Documentation

◆ MV_Recipe_InputParam_foreach

#define MV_Recipe_InputParam_foreach	(	recipe,
		param
	)

Value:

MV_Recipe_InputParam_Rewind(recipe); \

for ((param) = MV_Recipe_InputParam_Next(recipe); (param); (param) = MV_Recipe_InputParam_Next(recipe))

Macro for iterating over the input parameters in a recipe.

◆ MV_Recipe_OutputDataInfo_foreach

#define MV_Recipe_OutputDataInfo_foreach	(	recipe,
		info
	)

Value:

MV_Recipe_OutputDataInfo_Rewind(recipe); \

for ((info) = MV_Recipe_OutputDataInfo_Next(recipe); (info); (info) = MV_Recipe_OutputDataInfo_Next(recipe))

Macro for iterating over the output data information in a recipe.

◆ MV_Recipe_OutputParam_foreach

#define MV_Recipe_OutputParam_foreach	(	recipe,
		param
	)

Value:

MV_Recipe_OutputParam_Rewind(recipe); \

for ((param) = MV_Recipe_OutputParam_Next(recipe); (param); (param) = MV_Recipe_OutputParam_Next(recipe))

Macro for iterating over the output parameters in a recipe.

◆ MV_RecipeList_foreach

#define MV_RecipeList_foreach	(	list,
		recipe
	)

Value:

MV_RecipeList_Rewind(list); \

for ((recipe) = MV_RecipeList_Next(list); (recipe); (recipe) = MV_RecipeList_Next(list))

Macro for iterating over the recipes in a list.

Function Documentation

◆ MV_DataInfo_GetParameter()

MVLibExport MVCode_t MV_DataInfo_GetParameter	(	MVDataInfo_t	dataInfo,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value of a given recipe data component information.

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

The following parameters are available (followed by the type of the correspondingly retrieved MVValue_t):

MV_PARAM_DATAINFO_NAME : String
MV_PARAM_DATAINFO_DESCRIPTION : String

Parameters

dataInfo	is a handle to the recipe output data component information that is queried.
parameter	is one of the above `MV_PARAM_DATA_*` defines.
pValue	points to the value handle that is initialized with a copy of the value of the queried parameter.

Returns

MV_CODE_OK The recipe 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 dataInfo is not valid.
MV_CODE_UNK_PARAM The provided parameter key does not match any parameters which apply to output data components.

◆ MV_GetRecipeList()

MVLibExport MVCode_t MV_GetRecipeList	(	MVPlugin_t	handle,
		MVRecipeList_t *	pList
	)

Obtains the list of available recipes from the vision system.

Remarks: Each call to MV_GetRecipeList() has to be balanced by a call to MV_RecipeList_Clear().

Parameters

[in]	handle	is the Communicator handle for the plug-in instance.
[out]	pList	points to the uninitialized recipe list handle that is initialized with the current recipe list.

Returns

MV_CODE_OK The recipe list has been successfully retrieved and pList has been initialized with it.
MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
MV_CODE_INV_VALUE The provided pointer pList is NULL.
MV_CODE_TIMEOUT The retrieval of the recipe list from the vision system timed out. The vision system may not be running at all.
MV_CODE_PLUGIN_NOT_REGISTERED The plug-in is not currently registered. This indicates that MV_GetRecipeList has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
MV_CODE_OUT_OF_MEM The recipe list could not be stored because the system is out of memory.
MV_CODE_FAILED An unknown problem has occurred.

◆ MV_Recipe_Clear()

MVLibExport void MV_Recipe_Clear ( MVRecipe_t * pRecipe )

Destroys a recipe.

Each copy of a recipe made using MV_RecipeList_GetRecipeById() must be balanced by a call to MV_Recipe_Clear().

Remarks: Note that recipe handles obtained by iterating over a recipe list using MV_RecipeList_Next() or the MV_RecipeList_foreach() macro must not be destroyed.

Parameters

[in,out] pRecipe points to the handle to the recipe that is destroyed.

◆ MV_Recipe_GetParameter()

MVLibExport MVCode_t MV_Recipe_GetParameter	(	MVRecipe_t	recipe,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value of a given recipe.

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

The following parameters are available (followed by the type of the correspondingly retrieved MVValue_t):

Parameters

[in]	recipe	is the handle to the recipe that is queried.
[in]	parameter	is one of the above `MV_PARAM_RECIPE_*` defines.
[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 recipe parameter value corresponding to the specified parameter key was successfully used to initialize the value pointed to by pValue.
MV_CODE_INV_HANDLE One of the following:
- The provided recipe is not valid.
- The pointer pValue is NULL.
MV_CODE_UNK_PARAM The provided parameter key does not match any parameters which apply to recipes.
MV_CODE_UNSET_PARAM MV_PARAM_RECIPE_ACQ_SEQ is queried but there is no acquisition sequence explicitly associated with this recipe. The default acquisition sequence of the active configuration will be used instead in this case.

◆ MV_Recipe_InputParam_GetSize()

MVLibExport size_t MV_Recipe_InputParam_GetSize ( MVRecipe_t recipe )

Gets the number of input parameters of a given recipe.

Parameters

[in] recipe is the handle to the recipe that is queried.

Returns: The number of input parameters of the queried recipe.

◆ MV_Recipe_InputParam_Next()

MVLibExport MVRecipeParam_t MV_Recipe_InputParam_Next ( MVRecipe_t recipe )

Iterates over the input parameters of a given recipe.

Recipes have a built-in pointer to the "current" recipe input and output parameters. This function returns a handle to the currently pointed-to recipe input parameter and advances the corresponding pointer by one. If the end of the recipe's input parameters is reached, the returned recipe parameter handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Remarks: Note that the handles returned by the function are non-owning. They remain valid only until their corresponding recipe is destroyed.

Parameters

[in] recipe is the handle to the recipe that is iterated over.

Returns: A non-owning handle to the currently pointed-to input parameter.

◆ MV_Recipe_InputParam_Rewind()

MVLibExport MVCode_t MV_Recipe_InputParam_Rewind ( MVRecipe_t recipe )

Resets the built-in pointer to the beginning of a recipe input parameter list.

Parameters

[in] recipe is the handle to the recipe whose internal input parameter pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided recipe is not valid.

◆ MV_Recipe_OutputDataInfo_GetSize()

MVLibExport size_t MV_Recipe_OutputDataInfo_GetSize ( MVRecipe_t recipe )

Gets the number of output data components of a given recipe.

Parameters

[in] recipe is the handle to the recipe that is queried.

Returns: The number of output data components of the queried recipe.

◆ MV_Recipe_OutputDataInfo_Next()

MVLibExport MVDataInfo_t MV_Recipe_OutputDataInfo_Next ( MVRecipe_t recipe )

Iterates over the output data information of a given recipe.

Recipes have a built-in pointer to the "current" recipe output data information. This function returns a handle to the currently pointed-to recipe output data information and advances the corresponding pointer by one. If the end of the recipe's data information is reached, the returned recipe data information handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Note that the handles returned by the function are non-owning. They remain valid only until their corresponding recipe is destroyed.

Parameters

[in] recipe is the handle to the recipe that is iterated over.

Returns: A non-owning handle to the currently pointed-to output data information.

◆ MV_Recipe_OutputDataInfo_Rewind()

MVLibExport MVCode_t MV_Recipe_OutputDataInfo_Rewind ( MVRecipe_t recipe )

Resets the built-in pointer to the beginning of a recipe's output data info.

Parameters

[in] recipe is the handle to the recipe whose internal data info pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided recipe is not valid.

◆ MV_Recipe_OutputParam_GetSize()

MVLibExport size_t MV_Recipe_OutputParam_GetSize ( MVRecipe_t recipe )

Gets the number of output parameters of a given recipe.

Parameters

[in] recipe is the handle to the recipe that is queried.

Returns: The number of output parameters of the queried recipe.

◆ MV_Recipe_OutputParam_Next()

MVLibExport MVRecipeParam_t MV_Recipe_OutputParam_Next ( MVRecipe_t recipe )

Iterates over the output parameters of a given recipe.

Recipes have a built-in pointer to the "current" recipe input and output parameters. This function returns a handle to the currently pointed-to recipe output parameter and advances the corresponding pointer by one. If the end of the recipe's output parameters is reached, the returned recipe parameter handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Note that the handles returned by the function are non-owning. They remain valid only until their corresponding recipe is destroyed.

Parameters

[in] recipe is the handle to the recipe that is iterated over.

Returns: A non-owning handle to the currently pointed-to output parameter.

◆ MV_Recipe_OutputParam_Rewind()

MVLibExport MVCode_t MV_Recipe_OutputParam_Rewind ( MVRecipe_t recipe )

Resets the built-in pointer to the beginning of a recipe output parameter list.

Parameters

[in] recipe is the handle to the recipe whose internal output parameter pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided recipe is not valid.

◆ MV_RecipeList_Clear()

MVLibExport void MV_RecipeList_Clear ( MVRecipeList_t * pList )

Destroys a recipe list.

Each call to MV_GetRecipeList() has to be balanced by a call to MV_RecipeList_Clear().

Parameters

[in,out] pList points to the recipe list handle that is destroyed.

◆ MV_RecipeList_GetRecipeById()

MVLibExport MVCode_t MV_RecipeList_GetRecipeById	(	MVRecipeList_t	list,
		MVValue_t	recipeId,
		MVRecipe_t *	pRecipe
	)

Looks up a recipe with the given recipe ID and copies it if one is found.

Parameters

[in]	list	is the handle to the recipe list in which the recipe is looked up.
[in]	recipeId	is the handle to the value holding the recipeId that is looked up. The value should be of scalar String type.
[out]	pRecipe	points to the uninitialized recipe handle that is initialized with the looked up recipe.

Returns

MV_CODE_OK A recipe with the specified recipeId has been found in the list and *pRecipe has been successfully initialized with a copy.
MV_CODE_INV_HANDLE The provided list is not valid.
MV_CODE_INV_VALUE The provided pointer pRecipe is NULL.
MV_CODE_UNK_RECIPE The list does not contain any recipe with the specified recipeId or the value and data type of recipeId may not be correct. Presently, recipe ID are limited to scalar String values.
MV_CODE_OUT_OF_MEM The recipe could not be stored because the system is out of memory.

◆ MV_RecipeList_GetSize()

MVLibExport size_t MV_RecipeList_GetSize ( MVRecipeList_t list )

Gets the number of recipes in a recipe list.

Parameters

[in] list is the handle to the recipe list that is queried.

Returns: The number of recipes in the list.

◆ MV_RecipeList_Next()

MVLibExport MVRecipe_t MV_RecipeList_Next ( MVRecipeList_t list )

Iterates over a recipe list.

Recipe lists have a built-in pointer to the "current" recipe. This function returns a handle to the currently pointed-to recipe and advances the pointer by one. If the end of the recipe list is reached, the returned recipe handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Remarks: Note that the handles returned by the function are non-owning. They remain valid only until the recipe list is destroyed and calling MV_Recipe_Clear() on them is undefined behavior.

Parameters

[in] list is the handle to the recipe list that is iterated over.

Returns: A non-owning handle to the currently pointed-to recipe in the list.

◆ MV_RecipeList_Rewind()

MVLibExport MVCode_t MV_RecipeList_Rewind ( MVRecipeList_t list )

Resets the built-in pointer to the beginning of a recipe list.

Parameters

[in] list is the handle to the recipe list whose internal pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided recipe list is not valid.

◆ MV_RecipeList_SetFilter()

MVLibExport MVCode_t MV_RecipeList_SetFilter	(	MVRecipeList_t	list,
		uint32_t	filter,
		MVValue_t	value
	)

Filters a given recipe list according to predefined criteria.

The following three options are available for the filter argument:

MV_FILTER_RECIPELIST_IS_PREPARED : Only keep recipes which are currently prepared.
MV_FILTER_RECIPELIST_NOT_PREPARED : Only keep recipes which are currently not prepared.
MV_FILTER_RECIPELIST_RANGE_IDXS : Only keep recipes in a specified range of indices:
- If value is a scalar UInt32, keep recipes from that index forward;
- If value is an UInt32 array with two elements, keep recipes in the range [value[0], value[1]).

Set a filter using this function actually removes the recipes which don't match it from the recipe list. Thus, calling this function repeatedly compounds the applied filters.

Parameters

[in]	list	is the handle to the recipe list that is filtered.
[in]	filter	is one of the `MV_FILTER_RECIPELIST_*` defines.
[in]	value	is a handle to the scalar or array UInt32 value that is used to specify the index range for MV_FILTER_RECIPELIST_RANGE_IDXS.

Returns

MV_CODE_OK The specified filter has been applied successfully.
MV_CODE_INV_HANDLE The provided list is not valid.
MV_CODE_INV_VALUE In case the MV_FILTER_RECIPELIST_RANGE_IDXS filter is used, either value is NULL or its value or data type do not match the requirements or the specified range is itself invalid, i.e. valid[0] > valid[1].
MV_CODE_UNK_FILTER The type of filter that has been specified is unknown.

◆ MV_RecipeParam_GetParameter()

MVLibExport MVCode_t MV_RecipeParam_GetParameter	(	MVRecipeParam_t	recipeParam,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value of a given recipe input or output parameter.

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

The following parameters are available (followed by the type of the correspondingly retrieved MVValue_t):

MV_PARAM_RECIPEPARAM_NAME : String
MV_PARAM_RECIPEPARAM_DESCRIPTION : String
MV_PARAM_RECIPEPARAM_VALUETYPE : UInt32 corresponds to a bitmask of one or more of the values in MVValueType_t
MV_PARAM_RECIPEPARAM_DATATYPE : UInt32 corresponds to the numeric value of one of the values in MVDataType_t

Parameters

recipeParam	is a handle to the recipe input or output parameter that is queried.
parameter	is one of the above `MV_PARAM_RECIPEPARAM_*` defines.
pValue	points to the value handle that is initialized with a copy of the value of the queried parameter.

Returns

MV_CODE_OK The recipe 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 recipeParam is not valid.
MV_CODE_UNK_PARAM The provided parameter key does not match any parameters which apply to recipe parameters.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MV_Recipe_InputParam_foreach

◆ MV_Recipe_OutputDataInfo_foreach

◆ MV_Recipe_OutputParam_foreach

◆ MV_RecipeList_foreach

Function Documentation

◆ MV_DataInfo_GetParameter()

◆ MV_GetRecipeList()

◆ MV_Recipe_Clear()

◆ MV_Recipe_GetParameter()

◆ MV_Recipe_InputParam_GetSize()

◆ MV_Recipe_InputParam_Next()

◆ MV_Recipe_InputParam_Rewind()

◆ MV_Recipe_OutputDataInfo_GetSize()

◆ MV_Recipe_OutputDataInfo_Next()

◆ MV_Recipe_OutputDataInfo_Rewind()

◆ MV_Recipe_OutputParam_GetSize()

◆ MV_Recipe_OutputParam_Next()

◆ MV_Recipe_OutputParam_Rewind()

◆ MV_RecipeList_Clear()

◆ MV_RecipeList_GetRecipeById()

◆ MV_RecipeList_GetSize()

◆ MV_RecipeList_Next()

◆ MV_RecipeList_Rewind()

◆ MV_RecipeList_SetFilter()

◆ MV_RecipeParam_GetParameter()