====== Advanced:ZeoScript filter ======
===== Filter info =====

^  Description | Execute a user-defined script.  |
^  Author | [[user>Aaron]] |
^  Plugin | [[bundywiki>plugins:calc:ZG_script|ZG_script]] ^

===== Looks like =====

|  {{ :plugins:calc:zeograph:filters:adv_script.png |The 'ZeoScript' filter.}}  |  {{:plugins:calc:zeograph:filters:adv_zeoscript_conn.png|}}  |
^  ZeoScript, when disconnected  ^  ZeoScript, when connected  ^
===== Input pins =====

Input pins may be accessed in scripts using the variable names ''in0'', ''in1'', ''in2'', etc. The data type of an input pin is determined by the data type of the output pin to which it is connected. 

===== Output pins =====

Output pins may be accessed in scripts using the variable names ''out0'', ''out1'', ''out2'', etc. The data type of an output pin is determined by the data type of the input pin to which it is connected. 
===== Options =====

The only options stored within the ''ZeoScript'' filter is the script to be executed when the graph is run. Hence, the [[plugins:calc:zeograph:userguide:filters:options|filter options]] window for this filter is the //L3DT Script Editor// window, as shown below. The user guide for the script editor is [[bundydocs>l3dt:userguide:scripts:editor|on-line here]].

| {{:plugins:calc:zeograph:filters:adv_zeoscript_options.png|The 'script editor' window.}} |

<note tip>
It is unnecessary to save the filter's script using the //L3DT Script Editor// window, as the script is stored in the filter and thus is saved in the graph file. 
</note>
===== Comments =====

==== Script return value ====

Scripts must return 0 to indicate success, or -1 to indicate failure. 

==== Example ====

A substantial example of the ''ZeoScript'' filter is given in the 'Sine generator' graph that is included in the L3DT installer. This script filter generates a heightfield using a sine wave function using a number of input parameters. The script is given below:

<code>
int i j nx ny
hvar hMap
float period
float direction
float amplitude
float f


set hMap in0
set nx in1
set ny in2
set period in3
set direction in4
set amplitude in5

set out0 in0 // map from input to output

assert <isgt nx 0> "Heightfield is not initialised!"

//
// prepare progress box
//

progbox ProgBox
int64 p pmax

set p 0
set pmax ny

progbox.ShowWnd &ProgBox
progbox.SetTitle &ProgBox "Calculating"

//
// prepare some variables for the loop
//

float fx fy phase freq Angle_rad
set freq <div <mul 3.14159 2> period>
set Angle_rad <mul <div direction 180.0> 3.14159>
set Angle_rad <sub <div 3.14149 2> Angle_rad> // makes angles clockwise, with 0 at north

//
// here we go!
//
set j 0
do

  // set progress every line
  progbox.SetProgress &ProgBox p pmax
  incr p

  set i 0
  do
    set fx <mul <cos Angle_rad> i>
    set fy <mul <sin Angle_rad> j>
    set phase <add fx fy>
    
    set f <sin <mul freq phase>>

    set f <mul f amplitude>

    map.SetPixel hMap i j &f
        
  while <islt <incr i> nx>
while <islt <incr j> ny>

//
// flag map as being ready and modified
//
map.SetFlag hMap 1 true // MAPFLAG_ISREADY
map.SetFlag hMap 5 true // MAPFLAG_ISMODIFIED

return 0
</code>