This library contains common macros that allow a variety of logic operations to be performed. They also allow logic components to be easily combined using the visual network editor. The normal alternative to this would be to write specific procedural code.
It should be noted that these macros are not intended for the expression of essential application logic. If they were used in this way the system performance is unlikely to be acceptable. The macros are instead intended to help write small control routines and avoid the necessity of developing program code for these. Examples of these control routines include controlling the operation of a user interface and disconnecting certain areas of the network when they are not needed.
The logical terms, TRUE and FALSE, have the same meaning in this library as they do in the C programming language. A value is defined to be TRUE if it is not zero. Conversely a value is defined to be FALSE if it is zero. These conventions are used throughout this library.
Before the individual macros are examined the specific meaning of a 'trigger' should be noted. When the value of a network component is updated AVS/Express sends a signal to all the components linked to it indicating that it has been updated. This is called a trigger signal. A trigger is sent whenever a value is updated with either a different value or the same value. Normally the trigger signal is used to notify other modules that new data is available. However it can be used to simply signify that something has happened. This is now the parse_v module uses its trigger input. Whenever a signal is recieved on the trigger input the parse_v module processes the supplied v code.
Most of the macros in this library generate trigger outputs by examining certain inputs and determining whether a criteria is TRUE or FALSE. These outputs can be used to trigger several modules. These include parse_v, copy_on_change, BreakableLink, ToggleableLink and several of the Database macros.
There are a range of macros in the LogicWidgets library that all begin with the If phrase. All of these macros implement forms of the programming structure if...then...else. The purpose of this structure is to test a certain criteria to determine if it is true or false and perform one of two actions depending on this. These macros implement this structure through the use of triggers. If the criteria is TRUE then the true output is triggered else the false output is triggered.
The If... macros can be separated into two catergories; those with a single logic input and those with two logic inputs. The macros with a single logic input provide general logical behaviour, whilst those with two logic inputs provide higher level and more specific behaviour.
The IfTrue macro is the simplest of the If... macros. It is a wrapper around the TrueFalseCore module and does not provide any extra functionality. It tests the input value and triggers the appropriate output. Therefore the true output is triggered if the input is non-zero and the false output is triggered if it is zero. This behaviour is of limited use itself. However more complex logical statements can be expressed by using the v-code logical and arithmetic operators. A statement such as this can be used as the input to the IfTrue macro. AVS/Express evaluates the statement to a single value which is them tested by the IfTrue macro.
A similar approach of using v-code statements combined with the low-level TrueFalseCore module is used in all the others If... macros. The most basic of these enhancements is the IfFalse macro. This provides the inverse behaviour of the IfTrue macro. If the input value is FALSE the true output is triggered. Otherwise the input value is TRUE and the false output is triggered.
All of the above macros have two logical inputs. The macros perform a wide variety of different tests on the inputs. The simplest of these tests is implemented by the IfEqualTo macro. This macro tests if the input numbers are numerically equal. If they are the true output is triggered, otherwise the false output is triggered. All the other macros derive from the IfEqualTo macro and alter it to provide a variety of different tests. The exact definition of these tests is shown in the table below.
&trigger
This integer parameter is a trigger input that is present on the IfTrue and IfFalse macros. When this parameter is triggered the value on the input of the module is evaluated and the appropriate outputs triggered. Changing the input itself also causes the input to be evaluated. However it is possible to cause the module to retrigger without altering its state by using this input. An example of its use can be seen in the Toggle macro. This trigger input is also available on the other macros however it is not directly exposed as an input.
&in &in1 &in2
These integer parameter are the input parameters to the If... macros. The IfTrue and IfFalse macros use the single input in, whilst the two inputs macros use the inputs in1 and in2. These inputs are evaluated by the macros to determine which output should be triggered.
cond
This integer parameter is used to output the evaluated state of the input. In logical terms this parameter will have the same value as the input criteria. However it is restricted to a true binary representation of 0 and 1 only. Therefore if the input criteria is TRUE a 1 is output, otherwise a 0 is output. This parameter is triggered whenever the input is changed.
cond_true
This integer parameter is triggered whenever the input condition evaluates to TRUE. The actual value of this parameter is not significant and it should not be accessed.
state_false
This integer parameter is triggered whenever the the input condition evaluates to FALSE. The actual value of this parameter is not significant and it should not be accessed.
This table is intended to describe exactly how these macros will behave in logical terms. It uses the same logic operators as the v language uses.
| Macro Name | ||
| IfTrue | ||
| IfFalse | ||
| IfEqualTo | ||
| IfNotEqualTo | ||
| IfLessThan | ||
| IfGreaterThan | ||
| IfLessThanEqual | ||
| IfGreaterThanEqual | ||
| IfLogicalAND | ||
| IfLogicalOR | ||
| IfBitwiseAND | ||
| IfBitwiseOR |
This macro stores a value that can be toggled between TRUE and FALSE through the use of a single trigger input. Whenever a trigger is received on the macro input the state of the stored value is tested. If the stored value is TRUE then the stored value is set to 0, and therefore FALSE. Conversely if the stored value is FALSE then the stored value is set to 1, and therefore TRUE. The macro also has trigger outputs. The Toggle macro can be used for a variety of tasks, in particular it should be useful for storing the results of a trigger output.
&trigger
This integer trigger parameter is used to toggle the state of the stored value. Whenever this parameter is triggered the stored value is changed from 0 to 1 or from 1 to 0 as appropriate.
out
The state of the toggle.
not_out
The inverse of the state of the toggle.
value_true
This integer parameter is triggered whenever the toggle state is changed from 0 to 1. The actual value of this parameter is not significant and it should not be accessed.
value_false
This integer parameter is triggered whenever the toggle state is changed from 1 to 0. The actual value of this parameter is not significant and it should not be accessed.
This macro stores a value that can be switched between TRUE and FALSE throught the use of two trigger inputs. Whenever a trigger is received on the on macro input the state of the stored value is switched to TRUE. Conversely whenever a trigger is received on the off macro input the state of the stored value is switched to FALSE.
&on
This integer trigger parameter is used to switch the state of the stored value to TRUE.
&off
This integer trigger parameter is used to switch the state of the stored value to FALSE.
out
The state of the switch.
The parse_v_on... range of macros all allow v code statements to be executed whenever a set criteria is TRUE. They combine the standard parse_v module with the TrueFalseCore module. The TrueFalseCore module tests the supplied values to determine if they meet the set criteria. If they do the TrueFalseCore module triggers the parse_v module to process the set v code statements. The parse_v module can be used in exactly the way that it is used normally.
As with the If... macros the parse_v_on... macros can be spilt into two catergories; single and double input macros. Boardly the logical criteria of each of the parse_v_on... macros corresponds with the respective If... macros. However the parse_v_on... macros do not implement as many criteria as the If... macros. This is not a limitation of the system. The extra macros are not present so that the number of macros in the LogicWidgets library could be keep to an acceptable number. If the extra criteria are required the parse_v_on_equal macro can be easily used as the basis of the new macro. This was done to generate all the other two input macros.
&in &in1 &in2
These integer parameter are the input parameters to the parse_v_on... macros. The parse_v_on_true and parse_v_on_false macros use the single input in, whilst the two inputs macros use the inputs in1 and in2. These inputs are evaluated by the macros to determine whether the parse_v module should be triggered.
v_commands active on_inst relative
These parameters are all used by the standard parse_v module. The v_commands parameter is a string value that allows the v code that should be processed to be stored. The other parameters control the way the parse_v module works. For full details please see the parse_v documentation.
(none)
This table is intended to describe exactly how these macros will behave in logical terms. It uses the same logic operators as the v language uses.
| Macro Name | |
| parse_v_on_true | |
| parse_v_on_false | |
| parse_v_on_equal | |
| parse_v_on_not_equal | |
| parse_v_on_less_than | |
| parse_v_on_greater_than |
iac_proj/common/lg_wdgts.v contains the V definitions of the If..., Toggle, Switch and parse_v_on... macros.
The LogicWidgets library inherits its process. As this library contains no procedural code, the process is not important. The CommonMods library contains all procedural code used by the Common project and should be compiled.
Andrew Dodd, Various
International AVS Centre Manchester Visualization Centre Manchester Computing University of Manchester Oxford Road Manchester United Kingdom M13 9PL