Joe Maller: FXScript Reference: Constants & Preset Variables

Descriptions of FXScript constants for filters and transitions in Final Cut Pro.

Constants are sort of like variables but constants are always available and can be accessed from anywhere in a script. Preset Variables are similar to constants since they do not need to be defined beforehand like regular variables.

Constants are defined in the Manual, these are my additional notes:

General Constants

These constants appear

  • kUndefined

    The manual says this is what all static variables are initially defined as. I've looked around for this, but never found a way to show it.

  • kAlpha

    Represents the Alpha channel, which controls transparency.

  • kRed, kGreen, kBlue, kBlack, kWhite, kGray, kCyan, kMagenta, kYellow

    These represent color channels, or mixes of color channels. Pixel values can be assigned or transferred by referencing these constants.

  • True, False

    These are referred to as Boolean values. True can also be represented as 1 and False as 0.

Preset Variables

Like most scripting languages, FXScript has a large set of pre-defined variables that can be used in scripts.

  • src1, src2, dest

    These are image buffers, src1 is the main clip or incoming clip for transitions. src2 is the outgoing clip in transitions and doesn't do anything in generators or filters. dest is the output frame, this is what will display when the filter is run.

  • srcType1, srcType2

    These report the current alpha type of the contents of src1 or src2. I've only used them to get the current Alpha type when a function asks for an alpha type. This can be used intead of the constants kAlpha, kBlack and kWhite.

  • ratio

    Usually used in transitions, this decimal value between 0 and 1 is the current percent completion of a script. The value is equivalent to dividing the current frame into the total duration of frames. Ratio doesn't seem to work on slugs or color mattes, but does work on still images. Ratio will never actually equal 1 although the last frame will be very, very close to 1. I belive that ratio is simply frame/duration. Because frame counts from 0 and duration counts whole units (starting a 1) frame will always end slightly less than duration and ratio will never equal 1.

  • frame

    Returns the current frame number. If the source is interlaced abd tge filter does not contain a FullFrame definition flag, the frame value on external monitors will be double that visible in Final Cut Pro's viewer.

    The first frame is counted as zero, so the last frame is always one less than the amount reported by duration.

  • duration

    This counts the total number of visible frames in a specific instance of a clip. Because whole numbers start counting at 1, duration will always return a number 1 greater than the last frame number of a clip.

    Multiplying this value by the ratio will return the same value as frame. One strange behavior to note is that interlaced DV returns different numbers in Final Cut's viewer and the video monitor. FCPs viewer is counting frames, the video ouput is counting fields (which are really half-height frames). This can be avoided by dividing by the integer value of the aspect ratio + 0.5 (to correct for PAL). The problem does not affect non-interlaced clips or scripts that include the FullFrame definition flag.

  • fps

    Returns the framerate of the clip or sequence. Since I've only been working with DV, I only get a frame rate of 30 and I'm not sure if that is the sequence or the project. Using fps is preferable of a hard-coding in a value like 30 because it makes the script more portable, allowing it to work on NTSC or PAL or any multimedia application.

    The major bummer about the fps constant is that there is n oFXScript command to tell if a clip is interlaced or not. fps always reports 30 on NTSC video, but judging by the performance of frame and duration, fps should return 60 on external monitors from non-FullFrame scripts, to match the behavior of the other clip constants. I think this might be related to the behavior of the clip functions GetVideo and GetLimits.

  • RGBtoYUV, YUVtoRGB

    These 3x3 conversion matixes were used for RGB to YUV conversions in Final Cut Pro versions prior to 1.2.5. They have been demoted in favor of the colorspace functions SetPixelFormat and ConvertImage.

  • RenderRes

    This value represents the current sequence quality. It's used in a lot of included scripts, but I haven't used it since I really never work at anything other than the default render quality. This would be better if it described the currect zoom amount

  • LinearRamp

    This is used frequently with the LevelMap() function, it is a placeholder array that allows values to pass through LevelMap unchanged.

    The Final Cut Pro manual wrongly states that this constant contains values from 0 to 255. LinearRamp actually contains 256 fractional values between 0 and 1. This can be proven with Joe's LinearRamp Tester, which I wrote to help visualize the results of this and other arrays.

  • Previewing

    This can be used to separate the video monitor display from the desktop. Anytime an FXScript shows additional information on the desktop and not on the video output, the script probably used Previewing in an if statement.

    Items can be sent only to the desktop with a statement like:

    if previewing;
         do something;
    end if

    Whenever previewing is false, the results are output to both the video monitor and the desktop.

Variables not covered: clip1, clip2 and exposedBackground.

Undocumented

As far as I can tell, this do not appear in the manual, however it was used in several of the built-in scripts.

  • kNone

    This is a useful null variable which can be used in processes where no change is desired. For example in the ChannelFill() Function, using kNone will result in no change to a channel's original value. See Joe's Noise for an example of ChannelFill() with the kNone variable.

Number Formatting

These constants are used to format the output of numbers into different schemes.

  • kInteger

    Standard format, integer are whole numbers without decimal values. Values are not rounded to the nearest whole number, decimal values are simplydiscarded.

  • kFloat2, kFloat4, kFloat6

    These refer to floating point variables that aren't really floating point variables. A floating point number simply means there is no fixed number of digits on the right side of the decimal point, but these formatting schemes specify a specific amount of digits shown to the right of the decimal place. Using kFloat4, 2/3 is represented as 0.6667

  • k24fps, k25fps, k30fps, k30df, k16mm, k35mm

    These will format solid numbers into timecode by counting the number of frames. So the number 100 would format as 00;00;03;10. I didn't use these so I'm not sure how addition and subtraction would work, but I imagine timecode values would be treated similar to whole numbers.

Text Constants

These are places to store common text attributes. The setting stored here will be usd by any DrawString commands until they are reset or changed again.

  • kleftjustify, krightjustify, kcenterjustify

    These do just what you would expect them too. They represent the three possible text justification methods available in Final Cut Pro.

  • kplain, kbold, kitalic, kbolditalic

    Same as above, these represent the four possible text styles available in Final Cut Pro.

Shape Constants

  • kRound, kSquare, kDiamond

    These are pretty self-explanatory. I used them with the DrawSoftDot function in Joe's Pixelizer.

Keying Constants

Even though I used a keying command in Joe's Color Glow, I didn't use any of the keying constants: kKeyNormal, kKeyAdd, kKeySubtract, kKeyDifference, kKeyMultiply, kKeyScreen, kKeyOverlay, kKeyHardLight, kKeySoftLight, kKeyDarken, kKeyLighten

Color Space Constants

kFormatRGB255, kFormatRGB219, kFormatYUV219
Color Space constants are discussed on the FXScript RGB and YUV Color page.

The headache of fields vs. frames

Final Cut Pro often returns different numbers for the computer screen and the video output. Besides being very confusing while scripting, this results from the video monitor output counting fields while the computer monitor counts frames. This wouldn't be much of an issue if fps reported fields as well, however fps always returns the practical value (I always see 30 on an NTSC system). This issue is explained more completely on the FXScript Functions page.

If you know of anything else that isn't mentioned on this page or can correct any errors, please let me know:

 
page last modified: