Joe Maller: Joe's Debug and Explore Filters: Joe's Multi-Value Tester

A reporting filter for Final Cut Pro to help understand FXScript values.

This is a catch-all filter which I created to see the values of many FXScript Constants. This helped me understand quite a lot about how FXScript works. Included values: Ratio, Duration, Frame, Fps, Pixel Format, Aspect Ratio, RenderRes, ZoomFactor, "Corrected Duration, Width and Height.

About the Included Values

This is the list of values revealed by the Multi-Value Tester. More information about constants can be found on the FXScript Constants page.
  • ratio, duration, frame, fps, RenderRes

    These constants are all discussed on the FXScript Constants page.

  • GetPixelFormat(dest)

    This is the Color Space setting, it will return a number 1,2 or 3. These correspond to RGB255, RGB219 and YUV. The FXScript RGB and YUV Color page has more information about working with YUV and RGB color. Joe's PixelFormat Tester can also help to better understand how to work with different color spaces.

  • aspectof(dest)

    This value changes depending on the desktop display settings. Interlaced NTSC video returns an aspect of 2.2 on the output monitor.

  • width/720 [zoomfactor]

    Zoomfactor is something I came up with to help scale effects on the desktop. Since DV video is 720 pixels wide for NTSC and PAL (even 16x9), dividing the width by 720 will result in a decimal value usually between 0 and 1 (or higher for +100%). Multiplying any value by this amount will scale equal to the zoom amount.

  • duration/integer(aspectof(dest)) [corrected duration]

    This was briefly mentioned on the FXScript Functions page, it corrects duration to match between the desktop and video output. Final Cut Pro counts fields when figuring the duration of interlaced video, so the duration on the video output will always be double the desktop display. I bumped into this while trying to time the text fade up of Joe's Text Bugger to the last second of a clip. It would be easier if Final Cut Pro had changed fps to reflect fields since the frame constant counts to 60 on video output.

  • dest height and dest Width

    Height is considered per field of interlaced video, and returns half of the total height of the overall frame. To correct for this, height values can be multiplied by integer(aspectof(dest))to double interlaced values and get a correct vertical measurement. Some functions need this, others don't.

How It Works

There isn't much to this filter, it uses a subroutine to reuse the same string conversion lines, but it doesn't have to. Subroutines seem to need to be declared at the beginning of an FXScript document to work, so this one comes immediately after code. Final Cut Pro seems to interpret things in a linear way, this order makes sure the script knows the subroutine exists. Remember that line breaks are important, please refer to the actual source code for accurate line breaks.

Three values are passed into the subroutine: reporterDate, reporterstring and subformat. I used variable names specific to the subroutine for clarity. The variables are location specific, so data sent to the subroutine will be interpreted in the order the variables were declared. I separated the subroutine from the script with commented lines beginning with //, just to make the code easier to look at.

All values in FXScript seem to exist as numbers, even if we see them mostly as names. What really matters is the context of the value. Anyway, the main values are parsed into strings by the NumToString() function, which translates numerical values into string values using the specified format, in this case the format passed with the subformat variable.


//numreporter subroutine
  On numReporter(value reporterData, string reporterstring, value subformat)
    string reporter;
    point rect[4];
    color fontcolor;
    fontcolor = {255,235,235,235};
    setTextSize(28 * zoomfactor);
    ChannelFill(xbuffer, 0, 0, 0, 0)
    reporter = reporterstring + " = " + reporter
    DrawStringPlain(reporter, rect, dest, fontcolor , aspectof(dest))
//end numreporter

In other scripts I switched from the DrawStringPlain() function because I found the rectagle spacial target confusing. Someday I might redo this one, but I sort of wanted to finish someday and decided to leave it since it was working fine.

float zoomfactor, w, h;
dimensionsOf(Dest, w, h);
image xbuffer[w][h];
zoomfactor = w/720

First the floating point variables zoomfactor, w and h are declared, then w and h are assigned the dimensions of dest, the xbuffer image buffer is declared and then Zoomfactor is assigned. Zoomfactor is my little hack for determining the amount of zoom the image is currently viewing at. It makes it easier to match things up between the desktop and the video output image. Try the filter to see what kinds of values it returns.

dest = src1

This is a safety to prevent Final Cut from freaking out because of dest was never assigned anything. Empty buffers cause wackiness. Try removing this line and see what happens.

Next come two sets of if/then statements which determine which value the filter will show. The first one looks like this:

if formatting == 1; formatting = kInteger; end if
if formatting == 2; formatting = kFloat2; end if
if formatting == 3; formatting = kFloat4; end if
if formatting == 4; formatting = kFloat6; end if
if formatting == 5; formatting = k30fps; end if

The second one is a bit messier, check the source code. Each value refers to the position of the element in the popup menu starting with 1.

Source Code

Unlocked versions of this and all of Joe's Debugging and Exploration Filters are included for free with the trial and paid versions of Joe's Filters. Or use the source code below to build your own.

(copy and paste the code into FXBuilder)
page last modified: