Joe Maller: Joe's Debug and Explore Filters: Joe's Simple Fill

There are two ways to think about how this filter will work. At it's most basic, the filter will fill the source clip with a percentage of color. However, I prefer to think about filters as if I were going to build the effect manually in Photoshop:

The filter will create a layer of color. That layer of color will be composited onto the source clip at the specified opacity.

Understanding how to build these with existing tools will help to bridge the gap between understood image processes and abstracted programmatic image processes.

Declarations

Every FXScript begins with a few definitions. These tell Final Cut Pro about what kind of FXScript this is and where it should go in the menus.

filter "Joe's Simple Fill"
group "Joe's Debug and Explore Filters";

The first line sets both the type of script, in this case a filter, and the name of the script, "Joe's Simple Fill".

Inputs

FXScript provides many kinds of inputs, this filter uses a color selector to choose the fill color and a slider to set the opacity.

input fillcolor, "Color", color, 30, 255, 255, 127;
input opacity, "Opacity", slider, 100, 0, 100;
input title, "www.joemaller.com", Label,"";

The first line creates a color selector with a default yellowish color. The first number after color is the Alpha value (ignored by the visual color picker), the second is Red, third Green and fourth Blue. The selected color is stored in the fillcolor variable.

Opacity uses a simple slider from 0 to 100. The default setting is 100.

The last line, title, is a label. These don't affect the script except to display text for people using the filter. Each label input in a script needs a unique name.

Code

This is the most important line in every FXScript:

code

That line divides the filter between the inputs which are set globally, and the actual processing which processes every frame of a clip.

Compositing and Output

Below the code comes the actual processes which execute the filter. Thinking like Photoshop again, this uses the dest channel as an extra layer and fills it with color. This color "layer" is then applied onto the source image.

ChannelFill(dest, 255, fillcolor.r, fillcolor.g, fillcolor.b);

ChannelFill can fill all the channels or none of the channels. This function applies a completely opaque copy of fillcolor into the output image buffer dest. The alpha channel is set to 255 (completely white and opaque), then the three color components from fillcolor (fillcolor.r, fillcolor.g, fillcolor.b) are used to specify the value for each color channel.

If the filter was to stop at this point it's effect would be to completely fill the source clip with the selected color. Whatever is left in the dest image buffer at the end of a script is what will display in Final Cut Pro.

Matte(dest, src1, dest, opacity/100, kalpha);

Matte is a simple compositing funtion similar to using layer opacity in Photoshop. The image buffer dest, which was just filled with color, is applied onto the source image, src1. Opacity needs to be a number between zero and one, so the value of the opacity slider is divided by 100. The resulting image is placed back into the dest image buffer.

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.

Note

The source code above is slightly different from the source code included in the Joe's Filters download. The code above removes three commented lines which were leftover from an earlier version of the filter. Because those lines are just comments (preceded by two slash characters "//") both versions function identically. In the earlier version, the filter created an additional image buffer for ChannelFill instead of using dest.