History of <FFP_program>

Parses a Filter Factory Plus (FFP) program.

"Filter Factory Plus" (FFP or FF+) is the extended language and text file format used by FM, and is based on Adobe's original Filter Factory Language (FFL).

In a nutshell, an FFP program is what you enter in the FM Source Code window, and looks very much like a Filter Factory Wizard (FFW) or Plugin Commander (PiCo) source text program. In fact, you can enter an FFW program or a PiCo program (or even an original FF-style *.afs file) directly into the source code window and execute it as-is.

Since the FFDG "publication" format is essentially the same as the PiCo text format, this means you can cut and paste a filter description from the FFDG mailing list directly into the FM Source Code window and run it.

Of course, the FFP program format has many extra features beyond those supported by the FF, FFW, and PiCo formats, but the basic idea is the same: An FFP program consists of an (optional) header line, followed by a list of <key>:<value> pairs, followed by an optional footer line.

== Syntax ==

In brief, the syntax of an FFP Program is:

:<FFP_program> :

:: [%FFP] //optional header

:: { <key> : <value> }* //zero or more <key>:<value> pairs

:: [%%EOF] //optional footer

where the syntax of <value> depends on the <key>. The various possible <key>:<value> pairs are described in the following sections.

(As a deprecated feature, FM also allows an equal sign ("=") to be used as the separator between the <key> and <value> fields; however, "=" should be reserved as the separator between <subkey> and <value> fields in all newly written code.)

Note that the <key> field is case-insensitive, but most other fields are case-sensitive. That is, you can spell the 'Category' <key> as "Category" or "CATEGORY" or "category" or "cAtEgOrY"; but the "setCtlVal" function must be spelled exactly as given. This is particularly important when distinguishing between like-named pairs of variables and pseudo-constants, such as "x" (a variable giving the current x-coordinate) and "X" (a pseudo-constant giving the width of the current image in pixels).

Exceptions: <subkey> names and <color> names are also case-insensitive. As specified in the Syntax topic, case-sensitive names are denoted by double quotes (""), while case-insensitive names are denoted by single quotes ('').

== Example ==

The following is an example of an FFP program file (spazzle1.ffp):

<code>

%FFP //optional header line

/* Filter Information */

Category: "FM Filters"

Title: "Spazzle Demo Number 1"

Author: "Monkey Man"

Copyright: "Freeware"

Description: "This filter creates some wild and zany effects."

/* RGBA Channel Formulas */

R:(b?g*2*ctl(0)/b:g*ctl(0))%256

G:(r?b*2*ctl(1)/r:b*ctl(0))%256

B:(g?r*2*ctl(2)/g:r*ctl(0))%256

A:a

/* User Interface */

Ctl[0]: STANDARD, Text="Razzle", Value=123

Ctl[1]: STANDARD, Text="Dazzle", Value=134

Ctl[2]: STANDARD, Text="Frazzle", Value=255

Ctl[5]: PUSHBUTTON, Text="Scramble!" //our version of the "Randomize" button

Ctl[6]: PUSHBUTTON, Text="Reset" //reset sliders to default values

OnCtl[n]:

{

if (n == 5) {

//if user pushes "Scramble!", set the sliders to random values...

setCtlVal(0,rnd(0,255));

setCtlVal(1,rnd(0,255));

setCtlVal(2,rnd(0,255));

return true; /*override default action*/

}

else if (n == 6) {

//if user pushes "Reset", set sliders back to initial values...

setCtlVal(0,getCtlDefault(0));

setCtlVal(1,getCtlDefault(1));

setCtlVal(2,getCtlDefault(2));

return true; /*override default action*/

}

return false; /*event not handled*/

} /*end of OnCtl handler*/

%%EOF //optional footer line

</code>

Note the following points in this example:

* Text fields for Author:, Title:, etc., should be enclosed in quotes (""). (For backward compatibility, FFP also recognizes an unquoted string of text, beginning with the first non-blank character and extending to the first CR/LF pair, where a quoted string would normally be expected.)

* Comments may be included in an FFP program by prefacing the comment text with "//" or enclosing the comment text between "/*" and "*/".

* <key> names (on the left of the ":") are case-insensitive, while <value> fields (on the right of the ":") are in general case-sensitive.

* The 'Ctl' key is used to set the class, label, and initial value of a control. (For backward compatibility, the default class is 'STANDARD' and the default subkey is 'Text'. FFP also recognizes the 'val' key for setting the initial value of a control.)

* The 'Ctl' key with 'Class=PUSHBUTTON' is used to set or change the properties of a push button control.

* The 'OnCtl' key can be used to override the default action associated with a control, such as the handling of the "button down" event for a push button.

* The order in which the <key>:<value> pairs appear is immaterial except in the case of the R, G, B, A, C, and S keys (see above), in which case the order of appearance in the source code determines the order of evaluation during execution of the filter.

== Also see ==

Command Reference, Syntax, <FM_program>