Joe Maller: FXScript Reference: VariablesInformation about how FXScript uses variables while scripting Final Cut Pro.
Variables are little chunks of memory where a script can store information. The information in a variable can be changed or replaced when the script is running.
Defining FXScript Variables
Defining variables in FXScript is a two part process. Each variable must first be declared before it can be assigned a value. A simple variable declaration looks like this:
Each type of data also gets it's own type of variable in FXScript. Multiple variables of the same type can be declared together. Declaring multiple variables might look like this:
All six of those still need to have values assigned to them.
FXScript will choke if a script tries to put one type of data into a different type of variable. I didn't have much success moving or converting data between variables, so I try sort out my data types early in the script.
Variables are usually defined in the
FXScript Data Types
The following is a list of FXScript's ten data classifications, followed
by example code for how to define a variable of that type. Each example
shows the variable being defined as
Every color is defined as having four composite values. For RGB colors, the values are alpha, red, green and blue. For YUV, Y (luminance), U (Cb, red to yellow) and V (Cr, blue to yellow). An RGB image can be defined like this:
Once the color is defined, it's composite values can be addressed attaching the color abbreviation to the end of the color's variable name like this:
If the color was YUV, then use
This page contains more information about RGB and YUV Color in FXScript and Final Cut Pro.
FXScript stores video frame data in image buffers.
There are several predefined image buffers in the FXScript language:
Scripts do not automatically display anything without being told to,
so juggling image buffers is essential to seeing any scripted effects.
If a script never assigns any image data to
That will tell FXScript that the contents of
Scripts are not limited to these two or three image buffers. The code to define an additional image buffer looks like this (must appear in the code section of the script):
The first line declare the variables
The newly declared image variable
Most of mathematical operators are very simple or are covered in the manual, but compound operators only get a passing mention. I had never seen these before and wanted to know what they were since they figured prominently into the mathworks I adapted for Joe's Levels.
Basically, compound operators are shorthand for longer statements. Here is a chart of the most common compound operators (
Arrays allow sets of data to be stored in a single variable. Simple arrays are sort of like a list or a stack of drawers. Any type of data can be stored in an array as long as the data-type declaration is correct.
The notation for a floating point array with 4 entries looks like this:
The contents of that array could be assigned like this:
The complete array could also be defined like this:
Other types of arrays could be points, strings or colors, each defined as follows:
Arrays are a bit confusing about how they count. Since computers start counting at zero, the first position in an array is zero instead of one. This makes zero number one, and my head hurt. The term "off-by-one-error" has become tech jargon just to deal with this headache. (You do get used to it eventually, I'm just not sure if I still have ten toes or not.)
These are not nearly as complicated as they sound. A multidimensional array is sort of like two or more stacks of drawers side by side. Think of a two dimensional array as a grid of squares and a three dimensional array as a stack of boxes (beyond three dimensions I run out of metaphors).
The image buffers described earlier on this page are examples of multidimensional arrays, height and width being the two dimensions of the array.
The notation for a multidimensional array looks like this:
That code will create a 3x3 grid named
Another way of showing that is to use curly braces like on the simple array:
The defined constraints of the array will tell FXScript where to "wrap" the data into the next row.
The 3x3 matrix
A multidimensional array is usually called a matrix. In researching these pages, I learned that 3x3 or greater matrixes are at the heart of a great deal of digital image processing. 3x3 matrixes can be adjusted for Hue, Saturation and Brightness changes or convolved to find edges, sharpen or blur images. There is more information, though extremely technical, at these links:
Since I had never really dealt with matrixes (or multidimensional arrays for that matter), I wrote a few little plug-ins to help me to visualize what matrixes look like. These really helped me to understand what was happening inside the matrix (insert spoon joke here).
Arrays can get very large. FXScript commonly uses arrays for images or color lookup tables. A normal 720 x 480 image buffer array contains information on 345,600 elements.
If the command had been