|
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.
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
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:
|
|