-----------------------------------------------------------------------------
                SPLINE MACRO FILE - QUICK OPTIONS REFERENCE
-----------------------------------------------------------------------------
                        for Persistence of Vision 3.5

-----------------------------------------------------------------------------
BASIC USAGE:
 After including "SPLINE.MCR", you should begin by actually declaring your
 spline definition using a list of points and options (see below).  Then,
 to actually use the spline in your scene you can use this declared
 identifier with the spline animation or object creation macros.

USING OPTIONS:
 Note that apart from the spline identifiers you create, and the global
 debug_progress option, there are no other declarable options that affect
 the Spline Macro File.  Instead, you control the macros by including a list
 of added (ie. separated by + signs) options in the macro call, eg:

   #declare MySpline = create_spline (Array_of_Points,
      create_default_spline + spline_tension (-1) + spline_sampling(on))

 Generally, each macro call consists of a comma-separated list of required
 options, followed by a + separated list of options (with values in brackets,
 as shown above).  If you do not wish to use any options, you can simply
 specify default_options in place of the options list.

-----------------------------------------------------------------------------
SPLINE CREATION MACROS:
 #declare SplineID = create_spline ([Point array], [Options])
 #declare SplineID = create_spline_from_file ([Filename], [Options])

SPLINE PREVIEW MACRO:
 preview_spline ([Spline ID], [Options])

SPLINE EVALUATION MACROS (to return information about a spline):
 spline_points ([Spline ID])      // Number of points interpolated
 spline_looping ([Spline ID])     // Boolean
 spline_length ([Spline ID])      // Approximated using sampling
 spline_hull_length ([Spline ID]) // Straight-line distance between points

 spline_value ([Spline ID], [Spline Clock Value])
 even_spline_value ([Spline ID], [Distance along spline])

 evaluate_spline ([Spline ID], [Options])
   Returns spline_pos, spline_tangent, spline_accel, spline_distance values,
           spline_roll, spline_pitch, spline_heading vector rotations

SPLINE ANIMATION MACRO:
 animate_by_spline ([Spline ID], [Options])
   Use with origin centred object/camera to automatically apply spline
   rotations and translations

SPLINE OBJECT CREATION MACROS:
 create_spline_object ([Spline ID], [Options])
   To use, first define a spline_object () macro that performs desired
   actions using any of:

      sPoints, sLoop, sLength, sSteps, sStepSize
      sStep, sProgress, sClock, sPos, sTangent, sAccel, sDist, sRad, sTwist,
      pStep, pProgress, pClock, pPos, pTangent, pAccel, pDist, pRad, pTwist

   and then optionally increments/decrements any one of:

      sStep, sProgress, sDist, sClock

PREDEFINED OBJECT CREATION MACROS:
 pipe_spline ([Spline ID], [Options])  // Uses cylinders/cones and spheres
 blob_spline ([Spline ID], [Options])  // Uses ellipsoid blob components
 link_spline ([Spline ID], [Options])  // Uses specified link objects
 coil_spline ([Spline ID], [Options])  // Uses torus spirals
 torus_pipe_spline ([Spline ID], [Options])  // Uses torus sections

-----------------------------------------------------------------------------
GLOBAL OPTIONS:
 #declare debug_progress = Boolean;

-----------------------------------------------------------------------------
SPLINE CREATION OPTIONS:
   create_cubic_spline | create_bezier_spline | create_hermite_spline
 + spline_loop (Boolean)
 + spline_tension (Float) + spline_bias (Float) + spline_continuity (Float)
 + spline_TCB (T, C, B)
 + fit_spline_length (Float)    // Desired length of spline in units
 + fit_spline_accuracy (Float)  // Error allowed (in units) for above
 + uniform_spline_times (Boolean)
 + spline_sampling (Float)
 + spline_cache_file (String)
 + spline_file_points (Integer) // Number of points to read from file
 + spline_scale (Vector/Float)
 + spline_rotate (Vector)
 + spline_translate (Vector)

 NOTE: If none of the first three options are specified, the default spline
   is created smoothly joining the list of points (from the first point to
   the last).  The cubic spline option joins from the second point to the
   second-last point (like that used in POV-Ray's lathe object), setting the
   direction at the start and end using the extra points.

   The bezier spline option joins every third point, using the other two
   points in-between to change the shape of the curve.  The hermite spline
   option joins every second point specified, using every other point to
   set the direction of the spline at the point before.

   The sampling option should be specified if you wish to space objects
   evenly along the spline, or animate objects along the spline at a constant
   speed.  Good values start at 1, with higher values giving more accurate
   sampling.  The sampling performance (particularly for animations) can be
   greatly improved by specifying a cache file to read and write from,
   although you will have to delete the file if you wish to change the shape
   of the spline.

   The spline transformation values will always be applied in the order of
   scaling, rotation, followed by translation (regardless of which order they
   are specified in).  Using them when creating a spline transforms the
   spline in memory, so any subsequent uses of the spline use the transformed
   path.  You can also use the scale, rotate, and/or translate options in
   animate_by_spline (), evaluate_spline (), create_spline_object (), or
   any of the predefined spline object macros to transform just that instance
   of the spline path.

-----------------------------------------------------------------------------
SPLINE PREVIEW OPTIONS:
   spline_radius (Float)
 + show_spline_points (Boolean)
 + show_spline_hull (Boolean)
 + show_spline_tangents (Boolean)
 + spline_preview_pigment (Pigment)
 + spline_preview_finish (Finish)
 + spline_connected (Boolean)
 + spline_accuracy (Float) | spline_steps (Integer)

SPLINE ANIMATION/EVALUATION OPTIONS:
   even_spline_spacing (Boolean)
 + spline_clock ([Float function of POV-Ray's clock])
 + auto_banking (Float)
 + max_banking_angle (Float)
 + auto_rotate (Vector/Float)    // Fraction for pitch/heading
 + direction_foresight (Float)
 + banking_foresight (Float)

SPLINE OBJECT CREATION MACROS:
   spline_portion ([Start clock], [Finish clock])
 + spline_steps (Integer) | spline_step_size (Float)
 + spline_radius (Float)
 + spline_step_twist (Float) | spline_total_twist (Float)
 + blob_threshold (Float)          // Blob splines only
 + blob_stretch_factor (Float)     // Blob splines only
 + initial_torus_tangent (Vector)  // Torus pipe spline only
 + auto_rotate (Boolean)           // Link splines only
 + spline_normal_sky (Vector)      // Link splines and/or fit_to_spline_step
 + coil_radius (Float)             // Coil splines only

DECLARABLE OBJECT OPTIONS:
 #declare link_object = Object    // From <-.5, 0, 0> to <.5, 0, 0>
 #declare link_objects = [Array of Objects]

INTERNAL MACRO FUNCTIONS:
 atan3 ([Float1], [Float2]) // as for atan2, but returns value in degrees
                            // and returns 0 for atan3(0, 0)

 vequal ([Vector1], [Vector2])  // true if both vectors are equal
 vzero ([Vector])               // true if vector is of zero length

 torus_arc ([Initial Tangent], [From Point], [To Point], [Radius])
 pipe_spline_object ()
 link_spline_object ([AutoRotate])
 coil_spline_object ([Minor Radius])

 fit_to_spline_step ()  // returns matrix to fit link to current spline step

 NOTE: In addition to a constant spline radius (for pipe, blob, torus pipe,
   and coil splines), you can define a spline_radius_function () macro that
   returns a value using any of the values you would use for the
   spline_object () macro, which is then multiplied by the spline_radius
   value, eg:

 #macro spline_radius_function () sin(4*pi*sProgress) #end
 object {blob_spline (SplineID,
    spline_radius (0.5) + blob_stretch_factor (3))
    pigment {rgb <1, 1, 1>}}
   
-----------------------------------------------------------------------------
                                         Copyright 1999 - 2003, Chris Colefax
