  ________________________________________________________________________
 /                                                                        \
|                ARCHIMEDES FRACTAL GROUP : Initial Newsletter             |
|                                 May 1991                                 |
|                            from Mike Curnow                              |
 \________________________________________________________________________/ 


Introduction
============
Welcome to the initial release from the Archimedes Fractal Group. You have
probably got to this file last, after playing with the supplied programs. If
not, give them a quick go before settling down to find out more about the
AFG.

You will find on the disk:

!Mbrot     - a desktop Mandelbrot plotter.
!Julia     - a desktop Julia plotter.
!Interfere - an Interference pattern creator
!Martin    - a program that uses the algorithm of Dr. Martin.
!System    - required Acorn modules.
!News9105  - this file with a little browse program.
!AFGSprite - AFG sprite editor
!Packer    - a simple sprite compression facility to help save disk space
!ArcFS     - utility to display the images below
Images     - a Spark file containing the following images. Load !ArcFS first
             to be able to use these images.
Arcscape1  - Sample sprite from ArcScape program
FracScape1 - Sample sprite from FracScape program
Gasket     - Sample sprite from Sponge program
M_SeaHorse - sample sprite from !Mbrot. Can be reloaded for further zooming.
M_Twister  - from !Mbrot. Try loading into !AFGSprite and use Animate.
J_Limit    - sample sprite from !Julia. Can be reloaded for further zooming.
J_Fingers  - sample sprite from !Julia. Looks good when animated using Cycle.
Int_724    - sample sprite from !Interefere. After 360 cycles of animation
             it gets back to the original pattern!
Int_817    - from !Interfere. Try this one with a Blue palette. The patterns
             are mostly octaganol rather than circular.

Each application has its own !Help file. To view the help: Press the Menu
button with the mouse over the application icon, then follow the
"App.'....'" menu - at the bottom click on the Help menu item. 

Besides introducing you to AFG, this newsletter contains suggestions on
fractal programming using the Wimp and how to make submissions of your own
work.

If you want to use !Edit to scan this file or extract programming examples,
first load !Edit, then double click the !News9105 directory whilst holding
down the left shift key. Finally double click on the ReadMe file.

Background
==========
Who are we, what do we do, what is in it for you?

AFG has been set up as a focal point for work on Fractals and related
mathematical systems using the Acorn Archimedes computer range. There are
several groups and newsletters for other machines, but none that I am aware
of for the Archimedes. Fractal programs can be run on any computer, though
the Archimedes is one of the better ones for this because of its speed.
However a lot of effort is often needed to take the basic mathematical
formulae and then to wrap it up in a program that is easy to use and which
makes the most of the machines environment.

Fractal programs quickly appeared for the Archimedes, mainly as a
demonstration of its computing power. This work has been sporadic and does
not match the quality to be found in PC versions.

This is where AFG fits in. Investigating fractals, even on a powerful
machine, takes a lot of time and experimentation. By pooling the skills and
software routines of other Archie programmers, members of AFG will be able
to greatly expand their own capabilities and be able to explore whole new
areas of fractal geometry.

So AFG is aimed at people who want to explore and generate their own
fractals on their machine. The emphasis is very much on the doing rather
than theory or staring at pretty pictures. This is where the fun is - the
world of fractals is so large it is pretty easy to come across new fractal
shapes or stumble on to a new formula. 

AFG aims to be a self help group - its success will depend on each member
contributing their own tips, programs, images, suggestions and so on. My
role will be to co-ordinate all the software, help, contacts etc., as well
as providing my own input. I will maintain a database of submissions
(programs, images, tips) and contact names and addresses. If there is
sufficient activity, I may also publish a newsletter.

To assist in inter-communication between members, I have created some draft
standards for submissions of programs, images and documentation. This will
help to ensure that other members can investigate the same findings. I will
also be supplying some utilities to make application development easier.


AFG Membership And Rules
========================
Membership: to encourage participation, to become a member I ask you to
donate one or pieces of your own or Public Domain Fractal software - see the
end of this newsletter for what I have already. Source code is especially
desireable.

Nobody likes rules so initially there won't be any for this group. That
means no charges for membership or software, but obviously I will have to
pass on costs where incurred. This will operate as follows :

In any correspondance, if you need a reply, enclose a stamp, preferably a
SAE. The best way to correspond is by sending a disk, which will allow me to
extract any useful information for newsletters etc.. In return I will send
you the latest acquisitions in the library.

NB. Always write your name & address on the disk so I know which one is
yours!

If you require copies of programs, enclose a disk & return postage. I
suggest you mail using Jiffy bags or other suitable packaging - they can be
re-used several times and prevent damage to the disks.


Who Is Mike Curnow? (answers on a postcard to ...)
===================
I am an ex-Geography student that has had a fascination with computers from
early school days (we're talking of a 4-bit IBM schools computer here, circa
1970 - yes desktop PCs have existed a lot longer than you might imagine). My
job for the last 8 years has been working as a System Programmer (actually
nothing to do with programming) for a service company, looking after client
IBM mainframe sites.

I experimented with fractals on a BBC-B which lasted me until last year,
when the machine began to falter. Digging deep into my pocket, I now own a
Arc 410 with 40Mb hard disk (always filling up), 2Mb memory (how people
survive with less I do not know), and, most essential of all, an ARM-3 30Mhz
processor.

I would definitely recommend the ARM-3 - I got mine from Watford Electronics
who sell them at a reasonable price (especially when bought with a machine).
Optimised code runs up to 5 times faster - for instance the !Mbrot program
takes just 5 seconds to generate the initial image. I gather Acorn will be
releasing an A3000 ARM-3 later this year, so you can tell this is the way
things are going.

I program in Assembler, Basic and C (well, I am trying to get to grips with
this rather finicky but undoubtably powerful language).

The Hidden Help
---------------
Anyway back to fractals. My main source of inspiration comes from the
following publications:

Dynamical Systems And Fractals: Becker & Drfler, CUP, 10.95
The best value for money fractal book around with lots of programming help.
The source is in Pascal, but this is easy to convert into BBC Basic.

The Science Of Fractal Images: ed. Peitgen & Saupe, Springer-Verlag, 25
A lot more mathematical (it makes my eyes go crossed just looking at the
formula), lots of pretty pictures, and many definitive routines given in
pseudo-code which are usually easy to convert into Basic.

Fractal Report: bi-monthly from John de Rivaz, 10 per 6 issues.
Just started to get these, it will take some time for me to get typing the
routines in, but most are usefully short.

FractInt v15.1: Just acquired this collection of public domain software for
the PC. My aim is to port the most useful stuff across to the Archie, but
that could be rather ambitious, especially since they have started to use
C++ (I doubt Acorn will update their C compiler for some time, if at all).
Anybody willing to help?


Submitting Material - What Is Required
======================================
AFG will be very dependent on people supplying their own work or other
public domain software, for distribution amongst members. I will maintain a
list of all submitted work which will be enclosed with replies. The disk you
send will be returned either with material you have requested, or with any
recent news and software acquisitions. 

The following list of guidelines will help to ensure that members will get
the most from the material. They are a collection of personal preferences
and tips which you should find useful. If you have any of your own
recommendations or objections, then I am ready to be told off!

However all submissions will be gratefully received, in whatever state. Just
remember that it is your name which will be in the spotlight.


Programming Language
--------------------
Personally I don't mind what language you program in, but Basic will give
you the widest audience. When sending compiled programs (C, Assembler,
Pascal etc), PLEASE enclose the source - you really have nothing to lose by
witholding it, and we have much to gain.

Assembler is obviously fastest, but C is not far behind. When computing real
numbers BASIC is almost as quick since it use 5 byte reals compared to 12
bytes as used by the floating point emulator. Assembler programs can use the
floating point instructions, but unfortunately they are not included in the
Basic assembler. However my BASIC library routine FPLib will assemble
floating point instructions.


Desktop vs Dedicated, Applications vs Programs
----------------------------------------------
Most fractal programs are non desktop orientated, the excuse being that it
is too complicated and not relevant. However, take a look at the !Mbrot and
!Julia applications on this disk to see what is possible. Once you have
coded the initial desktop shell code, it is surprisingly easy to modify it
for other programs - !Mbrot & !Julia share 95% of the non-computational
code. C is a great help in Wimp programming since Acorn supply a whole
library of subroutines that makes desktop application programming relatively
easy.

For short programs I can understand the reason for non-Wimp operation.
However it is a simple matter to make a non-Wimp program run from the
desktop as an application.

Therefore I recommend all programs run as !Applications. The minimum you
will need is :

a) a directory prefixed with !
b) an Obey file called !Run, containing "Wimpslot nnnK", any other
initialisation statements, and a final "Run <Obey$Dir>.program_name"
command.
c) Typically the main program is called !Runimage but there is no reason why
it cannot be called anything else.
d) a !Help text file containing the documentation.


Desktop Programming - Some Tips And Recommendations
---------------------------------------------------
For BASIC programs the best approach is to create a library of Wimp
procedures and functions. I can supply a starter Wimplib library and a copy
of !FormEd which allows you to interactively create window definitions.

There is no reason why your application does not take over the whole screen.
This can be done by setting the Title colour to 255, background to 7 (black)
and the Title & Work area flags to 0. This creates a window with no borders
which you can then make the size of the screen. You should supply a menu
option to allow this window to be closed or at least shrunk to partial size.

A big problem with the Wimp for Fractal programs is that the Wimp expects
your program to be able to redraw a part or all of your window in real time.
Now this is usually out of the question. The circumvention is fairly simple,
namely to do all your drawing to a sprite. There are OS functions available
to direct your VDU output to a sprite, or you can write to the sprite
directly (instead of writing to the screen).

This sprite (and therefore window) can then be drawn automatically by the
wimp by using the Wimp_CreateIcon function, or by creating the sprite at
window create time and appending the Icon control block to the end of the
window control block. The window should have the "automatic wimp redraw" bit
set (bit 4 of the window flags). This way your program will never receive
window redraw requests. Note that your sprite can be any size, not just the
size of the screen : it can be smaller or larger. 

Plotting to sprites also has the advantage that you can swap between
previous images and are in a format ready to save to disk and reload. See
!Mbrot for an example.

Another problem is what to do when computing a fractal image - just hang the
machine or work in the background? With !Mbrot & !Julia, if the computation
is quick, then it locks the machine, drawing on screen (and to sprite) as it
goes. If the computation is lengthy it also initially hangs the machine, but
checks regularly for mouse clicks. When a click occurs it returns control to
the wimp but with the WimpNull event enabled. When a WimpNull event occurs
it plots a few more points then returns control - take care not to use too
much time since this will make typing rather jerky.

This provides multi-tasking, though you will find programs run much slower
because of the overhead of calling the Wimp every few calculations. The
!Mbrot/!Julia applications allow dedicated mode to be re-entered by clicking
on the  icon-bar icon. Thus users can choose which way to run - I find it
useful to be able to carry on programming whilst a fractal is being
generated.

A simple way to get numerical input without a complicated menu structure, is
to provide an "Input" menu selection. When clicked you open a Wimp Command
Window, then use standard PRINT & INPUT to get the data. When finished you
simply close the window : Wimp_CommandWindow is used in both cases.

All this assumes of course that you have access to the RiscOS Programmer's
reference books which describe all the OS calls. If you don't, I can
recommend the book:

  Archimedes Operating System: Alex & Nic Van Someren, Dabs Press, 14.95

It contains many of the SWI calls required, though it strangely omits the
OS_Sprite calls. Alternatively just rip apart any BASIC application for the
necessary Wimp calls or put in a request to me.


AFG Sprite Files
----------------
Saving a screen image (via *Screendump) is the simplest way to preserve a
hard won image. One disadvantage is that you need to create a separate
record of the parameters required to generate sprite, and how do you
remember which program generated what image?

To solve this problem I propose the AFG Sprite standard - this has been
implemented in the !Julia and !Mbrot applications on this disk. An AFG
sprite is simply a standard sprite file which has embedded control
information describing the originating program and parameters. They are
compatible with !Paint and !Draw, but are restricted to only one set of
control information per sprite file ie. I recommend to store only one sprite
per file.

AFG Sprite Layout:
The following is how the sprite looks in memory. On file the 1st word is
omitted. The values are in decimal unless preceded by '&' for hex.

Name   Offset  Len.  Function
------------------------------- 
Size      0      4   Total sprite area length       } Standard sprite 
Number    4      4   Number of sprites              } area header
Sproff    8      4   Offset to 1st sprite           }
Freeoff  12      4   Offset to free area            }
AFGver   16      4   AFG1 ie. &31474641 : identifies an AFG v1 sprite
                     Check this value to verify AFG1 sprites. 
Pgmname  20     12   Program name and version id, zero terminated string.
                     Check this to determine if sprite belongs to your
                     program when loading. eg. "Julia V10"
Varnum   32      1   number of control variables to follow (may be 0).
Varlen   33      1   Variable length in bytes & type. These are:
                       4=integer
                       5=Basic floating point
                       8=Double floating point (Assembler & C)
                      12=Extended floating point
                     &80+string len=String, zero terminated (not CR).
         34..nn  1   Length types of other variables
vardata  nn      n   variable data, word aligned
..        .
Sprhdr   ss     44   Sprite header                  } Standard sprite format
sprdata  dd     nn   Sprite data

In a non-AFG sprite Sproff contains 16 since there is no additional
information. In an AFG sprite Sproff will contain 16+length of AFG control
information. Checking AFGver and Pgmname when loading a sprite allows your
program to verify an acceptable sprite.

Varnum must be set to the number of variables that follow. Variables are
identified by their length, or +128 for strings. There will be one or more
Varlen fields in contiguous bytes. The variable data itself then follows,
each variable starting on a word boundary.

Nb. BASIC uses a carriage return (CR) to terminate strings, RiscOS & C uses
a zero byte. To store a zero terminated string in BASIC use
$x%="String"+CHR$0 and allow for the two extra bytes for the 0 & CR in the
length. To retrieve the string use S$=LEFT$($x%) which will strip off the
trailing zero byte.

The complete code for creating an AFG sprite in BASIC is now given:

    10 REM Reserve storage for a Mode 13 sprite (80k) + control info
    20 AFGlen=32:Sprlen=80*1024+44+16+AFGlen
    30 DIM S% Sprlen
    40 REM Initialise the sprite area
    50 !S%=Sprlen:S%!8=16+AFGlen
    60 SYS "OS_SpriteOp",256+9,S%
    70 REM Set up AFG Header
    80 $(S%+16)="AFG1"
    90 $(S%+20)="Myprog v10"+CHR$0:REM Max 10 chars in name
   100 S%?32=2:REM 2 variables in this example
   110 S%?33=5:REM 1st variable is a BASIC float
   120 S%?34=4:REM 2nd variable is an integer
   130 float=2.345:int%=128:REM variables to store
   140 |(S%+36)=float:REM Float variable, on word boundary
   150 S%!44=int%:REM Integer variable, on word boundary
   160 REM Now create a sprite for full screen Mode 13 plotting
   170 SYS "OS_SpriteOp",256+15,S%,"MySprite",0,320,256,13
   180 REM Set up a variable to allow writing straight to a sprite
   190 SprAdr%=S%+16+AFGlen+44

You can now store 256 colour bytes values at SprAdr%?offset - you don't even
need to be in mode 13! To complete the program and save the sprite use:
       SYS "OS_SpriteOp",256+12,S%,"Filename"

To load a sprite a similar section of code is required :

    10 REM Reserve storage for a Mode 13 sprite (80k) + control info
    20 AFGlen=32:Sprlen=80*1024+44+16+AFGlen
    30 DIM S% Sprlen
    40 REM Initialise the sprite area
    50 !S%=Sprlen:S%!8=16+AFGlen
    60 SYS "OS_SpriteOp",256+9,S%
    70 REM Now load the sprite (Use X version to trap errors)
    80 SYS "XOS_SpriteOp",256+10,S%,"Filename"
    90 IF S%!16<>&31474641 THEN PRINT"Not An AFG Sprite":END
   100 IF LEFT$($(S%+20))<>"Myprog v10" THEN PRINT"Not My Sprite":END
   110 REM Pick up variables from last time
   120 float=|(S%+36):int%=S%!44

Phew! Sorry if that was a bit heavy going (which is why I supply the code
above), but storing all the relevant information in this way gets around the
problem of separate control files.

If you are wondering why the number and type of variables is specified, this
is for programs that store varying parameters and for the utility
!AFGSprite. !AFGSprite will convert ordinary sprites to AFG sprites, and
perform useful transformations not available in !Paint.

A fairly high priority project for me is to update !Packer to allow
direct loading and saving of packed AFG sprites to save precious disk
space.


Sprite & Display Modes
----------------------
256 colour modes are usually the best for many reasons. For programming it
allows direct screen/sprite writing since each byte is a colour, thus
speeding up processing by bypassing the OS plot calls.

I prefer Mode 13 because of its square pixels (320x256 resolution). Mode 15
takes twice as long to draw and the oblong pixels sometimes look strange. If
you have a multi-sync monitor then Mode 21 (640x512 pixels) is best for
displaying, though I would advise calculating in some other mode since the
multisync modes slow down the processor.

Using the desktop in Mode 13 is not very nice since all the text gets
garbled. You can get around this problem by displaying a Mode 13 sprite in
mode 15. The wimp will automatically convert the sprite for you if you let
the wimp do the drawing. If doing your own sprite plotting, then use:

  OS_SpriteOp 256+56,sprite_ptr,x,y,0,scale_sptr,0

where scale_ptr points to a 4-word/16 byte control block containing:

  2  x multiplier
  1  y multiplier
  1  x divisor
  1  y divisor

Note also that when creating a sprite it is possible to create it in any
size, dependent on memory constraints. Thus you could create a Mode 13
1280x1024 sprite on a 2Mb machine. The sprite could be panned around on
screen, but the real advantage comes in printing where the extra resolution
will banish those jaggies when printing at full page size.


Documentation
-------------
Documentation is the last thing people get around to, but I can ensure you
that in 6 months time you will be glad that you documented how that
superfast routine you knocked up in fit of inspiration, works. Documentation
should be put in a file called !Help within an application directory, or as
a !Help directory using the !Help application explained later in this
newsletter. 

I suggest the following accompanies all code and programs:

How to use the controls: Who knows what keys you have chosen? Essential for
non-desktop applications.

The fundamental formula: ie. the algorithm that makes the program work.
Essential if your program is not in Basic because not everybody can read
Assembler or C.

Credits: if (as is likely) your routine was based on a someone else's,
please give references so that we can also check up on it. ie. Supply
publication name, date, page number etc.


AFG Software Library
====================
The following list documents the software that can be obtained by AFG
members by sending a disk(s)+stamps and a list of your requirements.
Alternatively send a 2.00 cheque made payable to Mike Curnow and I will
supply a new diskette + post & packaging. Please state Name, Version and
Author where specified.      

Note: the sizes given are a rough guide for you to know how much will fit on one disk.

Source: B=BASIC/Assembler, C=C, P=Pascal, N=none,
        b=BASIC/Assembler under Tube 6502 emulator,
        6=BASIC/Assembler under !65Host (ie. a BBC-B program).

Name      Version Size  Author  Source Function
----------------------------------------------------------------------------
!Beauty           260k  C.Declerck  N  Animated rendered 3D mandelbrot demo.
                                       Coffee table stuff.
!AFGSprite  1.0    43k  M.Curnow    Y  Converts sprites to AFG format and 
                                       allows them to be edited.
!FastBrot  15.0     8k  S.Streater  N  Very fast integer Mandelbrots, but
                                       limited resolution.
!Interfere  1.0    25k  M.Curnow    B  Circular interference patterns -
                                       fast 16/256 colour animation with
                                       full mouse control. Mesmerising.
!Julia      1.1   156k  M.Curnow    C  Desktop Julia plotter. Fast.
!Mandel             6k              B  Fast Integer mandelbrots,ltd. res.
!Mandel     6.0   290k  D.Karunadasa B Comprehensive desktop mandelbrots,
                                       though slow.
!Martin     1.0     3k  M.Curnow    B  Dr.Martin's fast, simple generator.
!Mbrot      1.0   160k  M.Curnow    C  Desktop Mandelbrot plotter. Fast.
!Scape             34k  M.Hesketh   B  3D Mandelbrot generator. Provides
                                       full control over x/y/z viewing,
                                       zooming and colours. Fast but uses a
                                       small mandelbrot. No Asm source.
A_DRAGON            2k  J.Lous      B  Simple dragon curves.
ArcScape            6k  D.Lawrence  B  Landscape generator.
Forest      4.0     2k  M.Curnow    6  Diffusion Aggregation forest.
Fracgen             5k  M.Cook      B  Turtle/L-system fractal generator
FracScape           5k  A.Jones     B  Landscape generator.
Fractals            9k  D.Karunadasa B 9 simple programs covering Bifurcate,
                                       Mandelbrot, Lorenz, Julia, Henon.
Fractals    2.0    14k  S.Hope      B  Good fractal landscape generator,
                                       though no save facility. Slow in
                                       high resolution mode.
FracWalk            1k  M.Cook      B  Diffusion Aggregation generator
Henon               1k  M.Curnow    B  Very simple Henon generator
Lorenz      0.4     6k  M.Attenborough B  Animated Lorenz attractor. Fast,
                                       with 3d control.
Sponge              3k              b  A 3d Sierpinski Gasket generator.
                                       An old BBC program that still looks
                                       great - could do with translating
                                       into ARM to speed it up.
Triang              1k  S.Cockle    B  Diffusion triangle generator.


Utilities & Libraries: Useful graphics programs & programming libraries

Name      Version Size  Author  Source Function
----------------------------------------------------------------------------
!Changefsi  1.18  132k  R.Wilson    N  Converts graphics into other formats.
!Creator    1.02   45k  J.Kortink   N  Sprites to GIF & TIFF format.
                                       Replaces !MakeTIFF/GIF.
!Packer     1.0    11k  M.Curnow    N  Compresses sprite files up to 90%.
!Translatr  6.36  210k  J.Kortink   N  Converts graphics into other formats.
FPLib       1.1     6k  M.Curnow    B  Floating point assembler.
WimpLib     1.1    11k  M.Curnow    B  Wimp procedures for BASIC programs
                                                                        
Also:
Fractint   15.1  1440k  Public      PC C/C++/Assembler source & runtime .exe
PC programs using Integer/FP Mandelbrot+ generator. Tons of material but you
really need a 386 PC with VGA to start to use this. It will run under the
Archie PC emulator in CGA mode but the image qulaity will be poor. I got it
for the source, though unfortunately they are moving towards C++ because of
the size (I've only got TurboC 2.0). There is about 2.5Mb of material here,
compressed onto 2 720k PC disks. A goldmine if you have the time to start
digging or have access to a fast PC. I'm jealous that the Archie is not
supported in such a way - maybe AFG can change that.


What Next?
==========
If the sample programs on this disk have wetted your appetite for more, then
contact me to start the real exploration. To show your commitment I request
that you send a disk with material you have collected or written. AFG
membership is open to those prepared to push back the frontiers, not coffee
table browsers looking to impress their friends.

It may be a little while before the next newsletter comes out to allow time
for this one to be sent around the various magazines to attract membership.
So please be patient initially, especially if you were expecting loads of
software. It will be here, but it will take a little time to collect and
collate it.

Anyway, I would like to here from any Archimedes owner even on non-Fractal
related matters. Contact me at the address at the end of this newsletter.

Contacts And Retail Outlets
===========================
Strange Attractions, 209 Kensington Park Road, London - shop, mostly into
selling pretty pictures and some PC software.

FraChaos, Higher trensgove, Constantine, Falmouth, Cornwall TR11 5QR: mail
order shop, lots of PC software, calendars, books etc.

Fractal Report: bi-monthly newsletter from RTL, West Towen House,
Porthtowan, Cornwall TR4 8AX. Ask for a sample issue. Contains short
routines mostly written in BASIC. A great place to pick up ideas. Some of
them will crop up in the AFG library when I get to converting them to the
Arc.

PS - Please mention AFG when corresponding with these places - they are
promoting AFG.


Final Boring Copywright Notice
==============================
The copywright of all material remains with the authors in all cases. The
material AFG distributes is PUBLIC DOMAIN and may be used freely as you
please. It may be passed on to others as long as NO CHARGES ARE LEVIED
except to cover costs.


And now I must go and write the documentation for my programs, since I have
to set a good example.

Mike Curnow, 26th May 1991
30 Bowen Drive,
West Dulwich,
London
SE21 8PN
Tel. 081-670-8818
                       
                   <<<< MAY THE CHAOS BE WITH YOU! >>>>
