Library Parameters

Library Parameters provides several mayor advantages for the parametrization of designs during design time AND during runtime:

  • It allows to set paths to specific parameters which may be deeply embedded in hierarchical structures. This way, even parameters in protected hierarchical boxes (or in protected hierarchical boxes that are nestled in other protected hierarchical boxes) can be set and reset during runtime, since their parametrization interface is lifted up in the hierarchy to a hierarchical level that is not access restricted.
  • You can set up nets and/or chains of parameters in your design, allowing to forward one parameter value to various other operators. This way, you can simplify the parametrization of the final applet: The final user may, e.g., set one parameter once, and, triggered from this write process, various other parameters within the design will be set accordantly without any further user interaction.
  • With the translator operators of the library, you can not only forward parameter values, but make the design calculate new values out of the current values of various parameters and write the result to still other parameters any place in the design. You define the formulas yourself. The syntax of the formulas complies to the GenICam standard (GenICam API version 2.0) and is described below.

The good thing about the parameters library is that you can set up connections (nets or chains) between parameter values in your design without actually touching the data flow structure of the design.

Library Parameters contains six reference operators and three translation operators. Find more information about both types of operators below.

Example designs using the operators of the Parameters Library you find in your VisualApplets installation: C:\Program Files\SiliconSoftware\VisualApplets\Examples\AdvancedVAFunctions\Parameters Library.

[Important] Availability

You can purchase a separate license for the Parameters library.

When using the VisualApplets extension Expert, you do not need to purchase a license for the Parameters library as it is already included in the VisualApplets Expert license.

************************************************************

The Reference Operators

The Reference operators of the Parameters library allow a 1:1 mapping of an operator parameter to the map parameter Value (or Field) of the reference operator. You specify the referenced parameter (path and name) in parameter "Reference".

You can define a target within the design hierarchy where the referenced parameter will be visible and accessible. The target is defined by two parameters: "DisplayHierarchy" and "DisplayName". In "DisplayHierarchy" you address a hierarchical box within the same process the reference operator itself is located in. In parameter "DisplayName" you set up the name for the target parameter. If "DisplayHierarchy" and "DisplayName" are both set, the parameter defined by "DisplayName" will be available in the hierarchical box addressed by "DisplayHierarchy". If "DisplayName" is empty, no parameter is created. If "DisplayName" is set, but "DisplayHierarchy" is empty, the parameter defined by "DisplayName" is added to the parent hierarchy (i.e., the hierarchical box the reference operator itself is located in).

This allows you to make a parameter of your design available on any hierarchical level (of the design) you want. For example, you can make the parameters of modules within a protected hierarchical box available for parametrization directly under the properties of the protected hierarchical box itself.

Mapped parameters can be referenced themselves. Thus, you can reference either the content of parameter Value in a reference operator, or reference the parameter you have defined in the parameters "DisplayName" and "DisplayHierarchy". This is especially important when protected hierarchical boxes are built up out of other protected hierarchical boxes.

[Note] All connected parameters update at once

If one of the connected parameters is changed (referenced parameter, map parameter "Value", or target parameter), the value is changed in all other connected parameters, too.

To set up map parameters, you simply proceed 2 to 3 steps:

  1. Instantiate a reference operator.
  2. Define a source parameter (e.g., a parameter that is deeply nestled within the hierarchy). Immediately, the value of the source parameter is mirrored in the map parameter of the reference operator instance.
  3. (Optionally) define name and location (path to target hierarchical box and parameter name) of a second map parameter.

All map parameters are treated as a normal parameters by the environment. You can access them via SDK or the runtime tools the same way you access "original" operator parameters.

Each instance of a reference operator allows to set up an 1:1 relation between the value of any parameter in your design and the map parameter (parameter Value) of the reference operator instance.

Data types supported by reference operators:

To create map parameters, you first need to instantiate one reference operator. For each possible data type, you have one reference operator available:

Operator Name Data types that are supported by this operator
IntParamReference Integer (VA_SINT, VA_UINT)
EnumParamReference Enumeration (VA_ENUM)
FloatParamReference Floating Point (VA_DOUBLE)
IntFieldParamReference Integer Fields (VA_SINTFIELD, VA_UINTFIELD)
FloatFieldParamReference Floating Point Fields (VA_DOUBLEFIELD)
StringParamReference String (VA_STRING,VA_FILENAME,VA_METADATA)

Table 34. Data types supported by reference operators


Procedure for creating map values with Reference Operators:

  1. Instantiate the reference operator of the data type you need.

  2. Double click on the reference operator instance to open its module properties.

  3. In Parameter Reference, specify the source parameter that you want the reference operator instance to connect to.

In the example below, an instance of the operator IntParamReference with the name Reference Operator Example connects to the parameter YLength in module Buffer. In this example, both modules (Reference Operator Example and Buffer) are located on the same hierarchical level.

Path to referenced parameter:

Referenced parameter:

[Note] Syntax for Referencing

The syntax is as follows:

<Path> is the relative path to the hierarchical level where the referenced module "Module" is located. Use a slash as separator between different hierarchical levels. Define the path as relative path from the hierarchical level the reference operator instance is located in.

<Module> is the name of the module (operator instance or hierarchical box) that contains the referenced parameter.

<ParamName> is the actual name of the referenced parameter.

If <Path> starts with a slash, the path is interpreted as absolute path starting from design level (e.g., /Process0/UUT/SetParam.Value).

You can also use ../ to go up a level. However, take care you don't use this option when designing freely replicable or relocatable modules.

  1. Set Parameter Activate to "Yes".

  2. Click Apply. The value of the referenced parameter is displayed in parameter Value (wich is the map parameter).

In our example, the value of parameter YLength in operator Buffer is now also available in parameter Value of the reference operator instance:

With parameter Value in your reference operator, you can do many things.

You can, for example, make the value you have in parameter Value available in yet another module (operator instance or hierarchical box) anyplace in your design. To do so:

  1. Define the name of a completely new parameter that is to bear the same value as parameter Value. You do this in parameter DisplayName of the reference operator. You are completely free in defining the name.

  2. Define the module within your design that is to bear this new parameter. You do this in parameter DisplayHierarchy of the reference operator.

[Note] Syntax for Setting up Path to Display Target

If you want the new parameter to show up in another place of the design, you need to specify the path to the hierarchical box that is to contain the new parameter in parameter DisplayHierarchy.

The syntax is as follows:

<Path> is the relative path from process level to the hierarchical level of the design where the <Hierarchical Box> is located that is to receive the new parameter. Thus, parameter DisplayHierarchy can only address hierarchical boxes within the same process. Use a slash as separator between different hierarchical levels.

<HierarchicalBox> is the name of the hierarchical box that is to receive the new map parameter.

Example: Level0/Level1

In our example, parameter Value of the reference operator instance is connected to a new parameter ConnectionToYLengthInModuleBuffer of module ModuleWithConnectedParameter :

If parameter Activate is set to "Yes", after clicking the Apply button, the new parameter is displayed with the correct value in the connected module:

Thus, the new parameter ConnectionToYLengthInModuleBuffer of module ModuleWithConnectedParameter has the same value as parameter YLength of module Buffer.

The mapping is done by the reference operator instance.

If the connected parameters of any of the three modules is reset, the value is reset in all other modules, too:

Hierarchical Boxes:

The Reference operators of the Parameters library allow you to make a parameter of your design available on any hierarchical level (of the design) you want. This is especially helpful if you want to allow parametrization of parameters nestled deeply within protected hierarchical boxes during runtime (i.e., if you want to make them available as dynamic write parameters). To allow easy parametrization of hierarchical boxes, hierarchical boxes can carry parameters now (as parameters in the Properties of the hierarchical box itself).

The Reference operators allow to set paths from the surface of a hierarchical box (Properties of the hierarchical box) to specific parameters which may be deeply embedded. This way, even parameters in protected hierarchical boxes (or in protected hierarchical boxes that are nestled in other protected hierarchical boxes) can be set and reset during runtime, since their parametrization interface is lifted up in the hierarchy to a hierarchical level that is not access restricted.

Mapped parameters can be referenced themselves. Thus, you can reference either the content of parameter Value (or Field) in a reference operator, or reference the parameter you have defined in the parameters DisplayName and DisplayHierarchy of the reference operator. This is especially important when protected hierarchical boxes are built up out of other protected hierarchical boxes.

In our example, this means you can reference parameter Value in module ReferenceOperatorExample as well as parameter ConnectionToYLengthInModuleBuffer in module ModuleWithConnectedParameter.

Reference to parameter Value of reference operator instance ReferenceOperatorExample:

Reference to parameter ConnectionToYLengthInModuleBuffer of module ModuleWithConnectedParameter:

[Tip] Don't Create Reference Loops

Make sure you don't implement reference loops, like ModuleA.Value referencing ModuleB.Value, and ModuleB.Value referencing ModuleA.Value.

Via the six available reference operators, all data types are provided that can occur as parameter values in protected hierarchical boxes.

************************************************************

The Translation Operators

The translation operators of the parameters library allow translated access to parameters of one or several other operators.

For calculation, you define formulas. The syntax for these formulas complies to GenICam API version 2.0 and is described below.

Read Action:

In parameter ReadAction, you define what happens for a read access to parameter Value of the translation operator.

One of the main differences to the reference operators is that translation operators don't simply hold a value. Instead, the value of parameter Value is calculated out of a formula. This formula you define in parameter ReadAction.

As soon as there happens a read access to parameter Value, the formula you defined in ReadAction is carried out and the result is forwarded to the element asking for the value.

The formula can contain values of operator parameters anywhere in the design. As soon as one of these values changes, the calculation of translation operator's parameter Value will end up with a new result (different to the value parameter Value held before).

The formula can not only incorporate the values of parameters, but also specific properties of parameters, such as minimal value, maximal value, step size, or the numerical value of enumeration items.

Write Action

In parameter WriteAction, you define what happens during a write access to parameter Value of the translation operator.

In contrast to the reference operators you do not simply forward the value of parameter Value to another parameter in the design. Instead, the value of parameter Value is used for a set of write actions you define in parameter WriteAction of the translation operator. Write actions are composed of one or several equations. With the left side of these equations you define which parameter of which operator receives the result of the calculation. If you define more than one equation separate the equations via semicolon.

As soon as the there happens a write access to parameter Value, the formula(s) on the right side of the equations you defined in parameter WriteAction is/are carried out and the result(s) is/are forwarded to the parameters specified on the left side of the equations.

The formula can refer to values of operator parameters anywhere in the design. As soon as one of these values changes, the calculation results will differ when you re-write the same value as before to the Value parameter.

The formula can not only incorporate the values of parameters, but also specific properties of parameters, such as minimal value, maximal value, step size, or the numerical value of enumeration items.

Data Types:

The operator you select defines the data type of its parameter Value, i.e.:

Operator IntParamTranslator -> integer value

Operator FloatParamTranslator -> float integer value

Operator EnumParamTranslator -> value of an enumeration

However, although the operator defines the type of its parameter Value, it does not restrict the data types of the parameters which are accessed during the write or read operations. For example, operator IntParamTranslator defines that its parameter Value is of type integer; but the formulas defined in the operator can contain access to, e.g., parameters of type double.

Formulas for Calculation of Value Range

You can also add formulas to calculate the current value range of parameter Value. You define the according formulas in the parameters RangeFrom, RangeTo, and RangeIncrement (step size).

The formulas can contain values of module parameters anywhere in the design, as well as specific properties of these parameters, such as minimal value, maximal value, step size, or the numerical value of enumeration items.

[Tip] Syntax for Translation Operator Parameters

The syntax complies to the GenICam API standard in version 2.0. The allowed formula elements are identical to the formula elements defined in the GenICam standard. Find an explicite description in the individual documentation on operators FloatParamTranslator and IntParamTranslator.

Paths to Parameters

To access an operator parameter any place within your design, you need to provide the path to this parameter in your formula.

For access to an operator's parameter, you use the following construct:

"PathToModule": Here, you define the relative path to the operator who's parameter you want to access. The path is relative to the hierarchical level the translation operator itself is located. You also define the name of the accessed operator. Use a slash as hierarchy separator.

"Module": Name of module.

As name for the translation operator instance itself you use the name "this".

[Important] Keep your Modules Independent

It is not allowed to define a path towards a hierarchical level higher than the hierarchical level the translation operator is located. This rule follows the logic that a hierarchical module is not allowed to know anything about the environment it is instantiated in, because only in this case it can be used as a freely relocatable and replicable module.

Access to Parameter Properties

The formulas can not only incorporate the values of parameters, but also specific properties of parameters, such as minimal value, maximal value, or step size:

  • ${PathToModule/Module.ParamName.From} or ${PathToModule/Module.ParamName.Min}: minimal valid value of parameter PathToModule/Module.ParamName.
  • ${PathToModule/Module.ParamName.To} or ${ PathToModule/Module.ParamName.Max}: maximum valid value of parameter PathToModule/Module.ParamName.
  • ${PathToModule/Module.ParamName.Inc}: Increment (step size) between two valid values of parameter PathToModule/Module.ParamName.
  • ${PathToModule/Module.ParamName.Enum("EnumName")}: Integer value of enumeration name EnumName.

Syntax for Write Access Formulas

Equations for write actions you define in parameter WriteAction. They have the following syntax:

Here, you can define multiple equations for multiple target parameters. Use a semicolon as separator between the individual equations.

"this" refers to the translation operator instance itself.

Example for a WriteAction Equation:

Example:

Syntax for Read Access Equations

Equations for read actions you define in parameter ReadAction. They have the following syntax:

Example for a ReadAction equation:

The following list summarizes all Operators of Library Parameters

Operator Name Short Description available since
EnumParamReference

Generates map parameter out of a module parameter that is of data type VA_ENUM.

Version 3.0.1
EnumParamTranslator

Generates translated map parameter of type VA_ENUM. Uses parameter of type VA_ENUM to create multiple translated map parameters in other modules.

Version 3.0.1
EnumVariable

Generates a software variable.

Version 3.1
FloatFieldParamReference

Generates a map parameter out of a reference parameter of type VA_DOUBLEFIELD.

Version 3.0.1
FloatParamReference

Generates a map parameter out of a reference parameter of type VA_DOUBLE.

Version 3.0.1
FloatParamTranslator

Generates translated map parameter of type VA_DOUBLE. Uses parameter of type VA_DOUBLE to create multiple translated map parameters in other modules.

Version 3.0.1
FloatVariable

Generates a software variable.

Version 3.1
IntFieldParamReference

Generates a map parameter out of a reference parameter of type VA_SINTFIELD or VA_UINTFIELD.

Version 3.0.1
IntParamReference

Generates an Int64 map parameter out of a reference parameter of type VA_SINT, VA_UINT, or VA_ENUM.

Version 3.0.1
IntParamTranslator

Generates translated map parameter of type VA_SINT. Uses parameter of type VA_SINT to create multiple translated map parameters in other modules.

Version 3.0.1
IntVariable

Generates a software variable.

Version 3.1
LinkProperties

Allows access to properties of connected link.

Version 3.0.1
StringParamReference

Generates a map parameter (string) out of a reference parameter of type VA_STRING, VA_FILENAME, or VA_METADATA.

Version 3.0.1

Table 35. Operators of Library Parameters