====== ZFILTER files ======

ZFILTER files are text files that define [[bundywiki>plugins:calc:zeograph:userguide:filters|filters]] used by the [[bundywiki>plugins:calc:zeograph|ZeoGraph]] plugin. 

ZFILTER files are stored in the following directory:

^  Win 7 / Vista | C:\Users\[username]\L3DT\Resources\[version]\Filters\ |
^  Win XP / 2000 | C:\Documents and Settings\[username]\L3DT\Resources\[version]\Filters\ |

===== File sections =====

ZFILTER files consist of the following sections:
  * [[#CLASSNAME]], for declaring the filter class name
  * [[#INPUTS]], for declaring the list of input pins  -- //optional//
  * [[#OUTPUTS]], for declaring the list of output pins  -- //optional//
  * [[#OPTIONS]], for declaring the list of filter options  -- //optional//
  * [[#FILTERDATA]], for declaring the list of internal working data  -- //optional//
  * A set of event scripts, including:
    * [[#ON_RENDER]], for rendering the filter (i.e. performing the filter operation/calculation)
    * [[#ON_CREATE]], for handling custom filter creation steps -- //optional//
    * [[#ON_DESTROY]], for handling custom filter destruction steps -- //optional//
    * [[#ON_OPTIONS]], for providing custom user interfaces for the filter options -- //optional//
    * [[#ON_NOTIFY]], for handling additional notification messages from the parent graph -- //optional//

An example ZFILTER file is provided at the [[#example file|end of this article]] to demonstrate how these elements are combined. Each element shall now be described in detail. 

==== CLASSNAME ====

The name of the filter is declared using the CLASSNAME declaration. In the example below, we declare the 'Power' filter in the 'Math' namespace:

<file>
CLASSNAME:Math.Power
</file>

Notes:
  * Filter class names must be unique. No two filters can share the same namespace/name combination. 

==== INPUTS ====

The input pins are declared using the INPUTS section. This section first states the number of input pins, then defines the name, type and value of each pin. 

In the example below, we declare two input pins. The first is called 'Base', is of type //float//, and has an initial value of 0. The second is called 'Exponent', is also of type //float//, and has an initial value of 1.

<file>
INPUTS:2
Base,float,0
Exponent,float,1
</file>

Notes:
  * Pin names must be unique. No two pins on the same filter can share the same name. 
  * Users should be careful to ensure that the number of pins given after the INPUTS token is equal to the number of pin defined afterwards. 
  * Declaring the input pin initial values is optional, and may be omitted.
  * Declaring the initial value for the following types is not supported: //hvar//, //map//, //format//. 
  * Event scripts may access pin values directly by name.

==== OUTPUTS ====

The output pins are declared using the OUTPUTS section. This section first states the number of output pins, then defines the name and type of each pin. 

In the example below, we declare one output pin called 'Result', of type //float//.

<file>
OUTPUTS:1
Result,float
</file>

Notes:
  * Pin names must be unique. No two pins on the same filter can share the same name. 
  * Users should be careful to ensure that the number of pins given after the OUTPUT token is equal to the number of pin defined afterwards. 
  * Declaring the output pin initial values is not supported.
  * Event scripts may access pin values directly by name.

==== OPTIONS ====

The OPTIONS section contains declarations of filter configuration settings that must be persistent (i.e. stored in graph files, and loaded back). By default, users can edit this data by selecting the [[bundywiki>plugins:calc:zeograph:userguide:filters:options|Filter->Options]] menu option, using a user interface provided by //ZeoGraph// (this can be overridden using the ON_OPTIONS event script). 

As with declaring input and output pins, the number following the OPTIONS declaration lists the number of data items to be declared. Beneath this is declared each item on a separate line, listing the name, type, and (optionally) initial value. 

In the example below we declare one item named "FileName", which is of type //string//, and has an initial value of NULL (i.e. empty string). 

<file>
OPTIONS:1
FileName,string,NULL
</file>

Notes:
  * Filter option names must be unique. No two options in the same filter can share the same name. 
  * Users should be careful to ensure that the number of items given after the OPTIONS token is equal to the number of items defined afterwards. 
  * Declaring the option item initial values is optional, and may be omitted.
  * Declaring the initial value for the following types is not supported: //hvar//, //map//, //format//. 
  * Event scripts may access items declared in the OPTIONS section by name using the 'Options' namespace. 

==== FILTERDATA ====

Additional temporary working data for the filter may be declared using the FILTERDATA section. In contrast to the filter OPTIONS items, the FILTERDATA items exist only during the lifetime of the filter, and are neither saved to nor loaded from disk. This data cannot be directly viewed or edited by //ZeoGraph// users unless the filter specifically implements a user interface for this purpose. 

As with declaring input and output pins, the number following the FILTERDATA declaration lists the number of data items to be declared. Beneath this is declared each item on a separate line, listing the name, type, and (optionally) initial value. 

In the example below we declare one item named "TempMap", which is of type //map//, and has no initial value. 

<file>
FILTERDATA:1
TempMap,map
</file>

Notes:
  * Filter data item names must be unique. No two items in the same filter can share the same name. 
  * Users should be careful to ensure that the number of items given after the FILTERDATA token is equal to the number of items defined afterwards. 
  * Declaring the filter data item initial values is optional, and may be omitted.
  * Declaring the initial value for the following types is not supported: //hvar//, //map//, //format//. 
  * Event scripts may access items declared in the FILTERDATA section by name using the 'FilterData' namespace. 







==== Filter event scripts ====

Filter events such as creation, rendering and destruction are handled using event scripts defined in the ZFILTER file. These scripts are written in the [[bundywiki>plugins:general:zeoscript:reference|ZeoScript language]].

=== ON_RENDER ===

The ON_RENDER event script reads input pin values, performs the filter operation, and writes output pin values. 

In the example below (from the [[bundywiki>plugins:calc:zeograph:filters:math_power|Math::Power]] filter), the ON_RENDER script sets the output pin (//Result//) to be the value of the first input pin (//Base//) raised to the power of the second input pin (//Exponent//). Thereafter, the script returns 0 to indicate success.

<file>
ON_RENDER
set Result <pow Base Exponent>
return 0
END
</file>

Notes:
  * ON_RENDER event scripts must return 0 to indicate success, and -1 to indicate failure. 
  * The script must be terminated by an END token.

=== ON_CREATE ===

During filter creation, //ZeoGraph// will automatically create all input and output pins, and any data declared in the FILTERDATA section, and initialise these variables with values provided in their respective declarations (if given). Following this creation process, //ZeoGraph// calls the ON_CREATE event script (if present) to perform any custom creation steps. 

Notes:
  * ON_CREATE event scripts must return 0 to indicate success, and -1 to indicate failure. 
  * The script must be terminated by an END token.

=== ON_DESTROY ===

When destroying a filter, //ZeoGraph// will call the ON_DESTROY event script (if present) to perform any custom destruction steps. After the script returns, the filter pins and all other filter data will be deleted. 

Notes:
  * ON_DESTROY event scripts must return 0 to indicate success, and -1 to indicate failure. 
  * The script must be terminated by an END token.

=== ON_OPTIONS ===

The ON_OPTIONS event script may be used to provide a custom user interface from which the user may edit the filter's options, and/or allow the filter to perform additional data validation on the options. If ON_OPTIONS is not declared, the default behaviour allows the user to edit all settings declared in the OPTIONS section, and no validation is performed. 

Notes:
  * ON_OPTIONS event scripts must return 0 to indicate success, and -1 to indicate failure. 
  * The script must be terminated by an END token.

=== ON_NOTIFY ===

The ON_NOTIFY event script allows filters to receive notification from //ZeoGraph// for events other than ON_RENDER/ON_CREATE/ON_DESTROY/ON_OPTIONS, and perform additional actions as desired. 

The event is identified by the //NotifyCode// variable (an integer), with the following defined values:

^ //NotifyCode// ^ Description ^
|  1  | The graph is about to begin rendering filters. |
|  2  | A pin has accepted a connection. |
|  3  | A pin has been disconnected. |

In the example below (from the [[bundywiki>plugins:calc:zeograph:filters:math_randomfloat|Math::RandomFloat]] filter), the ON_NOTIFY filter seeds the random number generator when the graph begins rendering (NotifyCode = 1).

<file>
ON_NOTIFY

if <iseq NotifyCode 1> // 1 = render start
  uint seed
  set seed <mul <system.time.GetTickCount> 1073676287> // multiply by large prime to ensure range clipping
  //echo <strcat "Seed: " seed> // debugging
  srand seed // seed the random number generator
endif

return 0
END
</file>

Notes:
  * ON_NOTIFY event scripts must return 0 to indicate success, and -1 to indicate failure. 
  * The script must be terminated by an END token.

===== Example file =====

An example ZFILTER file containing some of these elements is shown below. This example was taken from the [[bundywiki>plugins:calc:zeograph:filters:math_power|Math::Power]] filter, which is included with L3DT Professional and Pro for Torque.

<file>
CLASSNAME:Math.Power

INPUTS:2
Base,float,0
Exponent,float,1

OUTPUTS:1
Result,float

ON_RENDER
set Result <pow Base Exponent>
return 0
END
</file>