Ray Tracing Box/RAY_CD.mdf/RAYTRACE/FORM/DOCS/TUTOR.DOC

Text File | 1993-11-11 | 19.6 KB | 626 lines

TUTOR.DOC

REGISTRATION.

    This program is FREE, you don't have to register. I would like
some feedback though, you could consider this some sort of
registration if you like. For more info see readme.1st and form.doc.


HOW TO RUN IT

    In it's simplest invocation you can just type "FORM". Don't do
that yet, you would normally supply a filename, try "FORM
SAMPLE1.FRM". Usually form files have a .frm extension and this is
assumed of you do not supply it.

    This should display a sort of staircase in grey on your monitor
with the message "Press any key to continue" splatted all over the
top line. You can abort displaying by pressing <ESC>.

    Press a key, the form program should return your text screen, and
display :-

Zbuffer used DOS Memory
Display took 19.67 secs at resolution 320x200
// sample file
a_spine=box <0.2 , 0.5 , 0.2 > stack 10 in 50% grow 0.2 twist 90;
tweeny_bit = sphere 0.3 stack 1;
tweeny_bit, [a_spine] stack 30 in 75% twist 360;
end;
Zbuffer used DOS Memory

    The first and last lines of this output are really debug messages.

    The second line is self explanatory, the rest of the lines are
the contents of sample1.frm, FORM always displays the text that
produced the form just displayed. It also puts this text into a file
temp.frm, and also at the beginning of any pov file it outputs. Well
you wouldn't want to accidently lose your form would you?  We should
now be able to configure the program so it runs faster and produces a
better quality display.


CONFIGURING

1. DIRECT SCREEN ACCESS

    The default configuration uses the BIOS to perform its display
function, this is extremely slow and limited. So to improve the
display speed you can turn off the "compatibility mode" with the
-bios- command line switch.

    WARNING: As with all screen mechanisms that bypass BIOS there may
be some danger of damage to your monitor, this is very unlikely but
if you are unhappy do not use this command line switch.

    Try running "FORM -bios- sample1" this should have displayed
quite a bit faster. If you saw nothing or something strange then it
looks as if you may (I only say may) be unable to use the faster access,
or higher resolution modes. All is not yet lost, you can try "FORM -bios-
-modex sample1", this uses an alternative (more standard) method of
accessing the VGA screen that is still much faster than BIOS, but
doesn't use the SVGAKIT drivers.

    If "-bios-" or "-bios- -modex" worked then you can edit the line
"bios=no" to "bios=yes" in sstools.ini, and also, optionally, insert the
line "ModeX=yes" set (or set an environment variable "FORM=-bios- -modex")

2. SUPERVGA MODES

    Now we will try higher resolution modes. This will probably only
work if you have a "Super VGA" card.

    Try "FORM -res2 sample1" you should see the same picture but the
edges should be smoother. When you press a key the screen resolution
used will be displayed. This may still be 320x200 if FORM couldn't
find a higher resolution mode for your card.

    If that worked try "FORM -res3 sample1" (you're probably getting
bored of sample1 by now). Again you should see the same picture but
the edges should be smoother still. When you press a key the screen
resolution used will be displayed, and the time taken.

    If -res2 didn't work, then I'm afraid you're stuck with plain old
320x200.  If -res3 didn't work, then I'm afraid you're stuck with
res2.


Res2 tries modes 640x350, 640x400, and 640x480
Res3 tries all res1 and res2 modes and 800x600, 1024x768 and 1280x1024

    You may find that your system supports a higher resolution than
FORM will use, this is probably because FORM couldn't find enough
extended or expanded memory for it's workspace, it will use the
highest resolution that it can.


    To set a resolution as "permanent" edit the sstools.ini file
"screen_res=" line. Don't necessarily pick screen_res=3 as the time
taken to display at the higher resolutions can be annoyingly long. I
use res1 normally, res2 on a 486 (cos they're blindingly fast) and
either res2 or res3 when I'm saving the screen to a file (more about
saving screens in a bit).


Saving the screen

    If you add the command line "-save" the screen will be saved to a
file called TEMP.GIF, you can override the output type and save as a
TGA file with the -t option, you can also override the output
filename if you use -save=filename, (.GIF ot .TGA will be added as
appropriate).


TUTORIAL

Creating your own forms
=======================

    If you do not give FORM a file to process it will accept input
from the keyboard, this is only useful when you are playing around, a
much better method would be to use an editor to edit your form, and a
batch file like FORMED.BAT, which you would run with a filename to
edit.

    FORMED is a simple batch file that runs in an edit/display loop,
so it allows you to progressively change your form. It is also useful
for getting rid of errors, and is probably worth using throughout
this tutorial.  To run try "FORMED TEST.FRM", your editor (taken from
an environment variable "edit" or the batch file edit.bat) will run
up with TEST.FRM as the input file. When you leave your editor FORM
will be run with an input file of TEST.FRM.

    In this tutorial we will assume you are using FORMED.

    Run FORM you will see some text like:

            Copyright message
            Form:
                $Revision: 1.7 $ $Date: 93/11/11 13:00:11 $


    This is pretty much useless information and is there mainly for
my purposes.

SIMPLE FORM SCRIPT

Start up FORMED and enter exactly (FORM is case-sensitive)

            sphere;
            end;

Quit your editor and FORM will display a single sphere in the middle
of the screen.

This is a simple Form script.

    All form descriptions end with the word "end;" This tells FORM
where the end of the input is. FORM will then produce any required
output. If the description just ended without the word "end" no
output would be generated.

    What you instructed FORM to do was to create a form consisting of
a single sphere. Note the semi-colon, this told FORM that the object
had finished and not to try and interpret the next word as part of
the same object.

    Form is blind to spaces, as long as there is at least one space,
tab or newline FORM doesn't care.

    Form also accepts comments (only really useful in files), these
look like "/* comment here */" or "// comment until the end of the
line"

ERRORS

FORM does not come with much error checking, what there is comes in
two flavours.

1. SYNTAX ERRORS

    If you entered somthing wrong FORM will print out something like:
"error on line 2 near:" and then print out the script upto the point
where it failed. The error is usually a missing semi-colon from the
previous word, or a spelling mistake.

2. Program errors.

    As I said FORM does very little error checking, so it can (and
WILL) allow you to enter something that doesn't really make sense to
it (after all it's only a dumb computer). In these cases you will
probably get a beep and a message along the lines of "FPE SIGNAL".
FORM may even return to DOS. All that I can say about your error is
that it probably consisted of one of "bend, twist, or grow" without a
preceeding "stack" ot "list". This explanation will make a little
more sense later.


JOINING

Run FORM again, this time enter

        sphere, box;
        end;

    You got a sphere and a box stacked on top of each other, in FORM
when two objects are separated by a "," they are "joined" end to end.


STACKING

Try     sphere stack 5;
        end;

    This time you get 5 spheres "stacked" on top of each other.
Stacking is not quite the same as joining, but it is similar.

Try     sphere, box stack 5;
        end;

    You get three spheres and two boxes because you asked to stack
them 5 high. The stack works on the sphere, box in order so you get:

    sphere
    box
    sphere
    box
    sphere


NUMBERS

    Now is a good time to make some points about numbers, in FORM
scripts all numbers are floating point, that means that 1.5 is a valid
number anywhere that 1 is valid. BUT if FORM only expects an integer
then the number will be truncated to 1. (e.g. for stack)

    All angles are in degrees, since that is what most people are
used to.

    Expressions are allowed, i.e. 3*360 is a perfectly valid way of
saying three turns of a circle.

    Numbers are as far as I can remember always separated from each
other by a comma or keyword unless they are in an expression as above.

    If you have to enter three numbers together you will almost
certainly need to enclose them in "<" and ">".

STACK TRANSFORMS

    Once you have stacked or joined some objects you can apply some
transformations to them, for example you can "compress" them slightly
e.g.

        sphere stack 10 in 7;
        end;

    This will fit 10 spheres into the space that would have been
occupied by 7. Another way is

        sphere stack 10 in 50%;
        end;

This stacked them into 50% of their original space.


you can bend them

BEND
        sphere stack 10 bend 90;

This bent them so that the last one is bent 90 degrees out of position.

and
TWIST
        box stack 10 twist 45

This twists them around their own axis, similar yet different to bend.

OFFSET TWIST
A variation on twist is:

        sphere stack 40 twist 360 , 1;

in this case the boxes are twisted but not around their own axes, the
second number is the amount of offset.

TWISTX and TWISTZ
    These are two more variations on TWIST, can be nice when combined
with BEND try
        torus stack 20 in 25% twistz -90 bend 180; (see flip.frm)

GROW
        sphere stack 10 grow 0.1;

This "grows" the stack leaving the first item alone, and
progressivly "growing" each item until the last is "grown" by the
specified amount.

other types of grow are:
powered_grow
centered_grow
powered_centered_grow

There is very little difference between these types, but you might
like to play with them later. (I might like to improve the syntax as well)

COMBINATIONS

Twist, bend, grow can be combined in ANY order as in

    sphere stack 40 in 75% twist 45 bend 60 grow 1.3;

NOTE the semi colon at the end , this means that the object is
finished, most commands in FORM finish with a semicolon.

NOTE ALSO if we had entered

    sphere stack 40 in 75% bend 60 twist 45 grow 1.3;

We would have got a different form.

CHANGING SIZES

In FORM there are only four basic objects, the "sphere", the "box",
the "torus", and the "ellipse". All of these have a basic size and
shape. But you are not limited to these defaults, you can set your
own values for radii/proportions.

For example the word "sphere" creates a sphere with a "radius" of
half a unit, the phrase "sphere 1.5", creates a sphere three times as
large. This means we can vary the appearance of a sphere so:

    sphere , sphere 0.8 stack 10;

Will give a stack of alternating large and small spheres.

BOX
    for boxes you can again vary the size as in

    box 1.5;

but you can also turn the box into a brick by specifying three
lengths for it as in:

        box <0.5 , 1.5 , 0.2>;

which gives a box 1 unit across 3 units high and 0.4 units deep.

NOTE the "<" and ">", these are required.

ELLIPSE

    The default ellipse is indistinguishable from a sphere, the
reason spheres are included is simply because they display faster.
Ellipses (or ellipsoids as they should be called) can be modified.
You can specify their width and height, or their size along all three
axes to give smartie and rugby ball shapes.

    e.g.
        ellipse;                     a spherical ellipse
        ellipse 0.5 , 0.1;           an ellipse 0.5 wide, 0.1 high (a smartie)
        ellipse <1.4 , 0.2, 0.34>    an ellipse 1.4 wide, 0.2 high, 0.34 deep.
                                     (rugby ball along x axis)


TORUS

    Toroids, are doughnut shapes, you specify the small radius and
the large radius, defaults are: 0.2 , 0.5. These are quite expensive
computationally, but can give nice hollow stem effects, if you don't
need them to be hollow try ellipse above to achieve a similar effect.

    e.g.    torus;
            torus 0.3, 0.6;


DEFINING YOUR OWN OBJECTS :  named objects

    Unfortunately you cannot define your own primitives as such, but
you can create NAMED OBJECTS. The way to do this is best shown by an
example:-

my_object = sphere stack 10 bend 30;

    This defines an object called "my_object", it will not be
displayed, to display it you would need a line like:

my_object;

    This line actually creates one of my_object for display. Once you
have defined an object you can use it anywhere you like - so you can
now have:

    my_object = sphere stack 10 bend 30;
    my_object , box 5;
    end;

    Not especially useful, but some of the more fun operations can
only be performed using named objects. Another use for named objects
is to speed up display, if you are using a lot of torus or ellipses,
you might use named objects to speed things up like so:

    torus stack 30 bend 20;

    will take x seconds to display on my machine, so I change the
description to read:

    basic_object = ellipse 0.7, 0.5;    // min rad+ maj rad = 0.5+ 0.2 = 0.7
    basic_object stack 30 bend 20;

    this now displays in y seconds. When I am happy with the form I
can now change the first line to read

    basic_object = torus 0.2 , 0.5;

and I get my original picture back again.

SQUARE BRACKETS

    If you include a named object in a list you can optionally turn
it on its side by using "[" object_name "]". This makes the obect
grow out sideways. This is used in SAMPLE1 to get the stair treads.

FAN
===
    This is not very well named, it produces a "dandelion head" effect, try

    ellipse <0.2 , 0.5, 0.2> fan 40 , 180;

    The first value after fan is the number of copies to make, just
like stack.  The second value is the amount of spread to use, 180 is
full spread, 90 gives a hemisphere etc.

    There is an optional third value, "tightness", this gives "pulls"
the individual spikes together, try

    ellipse <0.2 , 0.5, 0.2> fan 40 , 180 , 0.1;

remember you can use named objects wherever you had a simple object,
so you could try:

    sos /* stack of spheres */ = sphere stack 10 bend 20 twist 45;
    sos fan 40 , 180 , 0.1;

It starts taking longer doesn't it, but it does look quite complex
(it is there are now 800 spheres in that picture).

The base in "flagpole.frm" is made from a fan of smartie shaped ellipsoids.

WEB
===
    This on the other hand is well named, it produces a spiders web
effect. It does however work best with previously defined stacks of
objects.

    try
    sos /* stack of spheres */ = sphere stack 10;
    sob /* stack of boxes */ = box stack 10 bend 20 twist 45;
    sos web 3 with sob 4;

there are three more optional values, so for a full web you can get

    OBJECT web SPOKE_NUMBER with DEFINED_OBJECT scale SCALE_NUMBER
    WEBBING_NUMBER HOLE_NUMBER EXCESS_NUMBER (uppercase words
    supplied by you)


    so using the above objects "sob" and "sos" we can get

    sos web 5 with sob scale(2) 10;

    will enlarge the "webbing" to twice its original size.

    sos web 5 with sob 10 hole 0.5

    will leave a hole about half the length of the spokes in the
    middle.

    sos web 5 with sob 10 excess 0.5

    will make the webbing continue on past the end of the spokes for
    a distance of about half the length of the spokes.


    see web1.frm, web2.frm and webgood.frm for examples of this.


HEIGHTLESS OBJECTS

    When an object has been made with WEB or FAN it has no height,
stacking them together has no effect, you MUST place an object in
between them to get them to stack. But what if you don't want to see
an inbetween object, what do you do? Well you can "delete" it so that
it becomes invisible and works just as a spacer. a simple example is:

    sphere , sphere , box, sphere delete 2 delete 4 stack 20;

    will delete the second and fourth objects, giving the effect of a
pair of spaced out spheres and boxes.

BUG: you will probably have to change the above to
    my_obj =    sphere , sphere , box, sphere delete 2 delete 4;
    my_obj stack 5;
to get it to work


Other operations
================
you can

DELETE  x
    this removes the x'th piece from the from.
and
DELETE x..y
    which removes the x to y'th pieces from the from.

useful for getting rid of clutter, or "spacing objects" (I'll get to
these later)


MOVE < x , y , z>
    Moves the whole objects so far x units along the x axis etc. I'm still
not very happy about this command, but it might be usefull.



Spacing Objects

    This is a generic term used for objects used to get round
problems in the system. For example we have made a fan

    sos /* stack of spheres */ = sphere stack 10 bend 20 twist 45 , 0.5;
    nicefan = sos fan 10 , 90, 0.1

and we want to put 5 on top of each other:

    nicefan stack 5;

(press <ESC> if you get bored waiting for it to finish)

that didn't work because fans have no or very little height, we need
to space them around.

so try

    sos /* stack of spheres */ = sphere stack 10 bend 20 twist 45 , 0.5;
    nicefan = sos fan 10 , 90, 0.1
    spaced_fan = nicefan , sphere 5 delete 2;
    // the sphere is just a spacing object and isn't meant to be seen.
    // sphere is radius 5 because if we look closely at sos we can
    // guess it's about 5 units tall (10 * 0.5)
    // alternatively we could have had
    // spaced_fan = nicefan , sos delete 2 // which would have been
    // more accurate

    spaced_fan stack 5;

works fine. Try it yourself without the delete, to see what's going on.


Negative Spacing Objects

This is another workaround, consider:
    a = sphere stack 10 in 10%;
    b = sphere stack 10 in 10%;

then the join in "a,b" should be virtually indistingushable,
unfortunately it isn't, there's no overlap!

so we introduce a negative spacer

    spacer = sphere -0.4 delete 1;
    a,spacer,b;

this then looks OKish. I'll be fixing this problem in a later release.


Textures (POV users only)
========

    FORM does not support textures as such, but it does allow some
level of textures for POV usage. To apply a texture simply put the keyword
texture and the texture name after the object.
e.g.

        sphere texture Red;

textures apply (in POV) to all uncoloured objects, so :

        a_piece = sphere , sphere texture red, box stack 20 texture blue;

        will colour half of the spheres and all the boxes box "blue",
and the remaining sphere will be coloured "red".

Note the above could have been written

        a_piece = sphere, sphere texture red, box stack 20;
        a_piece texture blue;

Also note once textured an object cannot be "repainted".

If the texture you want is not already a predefined one you can
"roll your own" by enclosing it in Quotes for example we could have said:

        a_piece texture "Metal pigment{White}";


Authors Note
============
Texturing is still in it's infancy (introduced at the start of NOV 93), I
still have to fix it so that textures can be applied between transforms.
It can be done in the current version but it doesn't work properly.





Other command line features are described in another document, look for it
as some of the features can be useful.

        [e-mail]

        Andrew Rowbottom