Triggers an Action if the Trigger input signal becomes around or above 1.0, and sends the captured sample value to the specified address.

Capture Action

Overview

This operator uses an Action ("Actions - Overview") to send the currently captured value to another object in the project. The Action is generated if the Trigger input changes its state from 0 to 1. Read more about triggers here: "Pseudo-booleans and triggers".

Use this operator to change the mathematical behavior of other operators, based on signal conditions.

See also the Constant to Action operator ("Constant To Action") as an alternative.

Operator ports

Input S: Floating point values

Input Trigger: Floating point values

Output S: Floating point values

Properties

Find more information about changing properties here: "Properties Viewer"

Action

type: Select from the list
Select the code of the Action that is performed when the input value is greater or equal to 1.0.

Select one of those presets:

Value

type: See description [this value cannot be changed]
The value to set at the Address is determined automatically

Address

type: Address, starts with '$' sign (see "Address - how to address objects and variable parameters")
Fill in the address of the object that should receive the Action.

You may type or paste the address, or you may press the small button on the right to open the Address Constructor ("Address Constructor")

AutoExtendAddress

type: True or False
Set to True if the Address should be extended by the channel name that triggered the Action.

Select one of those presets:
True or False
True may also be read like 'yes' and false like 'no'

The address is extended intelligently. For example, if the address is $Design.Input Field.Text$, then the channel name is added to Design.Input Field and not to Text. If a signal channel is called '10', then the address that is used becomes $Design.Input Field10.Text$. AutoExtendAddress also works for global variables, for example $MyVar$ could become $MyVar10$.

Caption

type: Word or phrase
The name of the object in the project. This name must not contain '.', '$' nor '@' characters.

For more information about the rules and usage of the Caption property, please refer to "Caption property - background and usage".

Documentation

type: See description
Optional documentation of this object. If this object is an operator, the Documentation text is displayed below the operator symbol.

Details

General working

Place this operator in between a signal connection. The signals at the input are copied unchanged to the output, also independent of signals at the Trigger input. A trigger at the trigger input will only take the sample that is currently flowing through the Capture Action, and send its value via an Action.

If the trigger input has 1 channel, then the trigger on that channel will cause the specified Action to be performed for every signal channel. So, if the signal input has 4 channels, then a trigger will cause four actions to be performed.
If the trigger input has the same number of channels than the signal input has, then each trigger channel causes its own Action to be performed on the captured value of the signal channel with the same index.

AutoExtendAddress mode

If the input has multiple channels, then the Action of this operator is repeated for each channel. In some cases it makes sense that the action address is changed somewhat for each channel, for example to set a different variable for each channel.

If you use the AutoExtendAddress property, it is possible to change the specified action address by extending it with the channel name. The way the address is extended, depends on the action.
In case of SET_PARAMETER and FUNCTION, the fore-last part if the address is extended. For example, if a channel is called C1:

SET_PARAMETER $Design.Constant.Value$ becomes: SET_PARAMETER $Design.ConstantC1.Value$
FUNCTION $Design.Device X_.Enable$ becomes: FUNCTION $Design.Device X_C1.Enable$
however:
SET_PARAMETER $var$ becomes: SET_PARAMETER $varC1$

In case of other actions, the channel name is just extended behind the specified action address. For example for channel C1:

SHOWPAGE $Page_ becomes: SHOWPAGE $Page_C1
ACTIONSEQUENCE $Design.My Action Start $ becomes: ACTIONSEQUENCE $Design.My Action Start C1$

Note: You may use a Channel Terminal ("Channel Terminal") to deliberately change channel names.

Behaviour if address points to a variable parameter list

If the action address refers to a variable parameter list ("Parameter List"), then an automatic address extension, based on the index of a channel is applied. It is tried to set the action value to individual values in the list that have the same order index the channel has. For example:

SET_PARAMETER $Design.Prepare Ranges and Offsets.Offsets$ for the first three channels becomes:
SET_PARAMETER $Design.Prepare Ranges and Offsets.Offsets.0$
SET_PARAMETER $Design.Prepare Ranges and Offsets.Offsets.1$
SET_PARAMETER $Design.Prepare Ranges and Offsets.Offsets.2$

In this case, the AutoExtendAddress property is ignored.
Note: this behaviour was added in Polybench 1.34; in older versions, lists cannot be addressed

Examples

Example: Capture Action with AutoExtendAddress Demo

Demonstrates the Capture Action that reads values from 3 signal channels. If the Constant Button is pressed, this triggers the Capture Action. It then issues 3 SET_PARAMETER actions - for each channel one.

Another feature that is demonstrated here is the AutoExtendAddress. The address of the SET_PARAMETER action is extended by the channel name for which the action is issued. For example, the second channel is called '2'. The second Input Field is called 'Input Field2'. The action address in the Capture Action is 'Input Field.Text' - so without a number. The AutoExtendAddress feature now takes care that channel name '2' is added to the address name 'Input Field', resulting in 'Input Field2'.
Examples\DF0411125_001_Capture_Action_and_AutoExtendAddress_Demo.xmc

Example: Capture Action to switch visibility of channels (Demo)

Demonstrates the Capture Action in combination with a parameter list.
Press 'on' or 'off' to set individual channels to 1 or 0. Then press 'Set OFF channels invisible' to trigger the Capture Action. Because the address points to a list (Prepare Signal Graphics.Visibility), the input values are automatically copied to the corresponding items in the list.
(Note: this works in Polybench 1.34 and higher only)
Examples\DF0411125_002_Capture_Action_to_switch_visibility_of_channels.xmc