home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / graphics / fractal_1 / !Fractal / Help / Scripts < prev    next >
Text File  |  1995-09-05  |  13KB  |  300 lines
  1. Fractal Scripts
  2. ===============
  3. The script facility allows !Fractal to be driven by command scripts rather
  4. than from the screen. This facility is provided to allow:
  5.  
  6. a) Batch running, useful for functions that take a long time to plot.
  7.    Multiple plots are allowed and the images can be saved.
  8. b) Creating composite fractals, such as Fault shapes or multiple L-systems. 
  9. c) Creating a fractal followed by 1 or more 3d transforms.
  10.  
  11. Essentially the script language simulates accessing !Fractal from its menus
  12. and panels, so you get full access to its functionality. Scripts are text
  13. files created in !Edit or any other editor. They feature simple expression
  14. evaluation, variables and screen plotting. They provide a means for creating
  15. complex images from multiple fractals.
  16.  
  17. Several scripts are provided in the Resources directory (use Misc->Resources
  18. from the menu to open), and should help to illustrate the syntax and
  19. capabilities. 
  20.  
  21. Running Scripts
  22. ===============
  23. Scripts are run by dragging the file onto a !Fractal window or its iconbar
  24. icon. Scripts will normally specify the fractal function they require. A
  25. script may be terminated by clicking Adjust. Any error messages (syntax or
  26. otherwise) are written to the file ScriptLog in the Resources directory. To
  27. syntax check a long script just comment out all the Draw commands and run
  28. it.
  29.  
  30. Sprite images are very large, so to perform a long run saving the images as
  31. you go, save the images in GIF format or use an ArcFS or Compression
  32. pathname, since sprites compress very well. This should allow 20+ Mode 15
  33. images per 800k floppy.
  34.  
  35. To superimpose fractal images use the command:-
  36.   Off Image,Redraw,Clear
  37. For images plotted using the x/y pixel mapping, X/Y Guessing must also be
  38. turned off unless the x/y image is plotted first. This is because the
  39. guessing algorithm looks at the colours already plotted to see if subsequent
  40. pixels need plotting.
  41.  
  42. Script Syntax
  43. =============
  44. Essentially the syntax is free format with punctuation necessary only to
  45. avoid ambiguity. The first line of the text must be the characters "Script".
  46. Follow these syntax guidelines:
  47.  
  48. a) Multiple commands are allowed on the same line, except for comments where
  49. the rest of the line is ignored. Use a semi-colon (;) to separate each
  50. command.
  51.  
  52. b) Case of commands and variables is not significant.
  53.  
  54. c) Commands and keywords may be truncated to the most significant
  55. characters. Variable names must be given in full.
  56.  
  57. d) Spaces are ignored except where significant, as in menu item names and
  58. data names.
  59.  
  60. e) Equals (=) may be used to seperate keywords and data values.
  61.  
  62. f) Use commas (,) to seperate multiple items for a command (eg. Data or Select).
  63.  
  64. Command Summary
  65. ===============
  66. Note: Refer to the main help files for permissable values for data items.
  67. Square breakets [] indicate optional items, a vertical bar | is a choice
  68. between values, exp an expression (explained later) and str_exp a string
  69. expression.
  70.  
  71. \ Comment                  All text until end of line is ignored.
  72. 3d_Elevation  exp          Sets the 3d elevation to angle in degrees.
  73. 3d_InvLog                  Sets the 3d Inverse Log mapping.
  74. 3d_Log                     Sets the 3d Log mapping.
  75. 3d_Linear                  Sets the 3d Linear mapping.
  76. 3d_Max  exp                Sets the 3d maximum height value.
  77. 3d_Min  exp                Sets the 3d minimum height value.
  78. 3d_Riemann  On | Off       Sets the 3d Riemann Plot on or off. 
  79. 3d_Rotation exp            Sets the 3d rotation to angle in degrees.
  80. 3d_Scalar  exp             Sets the 3d height mapping scalar.
  81. 3d_XY_Plot  On | Off       Sets the 3d X/Y Plot on or off.
  82. CellFill exp,exp           Invokes the CellFill function starting at x/y.
  83. Clear                      Clears the image.
  84. Colour exp1 [,exp2]        Like GCOL except sets the physical colour.
  85. Draw                       Plot the current function.
  86. Data item=exp [,...]       Set one or more data items, name as in data panel.
  87. Fractal=function name      Set fractal function.
  88. Gcol exp1 [,exp2]          Similar to the BASIC GCOL statement.
  89. If / Else / Endif          Script control - see later.
  90. Load str_exp               Load a sprite or resource file, but not a script.
  91. Off item1,item2,...        As Select, but sets menu item off if on.
  92. On item1,item2,...         As Select, but sets menu item on if off.
  93. Pal_Blue  exp1,exp2        Sets the level of the blue component for a colour
  94.                            number.
  95. Pal_Green exp1,exp2        Sets the level of the green component for a colour
  96.                            number.
  97. Pal_Red   exp1,exp2        Sets the level of the red component for a colour
  98.                            number.
  99. Plot exp,exp,exp           Similar to the BASIC PLOT statement.
  100. Plot_Change exp            Sets the colour change interval for point plots.
  101. Plot_Colour exp            Sets the physical colour for point plots.
  102. Plot_Random On | Off       Random colouring on/off for point plots.
  103. Plot_Step On | Off         Step colouring on/off for point plots.
  104. Plot_Stepby exp            Sets the step colour increment.
  105. Plot_Type exp              Sets the point plot style.
  106. Select item1,item2,..      Select menu item where item is name as in menu.
  107. Save_AFG=str_exp           Save image in AFG format. str_exp is filename.
  108. Save_Image=str_exp         Save image. The full pathname should be given,
  109.                            unless you set the current directory beforehand.
  110. var = exp                  Set a variable to the value of exp.
  111. While / Endwhile           Script control - see later.
  112. XY_Guessing On | Off       Sets the X/Y Guessing on or off. Turn off to allow
  113.                            x/y plot images to be superimposed.
  114.  
  115. Command Details
  116. ===============
  117.  
  118. CELLFILL exp1, exp2      exp1=x coord, exp2=y coord (in os units)
  119. --------
  120. This invokes the CellFill function starting at the given coordinates. All
  121. adjacent pixels of the same colour as the start point will be set to the
  122. CellFill colours. This allows you to flood-fill areas previously plotted. To
  123. set the fill colours switch to the CellFill function, ie.
  124.  
  125.      Fractal=CellFill     \ Selects CellFill
  126.      Data Up=45,Down=56   \ Set the colours
  127.      Fill x,y             \ Start filling at x/y
  128.  
  129. The standard cellfill function can be invoked via DRAW. See MandyGold2 and
  130. MandyGold1 scripts for the different effects between the two styles of
  131. filling.
  132.  
  133. COLOUR exp1 [,exp2]
  134. ------
  135. Sets the graphics colour in a similar way to the BASIC GCOL statement. If
  136. just exp1 is given exp1 is the colour, otherwise exp1 is the GCOL mode (see
  137. the BASIC manual), and exp2 the colour. Colour numbers are 0-255 and are the
  138. physical colour numbers, and thus map directly onto the current palette.
  139. This statement is for use with non-default palettes.
  140.  
  141. DATA item=exp [,....]
  142. ----
  143. Sets the data parameters for the current function, where item is the data
  144. name as shown in the Data display panel, including internal spaces. Multiple
  145. data names can be specified on the same line, separated by commas. Use
  146. Initial or InitZoom as item names to simulate these buttons on the data
  147. panel. For L-Systems the following extra keywords are available (they relate
  148. to the data panel) :
  149.   Angles = exp                number of angles
  150.   Axiom = string expression   eg. Axiom='F-F'
  151.   Clear_rules                 clears all rules for this L-system
  152.   Iterations = exp            number of iterations
  153.   Name = string_expression    Sets name of L-system
  154.   Rule = string expression    eg. Rule='F=XFX'
  155.          1st letter must be the rule-id, the rule string must start in col.3
  156.          Updates (if ruleid exists) or adds a new rule.
  157.  
  158. eg Data x0=34,width=n+34;
  159.  
  160. GCOL exp1 [,exp2]
  161. ----
  162. Sets the graphics colour in a similar way to the BASIC GCOL statement. If
  163. just exp1 is given exp1 is the colour, otherwise exp1 is the GCOL mode (see
  164. the BASIC manual), and exp2 the colour. Colour numbers are 0-255 and are
  165. made up of the bits BBGGRRTT where B=Blue (*64), G=Green (*16), R=Red (*4) &
  166. T=Tint bits. This format is used since it makes it easier to step through
  167. brightness levels (the BASIC format is TTBBGGRR). This mapping only works
  168. with the default palette. For other palettes use the COLOUR statement.
  169.  
  170. LOAD str_exp            eg. Load "<Frac$PDir>.Lyapunov" - loads a palette
  171. ----
  172. This command allows resources such as sprites and palettes to be loaded. Use
  173. <Frac$Dir> to refer to the Fractal directory and <Frac$Pdir> to the palette
  174. directory.
  175.  
  176. PAL_BLUE  exp1,exp2      exp1=colour number, 0 - 255
  177. PAL_GREEN exp1,exp2      exp2=colour level, 0 - 255.
  178. PAL_RED   exp1,exp2
  179. ---------
  180. These three commands allow the image palette to be programmed. exp1 is the
  181. physical colour number (as used in the COLOUR command for example) and exp2
  182. is the level of colour, 255 being full intensity. To set the screen palette
  183. to the image palette, use 'Select Palette,Set Screen' - you must be in a
  184. full 256 colour mode for this to work.
  185.  
  186. PLOT exp1,exp2,exp3     exp1=plot function, exp2=x-coord, exp3=y-coord
  187. ----                    where coords are in OS units.
  188. This performs a standard vdu plot function with the current GCOL settings.
  189. It is provided to allow you to embellish fractal images. See your BASIC
  190. manual for plot function codes. Typical values are:
  191.     4 = Move to x/y, 5 = Draw Line to x/y, 69 = Draw point at x/y
  192. eg. PLOT 4,100,200; PLOT 5,400,300; \ Draw line from 100,200 to 400,300
  193. See the script CIRCLES for an example.
  194.  
  195. PLOT_xxx - these keywords correspond to the Plot Options panel.
  196.  
  197. PLOT_CHANGE exp
  198. -----------
  199. Sets the colour change interval for point plotting. exp is 0-999999.
  200.  
  201. PLOT_COLOUR exp
  202. -----------
  203. Sets the plotting colour for point plotting functions (Bifurcate,IFS,Popcorn
  204. etc). exp is a number from 0-255 and is the physical colour number as shown
  205. in !EditPal.
  206.  
  207. PLOT_RANDOM On | Off
  208. -----------
  209. Turns random colouring on or off.
  210.  
  211. PLOT_STEP On | Off
  212. ---------
  213. Turns step colouring on or off.
  214.  
  215. PLOT_STEPBY exp
  216. -----------
  217. Sets the colour increment when stepping colours. exp is -99 to 99.
  218.  
  219. PLOT_TYPE exp
  220. ---------
  221. Sets the point plotting style. exp is a string evaluating to: Overlay, OR,
  222. AND, EOR, Invert, Add, Subtract.
  223.  
  224. SELECT, ON And OFF  item1,item2,...
  225. ------------------
  226. These commands simulate a menu selection, giving you access to the full
  227. facilities of !Fractal. Use Select for action options (eg. setting a display
  228. palette). Use On or Off for menu items that be switched on or off (Select
  229. would toggle between the states). The item names must be as shown in the
  230. menu structure (including internal spaces, but may be truncated) and must be
  231. seperated by commas. Use a semi-colon to denote end of command before end of
  232. line.
  233.  
  234. These commands also work on panel lists (eg. L-System->List->panel) - simply
  235. code the item name in the panel as the last option, eg.
  236.     Select L-System,List,Dragon ; Draw
  237.  
  238. Variables And Expressions
  239. -------------------------
  240. An expression is made up of numbers, strings, variables, operators and
  241. comparators. Parentheses are not currently supported.
  242.  
  243. Numbers: standard or scientific format, eg. 43.1 or 4.31e1
  244. Strings: enclose within matching single or double quotes, eg.
  245.          "Mike"  'Mike'  "Fred's"
  246. Operators: + - * / for numbers, + for strings.
  247. Comparators: = < > <> (not equal) <= >= 
  248. Variables: names must begin with a non-numeric. Case is not significant.
  249. Commands are searched before variables so avoid names clashing with command
  250. verbs.
  251.  
  252. Expressions are evaluated left to right, so 5+4*2=18 not 13. An expression
  253. is evaluated as a floating point number unless the first value is a string
  254. or a string expression is required, ie.  5+"41"=46  but  "41"+5="415"
  255. Only 1 comparator per expression is allowed.
  256.  
  257. Examples:
  258.    x=45;  y=x+123;  z=x*y;  Data item=x+4;
  259.    suffix=12; Save "Image"+suffix  (creates a file called Image12)
  260.  
  261. IF / ELSE / ENDIF
  262. -----------------
  263. Allows simple logic testing and control.
  264. Syntax:    IF expression
  265.                 1 or more statements if expression true
  266.          [ ELSE
  267.                 1 or more statements if expression false ]
  268.            ENDIF
  269.  
  270. where expression incorporates some form of comparison that evaluates to TRUE
  271. (non-zero) or FALSE (0), ie. IF x > 1. The ELSE clause is optional but ENDIF
  272. is required. IFs may be nested, each with a corresponding ENDIF. Examples:
  273.  
  274.     IF x=y
  275.        IF x=z          (because we can't say IF x=y AND x=z) 
  276.           statements
  277.        ENDIF
  278.        statements
  279.     ENDIF
  280.  
  281.     IF x=y
  282.       statements
  283.     ELSE
  284.       IF
  285.         statements
  286.       ENDIF       (matches IF on ELSE)
  287.     ENDIF
  288.  
  289.     IF name='Fred'; var=var+3; ENDIF
  290.  
  291. WHILE / ENDWHILE
  292. ----------------
  293. Allows simple loops.
  294. Syntax:    WHILE expression
  295.               statements
  296.            ENDWHILE
  297. where expression evaluates to TRUE (statements are executed) or FALSE (skip
  298. to ENDWHILE) - see IF for the suitable expression formats. WHILEs may be
  299. nested and mixed with IF/ELSE/ENDIF.
  300.