
                         Technical details
                         =================
.˜˜˜˜˜˜˜˜˜˜˜˜.
| Nº | Topic |
'˜˜˜˜+˜˜˜˜˜˜˜'
  01 | Animations and animation viewers
  02 | Exporting textures as JPEGs
  03 | Creating 16 and 24 bpp files
  04 | Menu tree conventions
  05 | Animation Types - details
  06 | Animation Types - file format
  07 | The Mutator
  08 | Breeding
  09 | Three-dimensional sculpting
  10 | Dithering
  11 | Resizing
  12 | Batch processing
  13 | Using !ChangeFSI
  14 | Virtual sprites and layering
  15 | Milking the Freeware version
  16 | Bump mapping


01 Animations and animation viewers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Texture Garden contains extensive options for generating texture animations.
Animations may have variable number of frames, and they may be controlled
by using animation types.

Animations are always replayed cyclicly, but their direction may be reversed by
the user.

Animations may be stored as directories of sprites, or as a single multiple
image sprite file.

When saving animations as directories, Texture Garden does not offer support
for going beyond the 76 file limit imposed by the filecore.  When playing back
such animations, caching of images may be deselected, allowing replay from
disc of animations which would otherwise not fit into memory.  These animations
 may be played back on the backdrop by dragging a directory directly onto
Texture Garden's icon bar icon.

When saving animations as multiple image sprite files, !ChangeFSI post-
processing is not available, and when replaying these animations, there must
be enough memory available to load the whole sequence.

Animations are generated mainly by altering the phase of the pseudo-random
noise which is used in conjunction with filters when performing the program's
fast-fourier-transforms.  Different frequencies are affected differently and
the "Animation Type" specifies the way in which different frequencies are
affected.

Two textures which look exactly the same may animate in different ways even
if the same animation type is chosen; how they animate depends on their
internal constitution, and not on their physical appearance.

The "Texture programmer" may design his own type of animation by using the
"AnimationFrameNumber" variable which changes from &0 to &FFFF during the
animation's course.

Texture Garden's batch processing options may be used for generating sequences
of textures for animation purposes.  This can also be done from the command
line if absolutely required.

Lastly, a word about alternatives to the animation viewing facilities provided.

Among the available Freeware on the platform are "!Picture" (written by mz
Sophie Wilson and available from Acorn's FTP site) and "!Player" (Version
1.00 by Emmet Spier in 1990).  "!Picture" does not cache sprites, but is
simple and neat.

"!Player" works well.  It is slightly faster than my own player due to its
use of optimised plotting routines, it can scale plotted sprites and it has
several other nifty widgets.  It needs to be fed a single multiple image 
sprite file, and it takes its palette from the first sprite in the file.  This
means you will probably need to edit the first sprite of an animation in
!Paint to give it a palette.

"!Picture" too uses the default mode palette if none is specified by the
sprite files.  One way of getting around this is to use the !ChangeFSI
post-processing provided by Texture Garden which automatically adds the
current desktop palette to the file.  Simpler, perhaps is to edit
"!Picture"'s !RunImage program as follows:

3250 spx%=-1:FOR Q%=0TO255:IFpixtrans%?Q%<>Q% spx%=pixtrans%

needs to be changed to:

3250 spx%=-1:FOR Q%=0TO255:REM IFpixtrans%?Q%<>Q% spx%=pixtrans%

or similar (spx% should wind up as -1).


02 Exporting textures as JPEGs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The fact that the program has a back-end interface to !ChangeFSI enables
textures to be exported as JPEGs.  This is useful for use with World Wide Web
pages.  JPEGs are usually to be preferred to GIFs for backgrounds as they
have excellent colour depth and can be compressed very well.  Browsers
lacking JPEG support are now rare.  Some synergy between the Fourier
Transforms used by Textures Garden and the Discrete Cosine Transform used by
JPEG may be partly responsible for this.  Compression is especially important
for backgrounds as they are usually drawn first and consequentlt need to be
downloaded before any navigation of the page can occur.  This is not true of
other images as long as the "width" and "height" attributes are specified in
the <img> tags.

There is explicit support for exporting JPEGs in the program.  Usually the user
can just set the !ChangeFSI option and then select which JPEG options are
required.  These options are overridden by any JPEG output commands specified
in the options string.  For further documentation on the "JPEG" and "JPEGMONO"
options, information is available inside !ChangeFSI.

Unfortunately, although the Computer Concepts "Colour Card Gold" graphics
hardware is supported by Texture Garden, !ChangeFSI (v.1.15) does not recognise
the CC-style 16bpp sprites and consequently fails to convert them to JPEGs
correctly.  It seems to be confused about the aspect-ratio and the 
colour-depth.  The aspect-ratio problem can be overcome using some of
!ChangeFSI's resizing options, but colour-depth problem seems insoluble and
the resulting washed out images are of little use.  Fortunately, a solution is
at hand.  Texture Garden has options for forcing output to be in 16 or 24 bit
colour.  When using these options, the output format follows Acorn's format,
and consequently, !ChangeFSI can deal with the sprites.

When outputting images as JPEGs, it is important to make sure that you generate
them at a high colour depth in the first place.  Using the force 24bpp option
is recommended.  This is because JPEGs are 24 bit images, and using less than
24 bits in the source image actually generates larger files because the colour
quantization introduced by using low colour depths is interpreted as being
sharp edges, which JPEG does not compress well.

Animations may be exported as directories of JPEGs.  These may be played back
using some programs (not Texture Garden), there seems to be little point in
doing this.

03 Creating 16 and 24 bpp files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Texture Garden allows the export of 16 or 24 bit colour sprites from any display
mode.  Old machines will have difficulty displaying these sprites, but they are
recognised by !ChangeFSI.  Versions of RISC OS prior to version 3.5 are too
primitive to display these "deep" sprites.  Fortunately, a patch for the
operating system is available to allow them to be viewed as dithered images on
older hardware.  This is called "Deeper" and is written by Sanjay Pattni.
This patch is a module, and it was distributed recently on September's Acorn
User cover disc.

The versions of the DragASprite module currently in existence do not seem to
operate correctly on these pseudo-deep images.  If this does not look as though
it will be rectified, reverting to dash boxes may be implemented.

Note that palette images are always created in the current mode, and are always
displayed with Floyd-Steinberg dithering.  This may mean, that in modes with
low colour depths they may look different from the textures they refer to.

This is because the textures are using simple dithering (usually for speed),
and so the true colours of the palette are not being represented accurately.

Textures are not recreated in the current mode on a mode change.  A minor tip
if you want a particular texture redrawn in its current position for some
reason is that if you start to drag a texture, and press SHIFT as you drop it
back onto its original position, then it gets redrawn in the current mode.
If you also press ALT, then the texture is completely deleted.  This last may
be of use to those working in conditions of restricted memory.


04 Menu tree conventions
~~~~~~~~~~~~~~~~~~~~~~~~
When navigating through the palettes directory or the directory of animation
types using the menu structures provided, some conventions are used for the
sprites that are displayed on the left-hand side of the menus.

Normally the sprite naming conventions are as follows:

         File(S)    File(L)   Directory(S) Directory(L) App(S)  App(L) 
Plain   :small_abc  file_abc  *name        #name        sm!xyz  !xyz 
Selected:small_abc² file_abc² *name²       #name        sm!xyz² !xyz² 
NoName  :small_xxx  file_xxx  small_dir    directory    sm_app  application 
NoNameS :small_xxx² file_xxx² small_diro   directoryo   sm_appo applicationo

Small sprites are used when they are available; otherwise the large sprite is
scaled.  If the selected version of the sprite is not available then the base
sprite is inverted.  Conventions taken from !FilerPtch are also used.  In
particular, "hidden" files are not displayed, to support the local directory
display options of that program.

When selecting items from the menus, pressing SHIFT or ALT will alter the
effect produced.  Generally SHIFT-clicking will load the file into a text
editor, and ALT-clicking will open a Filer window onto the directory
containing the selected item.  In the case of directories, clicking usually
opens the parent of the directory clicked on.  SHIFT-clicking instead will
open the selected directory itself.


05 Animation Types - details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Animation Types are stored in the "Animatons" directory within Texture Garden.
These control the way Texture Garden generates its animations.

Animations are generated mainly by altering the phase of the pseudo-random
noise which is used in conjunction with filters when performing
fast-fourier-transforms.  Different frequencies are affected differently and
the "Animation Type" specifies the way in which different frequencies are
affected.  Animation Types consist of a series of 1024 signed 4-bit values
which are used as multipliers of the "animation phase" of different
frequencies.  The animation phase is considered as coung from &0 - &FFFF, ie
through one complete cycle in any animation.  If the phase multipliers are
large then the animation will be violent and rapid.  If the multipliers are
zero for all low frequencies then the animation will appear as a series of
small ripples distorting a largely static display.  If the multipliers are
zero for all high frequencies then the animation may look like big waves
distorting an intricately patterned tapestry.  Many different types of
animation are possible using this method.


06 Animation Types - file format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Animation Types are stored as 512 byte files in the "Animatons" directory
within Texture Garden.  Source for several example files is contained in the
"Library.Source.Animations" directory.

The files are made up of 1024 signed 4-bit values.  Low frequency multipliers
are stored first within each byte the lower frequency is in the lower bits
(little endian).


07 The Mutator
~~~~~~~~~~~~~~
When texture Garden mutates a texture into another one, its operation is
quite simple.  It goes through the file and alters some of the numbers in the
texture generation file.  The numbers are chosen according to the "mutation
options" of the last command or function of the program.  These mutation
options are specified by the programmer of the function.  Their possible
values are listed in the "Extensions" file.


08 Breeding
~~~~~~~~~~~
When two textures are mated with one another the program examines the code of
the two textures for the "CreateTwoDimensionalTransform" and
"CreateOneDimensionalTransform" commands.  Breeding mainly affects this type
of command.  If one of the textures lacks both of these commands, then the
two textures will be unable to breed.  For a texture to be fertile, it
follows that it should always contain some such command.

For each occurrence of one of these commands in the "Mother" texture (paying
heed to the "Mutate Colours" and "Mutate Textures" options) a random
parameter of the command is chosen and deleted.  If this parameter is a
function, then all its arguments are also deleted.  A chunk of code is taken
at random from a "Create...Transform" in the "father" code.  This is then
spliced along with any relevant parameters into the mother code at the chosen
point.

The above mechanism allows textures to be of both sexes.  Note that almost
the entire code comes from the "mother" texture, with the father donating a
tiny quantity of code.  At the end of the breeding, the offspring is always
given a new seed (for the pseudo-random number generator).


09 Three dimensional sculpting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Support is provided for the production of three dimensional textures.  These
are of use when textures need to be moulded to the surfaces of solid objects. 
The most frequent application of this is when a texture is required that can
be moulded around the surface of a sphere.

The two commands "DefineSolidBlock(Block_Description)" and
"Sculpture(Path_of_X,Path_of_Y,Path_of_Z)" are used to perform this type of
action.

The "DefineSolidBlock" command defines a solid block of texture in three
dimensions.  "Block_Description" is a function of X,Y, and Z which usually
refers to various buffers using the "Point"-type commands.

The "Sculpture(Path_of_X,Path_of_Y,Path_of_Z)" command sculpts a solid shape
from the solid block of texture described in the last "DefineSolidBlock"
command encountered.  The parameters, "Path_of_X", "Path_of_Y", "Path_of_Z",
define a mapping between X and Y and the three dimensional space.  They are
functions of X and Y.  The resulting shape is stored in the main two
dimensional buffer.  It is usually best to enclose these commands inside the
"StopMutating" and "StartMutating" pair.

One version of the command that defines a sphere is:

Sculpture(
ScaledSignedMultiply(SignedCos(X),Absolute(SignedCos(LogicalShiftRight(Y,&1)))),
SignedCos(LogicalShiftRight(Y,&1)),
ScaledSignedMultiply(SignedSin(X),Absolute(SignedCos(LogicalShiftRight(Y,&1)))))

This is written on three lines to reveal its structure.  It is still quite a
mouthful.  The advantage of specifying the shape explicitly is one of
flexibility.  Smaller and larger spheres are possible, as are different
shapes.


10 Dithering
~~~~~~~~~~~~
There are now a number of dithering options available within Texture Garden.
!ChangeFSI's superlative dithering methods may be used in addition to the
native routines if needed, but in practice this is rarely required.

Texture Garden can use either simple random dithering, or a Floyd-Steinberg
dithering technique.

With simple dithering using the "Dithering(Value)" command, if you use a lot of
dithering to make an image look correct in a sixteen colour mode, then it will
not look much better when changing to a sixteen million colour mode.  A command
is provided to help with this called "ScaledDithering(Value)".  This scales the
degree of dithering to the colour-depth of the current screen mode.

Floyd-Steinberg dithering may only be used in conjunction with the 24 bit
virtual sprite commands.  It makes texture generation more time consuming.

Dithering may also be applied to palettes, where it can be applied separately
to the colours components within whatever colour model is being used.


11 Resizing
~~~~~~~~~~~
As described in the !Help file, dragging with SELECT on the bottom and
right-hand edges of a texture initiates dynamic resizing.

There is something fundamentally square (literally) about the way in which 
Texture Garden produces its extures.  The reason for this is the technical one
that it is often faster to calculate FFTs at a size which is a power of two and
then resize the result, than to do a FFT at the desired size.  If you want
textures that are not square then there are several options available:

If the resized image needs to be displayed for selection in the Texture Garden,
then using the built in resizing commands is strongly recommended.  This is
most easily performed by using the "Resize" command an conjunction with the
"ResizeSprite" command which are provided specifically for the purpose of
resizing textures.  This is the recommended method of resizing textures, and it
is the one used by the front-end provided for this purpose.

If a resize by XFactor and YFactor is required where
(0 < XFactor < &10000, 0 < YFactor < &10000) then a...
"Resize(XFactor, YFactor)" may be issued immediately before any "MakeSprite"
commands are encountered, and a... 
"ResizeSprite(XFactor, YFactor)" needs to occur just before the texture program
terminates.

For the very technically minded the "ResizeSprite" command merely calls the
"TruncateSpriteVertically(Y1,Y2)" and "TruncateSpriteHorizontally(X1,X2)"
commands with their first parameter as zero.  These commands operate on the
sprite generated by the program, chopping off its edges.  Note that although
X1, X2, Y1 and Y2 range from 0 to &FFFF, X = 0, Y = 0 is at the bottom
left-hand corner of the sprite and not, as usual, in the middle of the texture.

Equally technical: when the "Resize" command is issued three commands are built
and issued.  They are roughly as follows
"TwoDimensionalShift(&8000,&8000,Overwrite)"
"TwoDimensionalProcess(0,0,XFactor,YFactor,TwoDimensionalPoint(
   Multiply(&40000 DIV XFactor,LogicalShiftRight(X,&6)),
   Multiply(&40000 DIV YFactor,LogicalShiftRight(Y,&6))),
   Overwrite)".
"TwoDimensionalShift(&8000,&8000,Overwrite)"
This is close to what is actually used to resize the texture.
When corresponding  "TruncateSpriteHorizontally(&0,XFactor)" and 
"TruncateSpriteVertically(&0,YFactor)" are issued, the resulting image should
tessellate, be the right shape and size and breed properly.  It will also
be faster than if the resizing was done using !ChangeFSI, and will have had
anti-aliasing techniques applied to it before translation to the current
colour depth (better).

There are alternative methods available for resizing textures.  It is possible
to resize manually by loading the generated sprite into a bitmap package and
then trim it or resize it to the required size.  Trimming will clearly
prevent seamless tessellation.  Resizing will preserve this, but may introduce
some distortion.  One of the better ways to resize a resulting image is to
use the scaling options of the !ChangeFSI post-processing available.  Using
something like: "**#r 13:16 11:16 -nomode" would produce the desired effect.


12 Batch processing
~~~~~~~~~~~~~~~~~~~
Batch processing is supported by Texture Garden.  If a textfile is dragged to
the icon bar with the appropriate syntax, then it is used as a list of
textures to be processed.  The syntax required for each line is as follows:

<infile> <outfile> <size>

where infile is the path of a texture generation file (note that this should
always be a full path name), outfile is where the resulting sprite should be
written to, and size is the desired size of the texture to be output.  This
should always be a power of two.  Comments are allowed in batch files and they
are taken to be any line starting with a "|".

Texture Garden also has the option to process batchfiles upon receiving a 
request to do so from the command line.  It will only run in the desktop (i.e.
not inside a task window), but it may be called from Obey files.  The syntax is:

"Run !TexturGdn -file <batchfile>".

The reason batchfiles have been supported is to allow maximum flexibility for
those wishing to animate their textures.  It is in principle possible for users
to machine generate a whole series of textures and then process them in bulk.
Users who want to animate their textures in time with music (for example) may
take a series of parameters from a MIDI source, a tracker file, or directly
from the frequency spectrum of music sample and then use these as parameters
when generating an appropriate texture.  If you are engaged in this type of
activity, the author would be very pleased to hear from you.

There is one other command line option available.  This starts up Texture
Garden with no icon bar icon.  The syntax for this is:
"Run !TexturGdn -Remote".


13 Using !ChangeFSI
~~~~~~~~~~~~~~~~~~~         
Post-processing of saved sprites and animations may be controlled by ticking
the "Use !ChangeFSI" option.  

Two system variables are defined when using !ChangeFSI post processing of saved
sprites: "<TextureGdn$File>" which contains the path of the existing sprite
file and "<TextureGdn$Leaf>" which contains the leaf name from the same file. 

The !ChangeFSI-associated string provided contains the command line options
required by this program.  Two special characters are used: "*" and "#". 
Using "*" inserts "<TextureGdn$File> " (note the trailing space) into the
command line string at that point and "#" inserts a string corresponding to the
current mode.

The default setting for the string is "**#r -nomode".  This means that the
existing sprite is overwritten and that processing is performed in the current
screen mode.

If !ChangeFSI does not have enough memory to do its job then it can fail with
unhelpful messages.  If this happens, the sprite will be left as it was when
it was output from Texture Garden.  Please note that the system variable
<TextureGdnChangeFSI$Mem> may be changed in Texture Garden's !Run file.

For further documentation on the options available, information is available
from inside !ChangeFSI.


14 Virtual sprites and layering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Virtual Sprites are 24-bit colour sprites in an internal format.
They are created with the "MakeVirtualSprite(Type_R,Type_G,Type_B)" command
and may be converted to RISC OS sprites using the "MakeSpriteFromVirtualSprite"
command.

This method is useful when creating images by using multiple layers of texture.

Layers may be combined by specifing combination types for the red, green and
blue components of the image using the "Type_R", "Type_G" and "Type_B"
parameters.

It has some drawbacks when compared with the "traditional" method of using
the "MakeSprite" and AddToSprite" commands.

The command is always slightly slower than the original method, and in 2, 4,
16, and 256 colour modes, it is much slower, as currently ColourTrans SWIs
are used to perform the conversion.  Custom routines do the work in modes with
32K and 16M colours, so these are much faster.

Creating a virtual sprite also takes a chunk of memory which would otherwise
not need to be allocated.

However, the range of textures capable of being generated has been massively
increased by the addition of these commands.

More information concerning virtual sprites may be found in the "Language" file.

Sample textures illustrating these new methods are not currently provided with
Texture Garden, but are available separately.


15 Milking the Freeware version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Texture garden has two main limitations: textures edited by hand cannot be
loaded by the program, and the maximum resolution depends on the colour depth.
Both these restrictions are completely removed in the registered version.

The difficulties caused by the colour depth limitation may be minimised by
using custom desktop palettes in 16 and 256 colour modes.  This can be done
because Texture Garden reads its palette from the current screen mode and
does not assume that you are using the default palette.

In a 16 colour mode 256x256 is the maximum size of texture that can be
generated with the freeware version.  This is big enough for most purposes.
If you then choose a custom palette to match a particular texture, the quality
of the produced image can be much improved.

There are a couple of points to mention here:

Firstly, the texture will not be saved with a palette unless !ChangeFSI
post-processing is used, so you will have to add one manually in !Paint.

Secondly, there are probably free programs which will take a 16M colour sprite
and generate the "best fit" 16 or 256 colour palette.  Though unfortunately I
have no details concerning these, such a program would be of use to anyone
contemplating the proceedure described here.

16 Bump mapping
~~~~~~~~~~~~~~~
Most of the information relating to bumpmapping is with the relevant commands
in the language file.

A number of corners have been cut in the ray-tracing routines to provide rapid
texture generation.  Here is a description of some current limitations:

The program's implementation of Phong shading is still quit a lot like Gourad
shading, though the difference is quite noticable.

No true shadowing routines exist, so no part of a texture can cast a shadow on
another part.

Currently there are no ambient reflections from incoming rays, no mirror
effects or translucency.

An approximation to the normals at each point is generated which introduces
some minor non-linear distortion as the height of the light source changes.

Because many bump maps will have tall narrow peaks, shining a light from the
side will produce significantly more illumination than shining one from above.
This is a common cause of oversaturating colours.

All light sources are currently at infinity.  If closer light sources are ever
implemented they will (by their nature) stop textures using them from
tesselating.
