Functions
| Site: | QSC |
| Course: | Q-SYS Control 101 Training |
| Book: | Functions |
| Printed by: | Guest user |
| Date: | Thursday, 16 May 2024, 8:26 AM |
Description
Lesson Description
Create repeatable functions, and then execute those functions with varying parameters in both Lua and the Block Controller.
Video Transcript
0:08
In scripting, a function is an action or series of actions that is initiated by a particular stimulus. Other
0:15
coding languages might call this a procedure, or a subroutine. So far everything that we’ve scripted
0:21
has happened automatically as soon as we run the script, but a function is an action that you define
0:26
in the script, and then you can execute that function whenever and however you like.
0:32
There are five pieces to the construction of a function in Lua. First you enter the word function, then
0:39
if you like you can provide a name for the function.
0:42
If you give your function a name, that lets you quickly recall the same process over and over again
0:47
from multiple places, rather than rewriting it every time you want to perform it.
0:52
Next, within a set of parentheses you include any arguments that you want to pass into the function.
0:58
You could consider an argument to be like a local variable – it’s a thing that’s going to be used within
1:04
the function.
1:05
Next we write the body of the function, which is the list of actions you want the function to perform,
1:11
and finally you close off the function with the word end.
1:16
Here we have a very simple function named “f” which has two arguments – x and y. Within the body
1:23
of this function we are printing the result of x plus y. The word end completes the function. Now we
1:30
can launch this function simply by entering its name, and including the arguments we want to pass
1:35
into it in our parentheses. For instance if I enter “f(1,2)” then it will print the result of “3.” Note that
1:43
the function is expecting two arguments in this case, so it will return an error if I recall the function
1:49
without all the information it needs. Or if I were to add a third argument here, it won’t do anything
1:56
with that information because this function has no instructions to do anything with a third argument.
2:00
If this looks familiar, it’s because you’ve already been using a named function called … print. The
2:07
print command is a function, and whatever you put in its single argument, in the parenthesis, is the
2:13
information that this function sends to the Debug Window.
2:18
When you get into some more advanced functions, you may discover times when you don’t know
2:23
how many arguments you want to pass in. In this case you could use “…” in lieu of the arguments,
2:29
which tells the function to adapt to as many arguments as are provided. On the other hand, if your
2:35
function requires no arguments at all, you still need the open- and closed-parentheses to complete
2:41
the structure of the function, but there will simply be nothing in between them.
2:45
For instance, let’s look at a couple of other simple functions.
2:48
Here’s a function called “goblue”, with no arguments. The body of the function simply changes a
2:54
particular control’s .Color parameter to “blue,” and then it ends. Since this function only does one
3:01
thing, with no variables, we don’t need any information in our argument parentheses.
3:06
Here, let’s make a simple mathematical function called “plus5.” It will include one argument, A. We’ll
3:13
use this function to add 5 to the value of a control. So the body of the function would look like this:
3:20
we will take the incoming A.Value and redefine it as it’s current state plus 5. And just for good
3:28
measure let’s print the new A.Value before we end it. Now we could execute that function and enter
3:35
any control we like as the argument, and that control will have 5 added to its Value.
3:41
You could also add a return command within the body of your function, which will output whatever
3:48
information you specify at the conclusion of the function. For instance, looking back at our first
3:53
function, rather than include a print statement in my function, I’m going to define local variable M as
3:59
our “X+Y” Now I can’t print “m” because that’s a local variable, so my print command can’t access it.
4:08
But if I add the phrase “return m” at the end of our function, then this basically tells our function to
4:15
spit this answer back out. So now I can choose to print the function itself (print (f(1,2)), which returns
4:25
m, which is sent to my debug window.
4:28
One last thing while we're here on the Lua side, you may have noticed this little icon to the left of
4:33
your function. If you click it, the entire structure of function will collapse to a single line of code so
4:39
that it's not cluttering up the rest of your screen. You can always expand it again to keep on editing it,
4:44
or you can collapse it again just to make it a little bit easier to read.
4:48
In the Block Controller, you can define a function by going to the Variables & Functions section. Here
4:54
you’ll see two “define function” blocks, in which one has a “return” option and the other does not.
5:01
So, if you wanted this function to return information you could add that variable at this point,
5:07
whereas this function has a point of no return. JOKES! Alright, let's give a name to our function, and if
5:17
you want to include arguments passed into this function, you can click on the cog icon and add
5:22
“inputs” to the body of this block. Here I’ll add two arguments, and if I wanted this function to print
5:28
their sum, I could go to the System section and grab a Debug Print command, then go to the Operators
5:35
section and grab a mathematical addition block. I can pull the arguments right out of the top of this
5:41
function block to add them to its body. Just hover your mouse over the argument and the blocks
5:46
related to it are revealed. I’ll drag x and x1 into my arithmetic block. Now to launch this function, I can
5:54
find it as an available function in my Variables and Functions list. I simply need to populate the two
6:00
two arguments with actual information, and then when my Block Controller script runs it will run
6:06
the function. As always, I encourage you to look at the Lua generated by these blocks to reinforce
6:12
your learning of script. You can see that the function is built the same way we just learned, and it is
6:18
then executed using the two values we input into the arguments sections.
6:24
In the next section we’ll talk about creating the conditions for which a function like this could be
6:29
executed. But first, we have some exercises on functions for you to perform in the Control
6:34
Worksheet. Once you’re done, move on to the next video.