FilterFormula Main Page
3. General Usage
3.1 Invoke FilterFormula
3.2 Define a filter
3.2.1 Compiler options
3.2.2 Import / Export of Filters
3.2.3 Create a Standalone Filter
3.3 Structure of a filter

3. General Usage

3.1 Invoke FilterFormula

First, you will have to load an image into your preferred image editing program. Then select the menu item that leads you to third-party plug-in filters (usually this can be found under "Filters", or "Effects", or "Image -> Plug-ins") and select "FilterFormula" from the "ATS" subitem.


The dialog window consists of several components that will be described in the following:

Preview window:
In the upper left corner of the dialog box a part of the image to be filtered is displayed. This segment can be moved (move the mouse cursor to this window, press the left button and move it) or scaled. The scaling factor (displayed in text) can be changed by using the '+' and '-' buttons.
(Special feature: If you hold the SHIFT key while pressing any of these buttons, the zooming factor is set to the highest or lowest possible value.)
This window is used for display of both original image and filtered image preview. While it is moved, always the original image is shown. If anything has been changed (slider settings, filter name etc.), half a second after the change, the visible part of the image is processed by the selected filter and redisplayed. The filtering preview can be switched off if you deselect the "Filtering" checkbox; in this always the original image is displayed (useful to save time or for better positioning).
Note: 1) if you use the src()-function (or an equivalent function) in your filter or you are using a two-pass filtering approach (non-local filters), it could be that the image displayed is not what it should look like. This is because only the small part of the image is read and all image data outside this rectangle is not available. Therefore the border pixels are used instead which can result in wrong preview images. Also, if you chose to scale the picture, the result might not be the exact scaled image of the resulting image. But this window is used just to get an idea how the result might look like.
2) If the filtering algorithm is too time consuming (or an endless loop has been programmed), the preview filtering is stopped after around two seconds and the original image is displayed. In this case, the image is overlayed with a white X to signal that filtering could not be done (a part of the picture could be displayed as filtered and another part unfiltered).
Select Filter area:
In this area, you can either select a predefined filter from the list of available filters, or you can define a new one by simply entering the name in the combobox edit field. Then you can edit it (and compile it), or delete an existing filter by using the appropriate buttons.
If you change this field, you will notify that the OK button of the whole window could become unavailable. This is done when the filter name you entered is not available as executable code. You can then only edit and compile the filter, select another filter, or cancel the whole filtering process by pressing the Cancel button.
Slider area:
FilterFormula filters may use up to eight sliders where filter parameters can be entered. You may enter them either by moving the slider bars with the mouse (or keyboard), or by entering the numerical value in the white edit box. The default range of the sliders is 0 to 255, but it may be changed by selecting the "Options" button from the edit window. (also the names of the sliders may be changed.)
Additionally, there are two custom checkboxes (can be selected with the chk() function) and up to six color selector buttons. By pressing any of those, you can select a custom color.
(Special feature: You can select the color by a color picker from the preview window when you hold down the SHIFT key while pressing this button. If you move the cursor over the preview window, a color picker is displayed as cursor and you can select a color from it. This is ended when you press the left button plus SHIFT key in the preview window.)
Button area:
The "About" button shows some information about the release, build etc. of the program, and the "Help" button invokes your preferred HTML browser and displays this help about the FilterFormula.
By pressing the "OK" button the selected filter is applied to the image. If you press "Cancel", no filtering is done.

3.2 Define a filter

After pressing the "Edit" button in the main dialog screen, the filter editing window appears: This window can be used to define your filter in a source format similar to the "C" language. The main area is the big edit field in the center of this dialog box, it has a vertical scrollbar and always uses the "Courier New" font.

This window is a standard Windows text edit control, you can use all the default Windows editing functions (cut, copy and paste; but only via the keyboard shortcuts <Ctrl+X>, <Ctrl+C>, and <Ctrl+V>, "undo" is <Ctrl+Z>, etc...) and press the ENTER key to go to the next line. Only pressing TAB would take you to the next button of the dialog box window.

The lower/smaller window is the message window where the messages that appear during the compilation, are displayed. You will be shown possible error causes, errors, and at the successful end of the compilation some code statistics are displayed. (New)

On the top of the window you can see a status indicator of the compilation. An OK means that the source code was compiled o.k. and has not been changed since then; a red exclamation sign ("!") shows that there have been errors in the compilation (they are signalled also in a message box), and tree dots ("...") show that the input is pending and the source has not been compiled in this configuration.

The OK button will only be available when the OK sign at the top line is visible.

At the bottom of the dialog window there is a number of pushbuttons that will be listed in the following:

Import allows you to load external filter code (source and/or compiled) from a file. See section 3.2.2 for a complete description of this function.

Export with this function you can save the contents of the filter source to a plain source file or to a FilterFormula Interchange Format file. See also section 3.2.2 for a complete description..

Options Pressing this button will open a dialog which enables you to set the options for the respective filter, that are the size of the array (accessed with the put and get functions), and the name and scale for each of the eight sliders. See the separate description of this dialog window.

Compile Before you can process a filter, you have to compile the source code to i386 machine code. This is done by pressing this button. If there are no errors in your code, the "OK" sign at the top of the window will appear and the OK button will become enabled.

If an error is encountered, a message describing the type of error (e.g. syntax error) is displayed and the cursor is moved to the position of the error (or, at least, where the compiler found that there is an error which can also be several lines below the actual error or even at the end of the source code). Additionally, the red exclamation sign is displayed at the top of the dialog box.

Standalone This option allows you to create a standalone filter that can be used without the FilterFormula development filter. See section 3.2.3 for a detailled description of the process of creating standalone filters.

Note: this option is not enabled in the SHAREWARE version of FilterFormula; if you register it, you will receive the full version where this function can be performed.

OK leave the filter editing dialog and store it.

Cancel undo all changes and/or do not store the filter code.

All buttons can be selected by pressing the appropriate shortcuts on the keyboard (the characters underlined).
 

3.2.1 Compiler options

When you press the "Options" button in the editing dialog, the following dialog box is displayed on the screen: For every filter the size of the storage array can be defined which can be accessed via the put() and get() functions. Every array item is a 32 bit signed integer value, and the array size can have a value from 256 (minimum for compatibility with Filter Factory) to 65536 - which uses a memory block of 256 KB which is quite a lot - so use this only if you really need this amount of storage!

This setting can be overwritten if you define the compiler option !{ssize=...} in your source (see below).

Besides that, for each of the eight sliders in the filter main screen you can define the name (which is written before the actual slider), the enable state (if you can use this slider) and the possible range of the slider. The boundaries must be between -32768 and 32768, and the upper bound must be greater than the lower.

This setting changes the behavior of the ctl() and the map() functions, but not val() (only indirectly by decreasing the granularity, if a very small range is selected). See below for a more exact description of the appropriate functions.
 
 

3.2.2 Import / Export of Filters

These two functions allow you to load either the source and/or compiled code of a filter created by someone else or for another filter generation plugin and to save them to use it on another copy of FilterFormula on another PC (the *.ffm files are internal filter representations only and cannot be transferred to another computer system).

The following formats are supported by the FilterFormula import/export facilities. Please note that some formats are only available for import or export. The FilterFormula Interchange Format is only available in the full/registered version.
 

Plain format source code (File type *.ffs or *.c)               [Import & Export]
This format is a simple Windows text file that contains the filter's source code in plain format. You can use this format to use a file which was created by a third-party editor or which you found on a filter source collection on the internet. Note that this file should not exceed the length of 16 Kilobytes. The "options" settings cannot be specified in these files and must be supplied manually.
Adobe Filter Factory Source file (*.afs)                           [Import only]
This format is an Adobe-internal (non-readable) file that contains the source code for a filter defined in Adobe Filter Factory that accompanies the Photoshop image editing software.  When you import such a file, the expressions in the afs-file are changed so that they form valid FilterFormula statements: Prefix them with "R=", (B,G,A) and append a semicolon to each expression.
Additionally, the import routine will replace all occurrences of variables and functions that are not used in FilterFormula (but used in Filter Factory) by the respective settings so that the effect will be the same: a "z" is replaced with "0" to "3" (channel number), a "c" is replaced with "r", "g", "b" or "a" and the function "cnv()" is replaced with "cnvr()", "cnvb()" etc. (see the description of these variables and functions below).
Attention: If you import Adobe filter sources other than with this function (cut and paste, import as text, etc.), no translation will be done and the variables "z" or "c" will be treated just like user variables. This can be a potential error cause, so be aware of this!
FilterFormula Interchange Format (*.ffi)                  [Import & Export, Full/Registered Version only]
This format contains all filter relevant information including filter source, compiled code and "options" settings. This format contains two sub-formats (selection only available during export): F.F.I. with source or F.F.I. without source. In the first case, the complete source is stored together with all other information and can be changed, recompiled etc, made to standalone filters etc.. The second format  is useful for filters that you want to distribute, but you don't want to give away with their source code. If you export a filter in this format, the recipient can import the code, but cannot view or change the source code. Information about the code is displayed instead. A standalone filter can be created from this format, but the Group, Description and Copyright information cannot be changed.
If you choose to export a filter in the format without source, a dialog window is displayed where you have to specify Name, Group, Description, and Copyright of the filter (see below in section 3.2.3).

 
You will have to specify or select a filter name in the standard Windows file selection dialog and press the "Save" (or "Open") button. Then the file is written or read.
 
 

3.2.3 Create a Standalone Filter

In the full/registered version, FilterFormula gives you the possibility to create Adobe-Photoshop compatible filters that can be distributed royalty-free without the underlying filter creation tool. You can sell or give away your filters without the need to publish the valuable source code of your filters. Additionally,  the size of the created filters is much smaller than the complete FilterFormula plugin (about 70 KB). Unless Adobe's Filter Factory, the source code cannot be retrieved from the compiled filters in a simple way. The filters are only stored in their machine code form without their source code which makes it almost impossible to reverse-engineer them.

You have also the possibility to define a help file in HTML format which can be invoked from your custom filter by pressing the "Help" button. If you do not supply a help file, the "Help" button will be unavailable in your custom filter (the HTML help file must be in the same directory as the created ".8bf" filter file).

When you select this option (the code must have been compiled before), the following pop-up dialog window appears:

In this window, you can enter some information about the filter being created: When you press the "Save as" button, you are prompted to enter the name of the filter being created:
(this is the standard file selection dialog - in this case in German language - where you can enter the name of the filter being created).

The options that have been set in the "Options" dialog are used for the naming and visibility of the controls in your custom filter.

This whole process creates a plug-in filter (you have to copy the created ".8bf" file into the program's plug-in directory and eventually restart the image editor) which could look like that:


You might note that the unselected sliders, checkboxes and color selectors are not displayed here at all (just a rest of the color selection boxes).
The usage of this filter is quite similar to the usage of the main FilterFormula plugin.
By pressing "OK", the filtering process is performed here.
 

3.3 Structure of a Filter

Each filter in FilterFormula can consist of up to four different blocks: The contents of all blocks are enclosed in braces:
init { <initialization statements> }

pass1 { <statements in first pass> }

init1 { <initialization before second block> }

<real filtering statements>

These blocks must be defined (they can also be omitted, though) in exactly this order (no statements for the main pass before the definition of the other three and pass1 after init etc.)

See the following figure that illustrates the filtering process:

For the statements, functions and predefined variables that can be contained within the blocks, see the language reference part.


Back to Main Page

Previous Chapter
Next Chapter