Table of Contents
ZFILTER filesZFILTER files are text files that define filters used by the ZeoGraph plugin. ZFILTER files are stored in the following directory:
File sectionsZFILTER files consist of the following sections:
An example ZFILTER file is provided at the end of this article to demonstrate how these elements are combined. Each element shall now be described in detail. CLASSNAMEThe name of the filter is declared using the CLASSNAME declaration. In the example below, we declare the 'Power' filter in the 'Math' namespace: CLASSNAME:Math.Power Notes:
INPUTSThe 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. INPUTS:2 Base,float,0 Exponent,float,1 Notes:
OUTPUTSThe 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. OUTPUTS:1 Result,float Notes:
OPTIONSThe 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 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). OPTIONS:1 FileName,string,NULL Notes:
FILTERDATAAdditional 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. FILTERDATA:1 TempMap,map Notes:
Filter event scriptsFilter events such as creation, rendering and destruction are handled using event scripts defined in the ZFILTER file. These scripts are written in the ZeoScript language. ON_RENDERThe ON_RENDER event script reads input pin values, performs the filter operation, and writes output pin values. In the example below (from the 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. ON_RENDER set Result <pow Base Exponent> return 0 END Notes:
ON_CREATEDuring 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_DESTROYWhen 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_OPTIONSThe 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_NOTIFYThe 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:
In the example below (from the Math::RandomFloat filter), the ON_NOTIFY filter seeds the random number generator when the graph begins rendering (NotifyCode = 1). 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 Notes:
Example fileAn example ZFILTER file containing some of these elements is shown below. This example was taken from the Math::Power filter, which is included with L3DT Professional and Pro for Torque. 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 Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Share Alike 3.0 Unported
|