MaryAnn Mandell 2/1/97 changed or modified 
          L n s F l a r e . I N C

   Lens Flare "plug-in" for POV-RAY 3.0

 Copyright (C) 1996           Nathan Kopp

 Version 3.0beta       January 26th, 1997

 Thanks to Chris Colefax (his "Dome City"
           image inspired this)
------------------------------------------

Note:  This file must accompany lnsflare.inc
       in all distributions.


INCLUDED FILES:

lnsflare.txt   This file
lnsflare.inc   The primary lens flare include file
  (These two files must be included in every distribution.)

*************************************************************************
                          *** CONTENTS ***
*************************************************************************

  - Introduction and General Use
  - New features
  - Pre-Defined Flares
  - Hiding your Flare
  - Hints, Tips, and Troubleshooting
  - Legal Stuff
  - Appendix A - Advanced Flare Attributes
  - Appendix B - Primary flare parts breakdown
  - Appendix Z - Addendums


*************************************************************************
                *** INTRODUCTION AND GENERAL USE ***
*************************************************************************

LnsFlare is a very flexible lens flare include file for POV-Ray 3.0.

Adding lens flare to your POV scene is now a simple as adding the 
following few lines to your scene description file:

 #declare cam_loc = <x,y,z>    // use the x, y, and z of your camera
 #declare light_loc = <x,y,z>  // use the x, y, and z of the light
                               // you wish to flare
 #declare lookat = <x,y,z>     // the look_at vector of your camera
 #declare sky_vect = <x,y,z>   // the sky vector of your camera
 #declare flare_type = "35mm"  // or whatever pre-defined flare you like
 #include "lnsflare.inc"       // create the lens flare

LnsFlare will track the specified light_source even in animations as
long as the above variables are equal to the positions of their
respective objects in the scene.  Keep this in mind when you start
rotating and translating lights and the camera.  You may need to use
POV functions such as VROTATE to transform the camera's coordinates
before you call LNSFLARE.  This is also true for the location of
things like the light, the planet, etc.

Example:
  camera {
    location  < 0,  0,  0>
    direction < 0,  0,  1>
    up        < 0,  1,  0>
    right     < 1,  0,  0>
    rotate    <30, 60, 30>
    translate < 5,  3,  4>
  }
  #declare cam_loc = <0, 0, 0>
  #declare cam_loc = vrotate(cam_loc, <30, 60, 30> )
  #declare cam_loc = cam_loc + <5, 3, 4>

There are also three other special variables that can be used to easily
modify the lens flare.  These are:

 - flare_type          Determines a predefined flare type.  See below
                        for available types or use flare_type = "" to
                        create your own.
 - flare_scale_factor  Specifies the scale factor of the lens flare.
                        A value of 2 doubles the flare size, while a
                        value of .5 halves it, as you would expect.
 - flare_amount        This is a number from 0 to 1, 0 being no flare
                        and 1 being the regular amount.
 - show_flare_source   This boolean varable (yes or no value) can be
                        used to make the flare source transparant.  By
                        default, LnsFlare will create a bright spot at
                        the center of the flare.  Use
                          #declare show_flare_source = no
                        to make it more transparant.

The lens flare can be modified in MANY other ways.  See "Appendix A - 
Advanced Flare Attributes" for a reference on available parameters.

*************************************************************************
                       *** NEW FEATURES ***
*************************************************************************

                       >>>> Version 3.0 <<<<

-------------------------------------------------------------------------
1) NEW FLARE TYPES
-------------------------------------------------------------------------
Nine new flare types include "Space2", "Space3", "Camcorder", "85mm",
"Concert", "TV-Day", "Sports", "WarpFlare", and "Sparkle4".  Existing
flare types have been fixed as well.

-------------------------------------------------------------------------
2) EVEN FASTER RENDERING / DISTORTION REMOVED
-------------------------------------------------------------------------
By mapping the textures to discs (rather than spheres), I've increased
render speed even more.  This also removes distortion from certain flare
types.

-------------------------------------------------------------------------
3) RANDOMNESS IN SPARKLE EFFECT
-------------------------------------------------------------------------
Randomness factors have been added to the sparkle attributes of the lens
flares.  Most pre-defined flare types have been modified to reflect this
new feature.

-------------------------------------------------------------------------
4) FLARE STREAKS
-------------------------------------------------------------------------
Two new "streaks" have been added: "streak_a" and "streak_b".  These function
somewhat like "big_glow", but with some slight differences.  See "Appendix 
A - Advanced Flare Attributes" for more information.  They are used to 
produce the realistic "Sprots" flare, as well as adding streaks to "Space2",
"Space3", and "Camcorder".

                       >>>> Version 2.7 <<<<

-------------------------------------------------------------------------
1) NO-ROTATION OPTION
-------------------------------------------------------------------------
Added flare_auto_rotate option.  Setting this variable to false will
cause the flare not to rotate towards the center of the screen.  The
flare will, on the other hand, rotate to always face straight up towards
the top of the image.  You must specify a sky_vect vector for this to
work.  You can then rotate the sparkle from the default position using
the flare_rotate variable.

Note: This changes the big/smallstar and sparkle1/2/3 preset flares.


                       >>>> Version 2.5 <<<<

-------------------------------------------------------------------------
1) SUPER SPEED INCREASE!
-------------------------------------------------------------------------
LnsFlare's render time has been cut drastically.  By mapping the flare
textures to multiple spheres and clipping/bounding them, I've greatly
increased the render speed of the flares.  This is especially noticable
in scenes that use many little lens flares, but also improves render
time on scenes with large flares.  In this new version you should
declare sphere_size only once, if at all.

-------------------------------------------------------------------------
2) HEXAGON SPOTS!
-------------------------------------------------------------------------
Hexagon-shaped lens flare spots can be used in place of the ring- or
dot-shaped spots of previous versions.  Use #declare percent_hex
just like you might use #declare percent_dot.

                       >>>> Version 2.0 <<<<

-------------------------------------------------------------------------
1) HIDE YOUR FLARE!
-------------------------------------------------------------------------
LnsFlare now automatically hides the lens flare when it goes behind a
planet!  While this feature is still limited to only one planet (sphere),
or one plane (for a horizon), it is a _great_ help in animations.  Check
out the included files:
  flare_a.pov and flare_a.ini
for a demonstration.

Use the following to define the planet which your light will go behind:
  #declare planet_loc = <x,y,z>  // x,y,z coordinates of the planet
  #declare planet_rad = r        // the planet's radius

Use the following to define the plane which your light will go behind:
  #declare plane_loc  = <x,y,z>  // x,y,z coordinates of the plane
  #declare plane_norm = <x,y,z>  // normal vector of the plane

For either of the above, you must also define the size of
your light-source:
  #declare light_rad = r         // the radius of the light-source

-------------------------------------------------------------------------
2) SPARKLE ROTATES CORRECTLY!
-------------------------------------------------------------------------
Well, while I was testing the above animation, I realized that the sparkle
on the light-source didn't rotate correctly.  This is now fixed.

-------------------------------------------------------------------------
3) MANY PRE-DEFINED FLARES!
-------------------------------------------------------------------------
For easier use, LnsFlare now comes with 11 pre-defined flare types.
Use the included types or create your own masterpieces!

Pre-defined flares include:
  Space1, SmallStar, BigStar, Sparkle1, Sparkle2, Sparkle3
  35mm, 50mm, 105mm, Sunset1, and Sunset2

For more information on these pre-defined flares, see below.

-------------------------------------------------------------------------
4) NEW ATTRIBUTES!
-------------------------------------------------------------------------
New attributes are marked below (in Appendix A) with a '+'.  These new
options extend the flexibility of the sparkle and add lens flare "dots".

*************************************************************************
                      *** PRE-DEFINED FLARES ***
*************************************************************************

LnsFlare now includes 11 preset lens flares.  To use a preset flare,
declare the "flare_type" variable to the name of the flare (e.g.
#declare flare_type = "35mm").  The variable flare_type is NOT case
sensitive.  Available presets are as follows:

 - Space1
     The Space1 flare is very similar to the default flare.  It four
     pronounced sparkle arms.  It also has smaller and more random
     flare spots.

 - Space2
     This flare looks good for some space animations,
     like exploding stars.  This flare has a horizontal streak and a
     orangish tint to it.

 - Space3
     This flare also looks good for some space
     animations.  It has a horizontal streak and a bluish tint to it.

 - SmallStar
     This flare looks good for adding sparkle to a small distant star.
     It is a very faint flare.

 - BigStar
     This flare looks good for adding sparkle to a star that is closer
     to the camera.  It has a yellowish "glow" to it but retains the four
     faint arms of SmallStar.

 - Sparkle1
     This small flare is great for adding sparkle to a glare or to a small
     light such as a Christmas tree light or a taillight on a car.  It has
     a faint glow and four thin sparkle arms.  This flare should be colored
     by specifying "#declare source_color = <r,g,b>". Default color = <1,1,1>.

 - Sparkle2
     This small flare is similar to Sparkle1, but has 6 arms instead of 4.
     This flare is also bigger and has more of a glow to the light source.
     This flare should also be colored by specifying "#declare source_color
     = <r,g,b>".  Do not oversaturate this color... values like <.5,.5,1> for
     blue is better than <0,0,1>.  Default color = <1,1,1>.

 - Sparkle3
     This small flare is similar to Sparkle2, but has 8 arms instead of 6 and
     also has 16 smaller sparkle arms.  As with the other two sparkles, this
     flare should be colored by specifying "#declare source_color = <r,g,b>".
     Do not oversaturate this color... values like <.5,.5,1> for blue is
     better than <0,0,1>.  Default color = <1,1,1>.

 - Sparkle4
     This small flare produces a more random sparkle effect than the other
     three sparkle flares.  As with the other sparkles, this flare should
     be colored by specifying "#declare source_color = <r,g,b>".

 - WarpFlare
     Looks like a Starship going into Warp.

 - 35mm
     This flare mimics actual 35mm flare.  It's quite complicated.
     Test it to see what it looks like.

 - 50mm
     This flare mimics actual 50mm flare.  It's quite complicated.
     Test it to see what it looks like.

 - 85mm
     This flare mimics actual 85mm flare.  It's quite complicated.
     Test it to see what it looks like.

 - 105mm
     This flare mimics actual 105mm flare.  This bluish flare is
     quite soft and lacks a primary flare ring.  Test it to see what it looks
     like.

 - Camcorder
     This flare mimics the flare created by a camcorder lens.

 - TV-Day
     Mimics the flare from a TV camera looking at the sun on a bright day.

 - Concert
     Looks like the flare from a spotlight at a rock concert.

 - Sports
     This is the lens flare you see at all of the sports events on TV.  Use
     it for bright lights and camera-flashes.  Also good for adding sparkle
     to gems.  Shaped like an "X".

 - Sunset1
     This flare can be used to create a sunset where you wish the flare to
     cover up the light source.  This mimics a previous set of #declares that
     was included in version 1.0.

 - Sunset2
     This flare can be used to model a sunset where the light source is 
     already created and should not be covered up.  This mimics a previous
     set of #declares that was included in version 1.0.

When you use a preset, you cannot change any of the attributes (except for
the source_color of the sparkles).  To make changes, copy the #declares from
LnsFlare.inc and paste them into your code.  Make the proper changes and
then #declare flare_type = "".

*************************************************************************
                    *** HIDING YOUR FLARE ***
*************************************************************************
By default, the lens flare hides when it goes behind the camera.  New in
version 2.0, you can now also hide the flare behind a planet or below the
horizon automatically.  The hiding is slightly limited currently, but it
is a great help in most animations.

To allow the flare to go behind a planet, you must specify the location
of the planet (sphere) and it's radius.
  #declare planet_loc = <x,y,z>  // x,y,z coordinates of the planet
  #declare planet_rad = r        // the planet's radius

To allow the flare to go below the horizon (plane), you must specify the
location and normal vector of the plane.
  #declare plane_loc  = <x,y,z>  // x,y,z coordinates of the plane
  #declare plane_norm = <x,y,z>  // normal vector of the plane

For either of the above, you must also define the size of
your light-source:
  #declare light_rad = r         // the radius of the light-source

If neither of these methods is successful, you can manually hide the
flare by setting the "flare_amount" variable.

*************************************************************************
               *** HINTS, TIPS, AND TROUBLESHOOTING ***
*************************************************************************

Don't forget to keep something visible at the spot of the light_source.
This will still be needed for certain reflections (ex: sunset on water).

LnsFlare will track the specified light_source even in animations as
long as the above variables are equal to the positions of their
respective objects in the scene.  Keep this in mind when you start
rotating and translating lights and the camera.  You may need to use
POV-Ray's vector functions such as VROTATE to find the position
of the the point.  This is also true for the location of things like
the light, the planet, etc.

Example:
  camera {
    location  < 0,  0,  0>
    direction < 0,  0,  1>
    up        < 0,  1,  0>
    right     < 1,  0,  0>
    rotate    <30, 60, 30>
    translate < 5,  3,  4>
  }
  #declare cam_loc = <0, 0, 0>
  #declare cam_loc = vrotate(cam_loc, <30, 60, 30> )
  #declare cam_loc = cam_loc + <5, 3, 4>

Multiple lens flares is OK.  Each time you call "lnsflare.inc", it
checks to make sure the new sphere isn't the same size as the previous
flare sphere.  If it is, it makes the new one 1% _larger_ to avoid
intersection problems.  I suggest that if you set your own sphere_size,
you make sure that you don't use the same size twice.

Sometimes, you may wish to hide the flare behind some complex object
such as a space-ship or a sailboat.  This can usually be done by creating
an imaginary "planet" of an appropriate size.  Then tell the lens
flare to hide behind a planet of that size centered on the ship.

If you experience problems with mirrors or glass turning black, you
may need to increase your #max_trace_level.  This is especially true
if you use more than one lens flare.

Create your own masterpiece lens flares!  But remember, When you use a preset,
you cannot change any of the attributes (except for the source_color of the
sparkle? presets).  To make changes, copy the #declares from LnsFlare.inc
and paste them into your code.  Make the proper changes and then
#declare flare_type = "".

When creating flare for a lens that may or may not be centered on the
camera's look_at point (such as the windshield of a car), simply point
the "lookat" vector towards the center of the lens.  This will correctly
orient both the sparkle arms and the multiple flare spots.

*************************************************************************
                         *** LEGAL STUFF ***
*************************************************************************

Disclaimer:  I am not responsible for anything negative happening to you
as a result of using LnsFlare.  If your dog dies of shock because the flare
is so ugly, too bad.  If space aliens kidnap you because your picture of
them looks too realistic, that's your problem.  Tough luck.

LNSFLARE.INC is provided free of charge.  You may freely distribute it
provided that this file is included.  You may make changes and
fixes to the code as long as you make an addendum to this file and
that you send me a copy of the change/fix.  Also note your change in
the LNSFLARE.INC file.  Please give me (Nathan Kopp)
credit if you use this code.  :)  I can be contacted at one of the
following e-mail addresses:

  nkopp@grfn.org
  nk80300@ltu.edu
  nkopp@sunny.ncmc.cc.mi.us

If none of these work, you can probably contact me via Usenet on:
  comp.graphics.rendering.raytracing

Also check out my web pages:
  http://www.grfn.org/~nkopp/
  http://www.grfn.org/~nkopp/povray.html

This lens flare generator was _inspired_ by Chris Colefax's "Dome City"
image.  The code was originally created by Nathan Kopp on November 3rd,
1996.  Thanks also to God for giving me the time and ability to finish
this project.

*************************************************************************
             *** APPENDIX A: ADVANCED FLARE ATTRIBUTES ***
*************************************************************************

There are many attributes of LNSFLARE that can be modified with simple
#declare statements.  To change these attributes, #declare their new
values prior to the #include "lensflare.inc" statement.

-------------------------------------------------------------------------
PRIMARY FLARE:  (centered on the light source)
-------------------------------------------------------------------------
 The primary flare consists of a bright center which acts as the visible
 light source, since actual point lights are invisible to POV.  Further
 out from the center of the flare is a semi-transparant "glow".  Even
 further out is a ring-flare.  See Appendix A for a breakdown of the
 primary flare's parts.

  source_size   The apparant size of the source.  default = 0.02
  glow_size     The apparant size of the "glow".  default = .15
  ring_size     The apparant size of the "ring".  default = .3
  ring_width    The width of the "ring.           default = .1

    note: Sizes are kind of like a percentage of the overall picture.
          Actual sizes will vary depending on the "distance" setting
          in the camera statement.  A more telephoto lens will create
          larger flares.  This is true for all xxx_size attributes.

  source_color  The color of the light source.  default = rgb <1, 1, 1>
  glow_color    The color of the "glow".  default = rgb <1, 1, .7>
  ring_color    The color of the "ring.  default = rgb <1, .7, .7>
  source_bright The max brightness of the light source.  default = 2
                  Source fades from this brightness to glow_bright.
  glow_bright   The max brightness of the "glow".  default = 1.2
                  Glow fades from this brightness to 1.0.
    note: Brightnesses are multiplied by color to get the final
          color value.

  source_tr     The minimum translucency of the source.  default = .1
  glow_tr       The minimum translucency of the glow.  default = .7
  ring_tr       The minimum translucency of the ring.  default = .8
  source_fade   How fast the source fades off... this is a percentage
                of the distance from source_size to glow_size and is
                where color is glow_color*glow_brightness.  and transmit
                is 1/2 way between source_tr and glow_tr.  Color is
                glow_color*1 at glow_size.

 The "big glow" is a new flare attribute to version 2.0.  It is basically
 a large flare glow that is unaffected by the other parts of the primary
 flare.  It can be larger than the ring size.  By default, it is disabled.
 This was added to create the 35mm and 50mm lens flares.

  big_glow_size  Radius of the "big glow".  default = 0
  big_glow_color The color of the "big glow".  default = <1,1,1>
  big_glow_tr    The minimum translucency of the "big glow".  default = 1

-------------------------------------------------------------------------
FLARE STREAKS
-------------------------------------------------------------------------
 Flare streaks are used to produce streaks of light, usually either
 horizontal or vertical, from the light source.  These streaks get thinner
 as they get farther away, unlike streaks from the sparkle (see below).
 The streaks are produced by mapping a wood texture to a disc and 
 squishing it.

  streak_a_size         The radius of the streak.  default = 0
  streak_a_color        The outer color of the streak.
  streak_a_center_color The center color of the streak.
  streak_a_tr           The minimum transmittance of the streak.
  streak_a_scale        The streak's scale factor (x=width, y=height).
  streak_a_rotate       The rotation of the streak.
  streak_a_auto_rotate  Yes/No - does the flare follow the lens center?

 Similar variables exist for the second streak, "streak_b".

-------------------------------------------------------------------------
SPARKLE AROUND THE LIGHT SOURCE:  (centered on the light source)
-------------------------------------------------------------------------
 The sparkle consists of two sets of radial arms.  The first set should
 be quite large, and start to fade at a distance of star_size. The second
 set is usually more in number but begins to fade at star_size/2.  To
 remove the sparkle, set num_arms and num_arms2 to zero.

  star_size     The distance where the star starts to fade.  default = .2
  star2_size    The size of the second star.  default = .1
  num_arms      The number of arms of the sparkle.  default = 9
  num_arms2     The number of little arms of the sparkle.  default = 9*2
  star_width    The width of each arm.. this is a percent of the total space
                 for each arm.  default = .2
  star2_width   The width of the arms for the second star
  star_color    The color of the sparkle.  default = rgb<1,1,1>
  star_tr       The minimum translucency of the sparkle.  default = .9

  star_rand     Randomness factor for the first sparkle.  default = 0
  star_rand2    Randomenss factor for the second sparkle. default = 0
  star_seed     Seed value for the star.

-------------------------------------------------------------------------
MULTIPLE LENS FLARE SPOTS (and dots):
-------------------------------------------------------------------------
 Multiple lens flares are in a line that passes through the center of
 the picture (lookat point) and the primary flare (light_loc point).
 The flare spots get increasingly farther apart as they get farther from
 the primary flare.  The randomness of various attributes of the spots
 can be set.  The randomness is a percentage of the actual value.
   ex:  a spot_size_rand of .2 means that each spot will be between 80%
        and 120% of it's normal size.
 To turn off the spots set num_spots = 0.

  spot_size        The size of a spot.  default = .1
  spot_color       The color of a spot. default = <1,1,.7>  (faded yellow)
  spot_tr          Minimum translucency of a spot.  default = .9
  num_spots        The number of spots on each side of the flare.
                    default = 4
  spot_dist        Used to compute distances between spots.  Bigger
                    numbers mean farther spaced spots.  default = .2
  spot_dist_pwr    Exponential growth value of the distance between the spots.
                    default = 2  (quadratic)  for linear spots, use 1
  skip_spots       The number of spots to skip (nearest to light source)
  spot_fade_amount Allows the spots to fade as they get farther from the
                    light.  default = 0.  Use small values (like .05)

 In addition to flare spots, LnsFlare 2.0 can create flare "dots".  While
 spots are more transparent on the inside (ring-like look), "dots" are
 more transparent on the outside and less on the inside.  Flare dots are
 generally smaller than the ring-like spots.  Increase "percent_dots" to
 replace some of the flare spots with dots.  New in version 2.1 - lens flare
 spots shaped like hexagons!  Use percent_hex just like you'd use percent_dots.
 Hexagon spots use spot_color, spot_tr, ans spot_size.

  percent_dots    The percent of the spots that are randomly replaced with
                   dots.
  dot_size        The size of a dot.  default = .04
  dot_color       The color of a dot. default = <.4,1,.5>  (faded green)
  dot_tr          Minimum translucency of a dot. default = .75
  percent_hex     The percent of the spots that are randomly replaced with
                   hexagons.


    note: the actual distance between spots depends on the 2D distance
          between the light_source to the look_at points.  The closer
          these points, the closer the spots (as you'd expect).

  spot_size_rand  The randomness of the spots' sizes.  default = 2
  spot_color_rand The randomness of the spots' color.  default = 0
  spot_dist_rand  Randomness of the spots' relative distance. default = 0
  spot_seed       The seed for the above randoms.  default = seed(546)

-------------------------------------------------------------------------
SCALING AND ROTATION FACTORS
-------------------------------------------------------------------------
  flare_scale_factor specify the overall size of the lens flare
                       default = 1.0

  flare_rotate       Rotates the flare an additional amount.  This value
                       is added to the calculated rotational value.  
                       default = 0
  flare_auto_rotate  Determines if the flare should rotate to face the
                      center of the image.  Set to flase to keep the
                      flare sparkle aiming towards the top of the image.

  main_flare_scale   Scale factor for the primary flare (including
                      sparkle).  x=width, y=height.  Default = <1,1,1>
  big_glow_scale     Scale factor for big_glow.  See above

-------------------------------------------------------------------------
MISC
-------------------------------------------------------------------------
Use the following to define the planet which your light will go behind:
  #declare planet_loc = <x,y,z>  // x,y,z coordinates of the planet
  #declare planet_rad = r        // the planet's radius

Use the following to define the plane which your light will go behind:
  #declare plane_loc  = <x,y,z>  // x,y,z coordinates of the plane
  #declare plane_norm = <x,y,z>  // normal vector of the plane

For either of the above, you must also define the size of
your light-source:
  #declare light_rad = r         // the radius of the light-source

Finally, the texture is mapped to a small sphere which is translated to
the camera location.  You can set the radius of the sphere with:
  sphere_size         default = .1

I do not suggest specifying a sphere_size more than once.  LnsFlare will
automatically make sure that no sphere_size is repeated if you only
specify the first size (or none at all).


*************************************************************************
          *** APPENDIX B - PRIMARY FLARE PARTS BREAKDOWN ***
*************************************************************************

  Position                       Color                  Transmit
 ----------------------------------------------------------------------- 
  0                    source_color*source_bright     source_tr
  
  source_size          source_color*glow_bright       source_tr
  
  % from source_size   glow_color*glow_bright         1/2 from source_tr
   to glow_size                                        to glow_tr
  
  glow_size            glow_color                     glow_tr
  
  1/2 from glow_size   glow_color and                 100%
   to ring_size         ring_color
  
  ring_size            ring_color                     ring_tr
  
  1% past ring_size    ring_color                     100%
  

*************************************************************************
                   *** APPENDIX Z - ADDENDUMS ***
*************************************************************************

 (please add notes here if you change the code... include your name
  and the date - also make a similar note in LNSFLARE.INC)
------------------
 Release version 3.0beta 
 - Nathan Kopp   nk80300@ltu.edu   January 26, 1997

