**************************************************************************
**************************************************************************
             LINK INCLUDE FILE FOR PERSISTENCE OF VISION 3.x
**************************************************************************
**************************************************************************

Created by Chris Colefax, 20 April 1998

1.0  INSTALLATION
2.0  QUICK START
3.0  LINK OPTIONS
        3.1  link_point1, link_point2
        3.2  camera_sky
        3.3  link_looseness
        3.4  link_object
        3.5  link_count
        3.6  link_size
        3.7  link_twist
        3.8  total_link_twist
        3.9  link_size_turb
        3.10  link_twist_turb
        3.11  link_seed
        3.12  scale_links
        3.13  rotate_links
4.0  CREATING LINK OBJECTS
5.0  TIPS AND IDEAS
        5.1  Texturing the link
        5.2  Creating multiple copies of the same link
        5.3  Speeding up links with many link objects
6.0  COPYRIGHT AND LEGAL INFORMATION
7.0  CONTACTING THE AUTHOR

**************************************************************************


1.0  INSTALLATION
**************************************************************************
Before using the Link Include File, copy Link.inc to one of the
directories (folders) in your POVRay library path.  Normally this is the
INCLUDE sub-directory of the directory where you installed POVRay, so if
you installed POVRay in C:\POVRAY you should copy the files to
C:\POVRAY\INCLUDE.  On a Windows 95 system, this is probably something
like:

   C:\Program Files\POV-Ray for Windows\Include

If you plan to use the sample objects included in LinkObjs.inc (see below),
you can also copy this file to the same directory as Link.inc.

On UNIX and similar systems, where filenames are case-sensitive, you may
have to rename the files so the filenames are all uppercase (ie. LINK.INC).
This will enable you to render the sample files without modification.


2.0  QUICK START
**************************************************************************
The Link Include File allows you to create a link between any two points
in the POVRay universe.  You can set how loose (or tight) you want the
link to be, and use any object you like to create the links, such as
chains, ropes, beads, railway tracks, etc.

Using the Link Include File is as simple as declaring the two points you
want to link together as link_point1 and link_point2, and then including
the file, eg:

   #declare link_point1 = <-100, 50, -45>
   #declare link_point2 = <50, -100, 30>
   #include "LINK.INC"

which will create a link using the default options.  Using any of the
other options is as simple as adding the following line to your scene file,
BEFORE including Link.inc:

   #declare [variable-name] = [value]

substituting the desired variable name and value where appropriate.
Note that Link.inc should NEVER be included at the start of a scene
(like "colors.inc" or "textures.inc").  It should only be included after
first declaring the desired link options.


3.0  LINK OPTIONS
**************************************************************************
This section explains the various options that can be used with Link.inc.

3.1  link_point1, link_point2
*****************************
As mentioned before, these two options specify the two points you wish to
link together, declared as POVRay vectors.  Any two points can be used,
within the limits set by POVRay.

3.2  camera_sky
***************
This vector option specifies the direction of the sky, which controls how
the link hangs between link_point1 and link_point2.  Normally you would
use the same sky direction as used in the POVRay camera {} statement,
although any vector can be used.
The default value of this option is <0, 1, 0>.

3.3  link_looseness
*******************
This option controls how loose (or tight) the link between link_point1 and
link_point2 is.  Values generally range from 0, which gives a tight link
between the two points (ie. a straight line), and upwards, with larger
values giving looser links.  You can use negative numbers for this option,
which will make the link defy gravity and "hang" upwards.

Another way of thinking about this option is to imagine the length of a
tight thread connecting the two link points.  The link_looseness option,
then, specifies how much extra length you add to this thread.  Obviously,
as you add more length to the thread, the thread hangs lower and lower.
Note, however, that this option is only relative to the length between
link_point1 and link_point2, and does not actually specify the length
of the link between them.

The default value of this option is 1, which gives a slightly loose link.

3.4  link_object
****************
This option specifies the object you want to use to create the link
between the two points.  The link is actually created by joining a
string of these objects together, end to end.  Any object allowed by
POVRay can be used, although there are some rules you should follow to
achieve the desired result (see section 4.0).
The default object used is a plain, white cylinder, which creates a
simple line between the two link_points.

3.5  link_count
***************
This option controls how many of the link objects you wish to join
together to create the link between the two points.  Normally, the objects
are automatically scaled to fit the length of the link, ie. the larger
the link_count, the smaller the link objects (and vice-versa).
The default value of this option is 20.

3.6  link_size
**************
Instead of using the link_count option, you can specify directly the size
of the link objects you want to use, eg. if you set link_size to 0.1, the
Link Include File will scale the link_object down to 0.1 of its size, and
then use as many of these link objects as are required to connect
link_point1 and link_point2.  Note, however, that Link.inc will use a
minimum of four link objects, so if you specify a size that is larger than
one quarter of the total link length, Link.inc will use a smaller link_size.

3.7  link_twist
***************
You can use this option to control how much the link objects are twisted,
around their own axis, as they connect link_point1 and link_point2.  You
can either specify the amount of twist in degrees, or use decimal fractions
between -1 and 1, eg. setting link_twist to 0.5 will give each link_object
a half twist (which is the same as setting link_twist to 90).  Positive
numbers give a clockwise twist, while negative numbers give an anti-
clockwise twist.
The default value of this option is 0 (no twist).

3.8  total_link_twist
*********************
Instead of specifying the amount of twist per link_object, you can use this
option to control the total amount of twist for the entire link, specified
in degrees.  For example, setting total_link_twist to 720 will twist the
link between link_point1 and link_point2 by two full revolutions (in a
clockwise direction), no matter how many link objects are required.

3.9  link_size_turb
*******************
You can use this option to add a certain amount of randomness to the size
of each individual link_object.  Values generally range from 0 (no
randomness) to 1, with larger values giving more randomness.  Because the
size of link objects is unequal when you use this option, there may be
slightly fewer or slightly more link objects used then specified by the
link_count option.
The default value of this option is 0 (no randomness).

3.10  link_twist_turb
*********************
You can use this option to add a certain amount of randomness to the twist
applied to each link_object, ranging from 0 (no randomness) and upwards,
with larger values giving a greater amount of randomness.  The randomness
is added to the link_twist or total_link_twist option, so that it is
possible to specify a certain amount of twist using either of these options,
and then to add some extra randomness using the link_twist_turb option.
The default value of this option is 0 (no randomness).

3.11  link_seed
***************
This option controls the random seed number used when you specify values
other than 0 for link_size_turb and/or link_twist_turb.  You can specify
any integer you like, as limited by POVRay.
The default value of this option is 0.

3.12  scale_links
*****************
Normally, the link objects are scaled to fit correctly, depending on the
values set for link_count or link_size.  However, you can set this option
to false to specify that the link objects should not be automatically
scaled.  This is most useful when you want to create animations where the
link_points are moving, as it keeps the size and number of individual
link objects constant, instead of adjusting these values to fit.
The default value of this option is true.

3.13  rotate_links
******************
Normally, each link_object is rotated so that it connects correctly with
the next link_object.  However, you can set this option to false to specify
that the link objects should not be rotated, but that their orientation
should remain constant.  For example, you could create a link_object that
faces downwards (with respect to the sky direction), and setting this
option to false will ensure that each link_object continues to face
downwards when joined together.  Note that the objects will still be
twisted as specified by the link_twist, total_link_twist, and/or
link_twist_turb option.
The default value of this option is true.


4.0  CREATING LINK OBJECTS
**************************************************************************
As mentioned before, any object can be used when specifying the
link_object, including single objects, CSG objects, triangle meshes, etc.
However, to correctly connect the link objects together requires following
certain guidelines.

Basically, the object should be:

   a) orientated along the x-axis
   b) unit sized in length
   c) centred on the origin

The default link_object, then, is a cylinder that fits these criteria:

   cylinder {<-.55, 0, 0>, <.55, 0, 0>, .25 pigment {rgb <1, 1, 1>}}

As you can see, the length of the object is indeed orientated along the
x-axis, and the object is centred on the origin.  However, the object
is slightly longer than unit sized.  This is to allow for overlap of
one link_object and the next, which prevents gaps between link objects
where the link curves tightly.  You can extend the amount of overlap,
depending on the desired effect, eg. the Gold_Chain and Iron_Chain
objects in LinkObjs.inc.  These objects are scaled so that the curved ends
of the chain links extend beyond x * -0.5 and x * 0.5, so that one link
is correctly joined with the surrounding links. On the other hand,
making the link_object shorter than unit sized would result in gaps
between each individual link_object.

You can also change the orientation of the link_object to achieve certain
effects, eg. the Spikes object in LinkObjs.inc.  In this case, the cone
used to create the spike faces in the +y direction, which is perpendicular
to the x-axis.  The result is spikes that extend perpendicular to the
link between link_point1 and link_point2, no matter which direction each
individual link_object is facing in.

Offsetting the link_object from the origin can also be used to achieve
certain effects, particularly when you use the link twisting options, eg.
the Candy_Cane object in LinkObjs.inc.  In this case, two spheres are used,
but both are offset from the origin by a certain amount.  When they are
linked together and a certain amount of twist is applied, the spheres
actually twist around each other, rather than twisting around their own
centres.  A similar method is used with the Bubbles object, which, when
used with the link turbulence options, gives each individual bubble a
random offset from the centre of the link.


5.0  TIPS AND IDEAS
**************************************************************************
This section contains some tips that can be used to speed up the Link
Include File, and some ideas on different ways to use Link.inc.

5.1  Texturing the link
***********************
Normally, you specify a link_object that contains a texture, resulting in
identical copies of each link_object, with identical textures.  However,
you can apply a texture to the entire link using the following method:

   #declare link_object = .... (an object without a texture)
   #declare .... (other link options)
   object {#include "LINK.INC" texture {MyTexture}}

This way, MyTexture is applied to the link objects after they have been
joined and placed into position between the link_points.  You could use this
method with a gradient texture, so that lower link objects have a different
texture than higher link objects, or you could apply other patterned
pigments and/or normals so that these are different for each link object.

5.2  Creating multiple copies of the same link
**********************************************
There is no limit on the number of times you can use Link.inc in a scene
to create different links (provided you have the time and memory to store
and render all the objects).  However, if you want multiple copies of the
same link object transformed in various ways, you can use a similar method
as above:

   #declare link_point1 = <0, 0, 0> #declare link_point2 = <10, 0, 0>
   #declare MyChain = #include "LINK.INC"

   #declare Rot = 0 #while (Rot < 360)
      object {MyChain rotate y * Rot}
   #declare Rot = Rot + 30 #end

This would create a ring of hanging chains, and is much faster (and easier)
than calculating the various link_points required and including Link.inc
multiple times.  You could use this method to create a chandelier, or a
rope ladder, etc.

5.3  Speeding up links with many link objects
*********************************************
The more link_objects you use with a link, the longer the link takes to
create.  You can reduce the time and memory required in a number of ways:

 a) Consider using a less detailed link_object, perhaps by using suitable
    textures (like the Rope object in LinkObjs.inc, which is created with
    one sphere, instead of the Snake object which is created with seven
    spheres).

 b) Try joining a number of links together, and then using these pre-joined
    link objects as one link_object.  This lets you use a smaller link_count
    value, which speeds up the creation of the link, eg:

       #declare link_object = MyObject
       #declare link_count = 100
       #declare ... (other link options)
       #include "LINK.INC"

    becomes:

       #declare link_object = union {
          object {MyObject translate -x * 1.5}
          object {MyObject translate -x * 0.5}
          object {MyObject translate x * 0.5}
          object {MyObject translate x * 1.5}
          scale 1/4}
       #declare link_count = 100/4
       #declare ... (other link options)
       #include "LINK.INC"

    As you can see, joining four objects together (and scaling them down
    by one quarter) means that you can use one quarter of the link_count
    value.  Note, however, that joining too many objects together in this
    way may make the resulting link less accurate, creating unwanted gaps
    between each individual link object.


6.0  COPYRIGHT AND LEGAL INFORMATION
**************************************************************************
The Link Include File package, including Link.inc, all documentation, and
associated sample files are Copyright 1998 by Chris Colefax.  Full
permission is granted to the user to modify any or all of the files for
his/her own use.  If modified versions are to be distributed the user
should make clear the modifications that have been made by him/herself.

The Link Include File package may be bundled with or without other software
on CD-ROM collections, Bulletin Board systems and other file archives,
providing that all associated files, including documentation and samples,
are included.  I would also request that persons intending to distribute
the Link Include File package in this manner or otherwise would first
contact me (see below for contact information) to ensure that they are in
possession of the latest version.

Further, no restrictions of any sort are placed on the usage of the include
file itself (Link.inc), and scene files or images created using the include
file remain entirely the property of the user or users who have created
them.  I claim no liability or responsibility for damages or loss resulting
from usage of the include file, or any part of the include file package.


7.0  CONTACTING THE AUTHOR
**************************************************************************
If you wish to contact me with bug reports, bug fixes, criticisms, 
comments, suggested improvements, questions, etc. you can reach me by 
email at:

   ccolefax@geocities.com

or by regular mail at:

   Chris Colefax
   PO Box 110
   Kuranda, Queensland
   Australia  4872

**************************************************************************

POV-Ray(tm) and Persistence of Vision(tm) are registered trademarks of the
POV-Ray Team(tm)
