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:
-
Name and Group
specify the names and the group (sub-menu) under which the created filter
can be accessed from your preferred image editing software.
-
The Description field contains a very
short (max. 47 characters) description of the filter which will be displayed
in the main page of the created filter.
-
The Copyright field contains information
(127 characters max.) about the copyright, author etc. of the filter.
-
The HTML Help field can (optionally)
contain the name of a help file in HTML format that will be opened in the
user's preferred HTML browser when the "Help" button in the created filter
is pressed.
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 init block is executed once before each filtering process
-
The pass1 block is executed once for every pixel in the image;
the values are read-only, i.e. you cannot modify the image data of your
image. This block is only used for collecting data about the image (e.g.
to calculate the average lightness, etc.)
-
The init1 block is only executed once between pass1 and the
main pass. This can be used e.g. to evaluate the data collected by pass1.
-
Finally, the main block (no special keyword is required for this) is executed
once for every pixel; the main filtering is done in here. In this block,
the R, G, B, and A values can be set for every pixel.
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