                     ********************************
                                USER MANUAL
                       FOR FS2000 TREES LIBRARY SDK
                           Release 2, 2000-12-17
                     --------------------------------
                                     by
                                Gerrish Gray
                     ********************************

This is the SDK for the construction of scenery using the 'Trees' 
series  of libraries of static scenery objects for the depiction of 
trees in FS2000.

The SDK includes

  -  A series of 24 macros in API format for use with Airport.  May 
     also be useable with other scenery design programs.

  -  An identical series of 24 macros in SCM format for use with
     Abacus's Airport & Scenery Designer 2.1 (C).

The archive containing this SDK also contains an upgrade to the Module 0 
library of generic tree types.


PREPARATION
===========

When you plant real trees, you need to dig some holes and prepare the 
ground.  Then you need to go to the nursery, or maybe select what you want 
from the nursery catalogue.  Well, it's much the same with the FS2000 Trees
library ...

First you must install the library modules correctly.  Please read the
installation instructions.  Because the Trees Library & SDK is based on the
use of 'object libraries', you won't be able to grow any trees until you 
have some 'Trees' library objects to plant.  You will need to install, as a 
minimum, the Module 0 library BGL and accompanying bitmap textures as well 
as this SDK.  If you have not already done so, download TREES_0.ZIP from
the same libraries as you obtained this SDK (sorry, they're not available 
at your local garden nursery!).  Be careful that you keep the TREES_02.BGL 
file supplied with the Release 2 upgrade, though, and delete TREES_0.BGL 
that came with Release 1.  Similarly, keep the TREES_02.TXT index file for
the Upgrade and discard the previous TREES_0.TXT index.

Now you need to do some reading.  The rest of the instructions that follow
below will be a big help (if you don't know what "RTFM"(*) stands for, you
may find that you run into trouble and no trees may grow in the holes you
have dug in your FS2000 scenery project).

It might also help to pay attention to the following :

A. Two other documents provided with the SDK which contain some useful 
   information:-

   SEASONS.TXT - an explanation of Seasonal Effects in FS200 scenery and 
      how they are applied in this kit - you MUST read this file to gain a 
      proper understanding of the complex parameters required by the macros

   HARDZONE.TXT - an explanation of the use of Plant Hardiness Zones in the 
      classification of trees, with an accompanying selection of Plant 
      Hardiness Zone Maps for various parts of the world.  This is NOT
      compulsory reading as the data on plant hardiness zones is provided
      for information only and as an aid in the selection of trees for
      'planting' in scenery for different parts of the world.  In the 
      FS2000 virtual world, any trees will actually survive under any 
      climatic conditions - so plant 'em where you like (as long as you 
      make the appropriate settings in the screens in Airport/ASD).

B. The macros themselves are extensively self-documented.  The header part 
   of these macros (the block of lines starting with semi-colons) should be 
   read by opening the API or SCM files in your favourite text editor.  
   They give a detailed explanation of how each macro works and the 
   parameters it requires.

C. Last, but not least, you need the 'nursery catalogue' of trees you can
   plant.  Each library module comes with an index file called something 
   like TREES_0.TXT that contains a listing of tree objects and the data 
   you need in your favourite scenery design program in order to 'plant' 
   them.  

   Sorry, but there's no pictures in the catalogues.  If you want to see
   what the trees are going to look like, then you can view the texture 
   .BMP files in a suitable file viewer - but please don't mess them up, 
   because they're not ordinary bitmaps and your trees won't grow right if 
   you overwrite the files on disk with images re-written by any ordinary 
   graphics software.

   If you have some tree textures or useable pictures of your own that you 
   think might look good as part of the Trees Library, I would be very 
   grateful if you would send them to me at 
                 gerrish.gray@wimborne-dorset.fsnet.co.uk
   and I'll see about adding them to the catalogue.  I would particularly 
   welcome some more tropical tree types ...


THE MACROS
==========
There are 24 different macros in all, each in the two different formats 
- API for use with Airport etc and SCM for the ASD fans.  A few of the 
API's (those with the suffix '1' to their names) are capable of being used 
with Airport 2.10, but all the more advanced ones need the latest version 
of Airport 2.60 because of the number of user parameters required.  They 
are also capable of being used with many of the other scenery design 
programs now available.

TrSingle    (NOTE: This macro has been renamed in Release 2 to avoid a
                clash with the name of an ASD macro)
            This is the simplest macro and inserts a single tree into the
            scenery at the current 'reference point'.  The catch is that
            you have to specify not only the usual scale and visibility 
            parameters, but also
            (a) which Hemisphere your scenery is located in - use the 
                value 0 for the Northern hemisphere, 1 for 'down under'.
                (If you are using Airport 2.10, this is User Parameter 0.  
                With the newer version of Airport, or with ASD, the 
                parameters (or 'Arguments') are all conveniently labelled.
                Correct setting of this value is needed to ensure that
                your trees don't drop their leaves in spring!
            (b) a 'Latitude Band' 1 to 4 to get the correct seasonal 
                behaviour, like a long snowy winter in Alaska but not in 
                Florida!  See SEASONS.TXT for details.  (This is User 
                Parameter 1 for the Airport 2.10 guys).
            (c) last, but by NO MEANS LEAST, a 'Tree ID' for the specific
                Trees library object that you wish to use.  See below for 
                details on Tree IDs.
            3D GROUPS:  Use this macro with one of the '3D Group' tree 
                types - their IDs all end with a letter rather than a digit
                - to create 18 trees at one go.  But avoid 3D Groups on 
                steep terrain, as the 18 trees will all be one level, and 
                some may end up buried into the hillside while others
                float above the lower slopes, defying Newton's apple.  Not
                a pretty sight, better to stick to individual trees in 
                these circumstances - they will all follow the mesh terrain 
                accurately, even when placed with the 'multiple-tree'
                macros that follow ...

TrLn5_1     This series of macros create straight lines of 5 or 10 trees.
  to        SIMPLE VERSIONS: The macros with a '_1' suffix use a single
TrLn10_4        tree type for all the trees in the line.  They need the same
                parameters to be set as TrSingle plus a fourth value - a
                a Tree Scale (see below).  Note that the original reference 
                point places one end of the line, NOT its centre point.  The 
                Rotation parameter controls the direction.  In Airport, a 
                line of the correct length is drawn on the display and you 
                will find it easy to move along to the end of the line and 
                extend your avenue with another 'TrLn' macro.  It's a bit 
                trickier in ASD - some trial and error might be needed.
            TREE SCALES: In all macros apart from TrSingle, you set the 
                size of the trees independently of the main Scale factor, by 
                setting a separate scale to be applied to the trees.  The
                main Scale parameter is used just to determine the inter-
                tree spacing, with scale=1.0 giving a spacing of 10m.
                The basic 'generic' trees in the Module 0 all start out 10m 
                tall, and you will often want a scale other than 1.  Many 
                mature trees reach 20m (scale=2.0) or more - some, in the 
                giant fir forests of Western America or in Equatorial rain 
                forests, as much as 100m (scale=10).  Young trees might be 
                only 5m (scale=0.5).
            MIXED TREE TYPES:  The '_2' '_3' and '_4' macro types use 
                several mixed tree types in their lines and require an 
                additional pair of 'Tree ID' and 'Tree Scale' parameters for 
                each additional tree type.  Remember that all of the tree 
                types chosen must be available in the Latitude Band set
                for the macro.  This will not be a problem with the Module 0 
                generic trees as they are all available in all latitude 
                bands (with the exception of the palms ... even in FS2000 
                palms won't grow in Fairchild, Alaska!).  But in the add-on 
                modules to follow later, many of the specific tree types 
                will be matched only to appropriate latitude bands - check 
                the 'nursery catalogues' carefully.
            AVENUES & HEDGES: These 'Line' macros are particularly useful
                for creating roadside avenues or hedges.  Use a reduced
                Scale factor to keep the spacing close when creating a hedge 
                - the resulting hedge will be infinitely more realistic than 
                those dreadful 2D things seen in older scenery.  A special 
                library of hedging shrubs is planned as one of the add-on 
                modules to be released later.  Work is already under way.
            NATURAL VARIATION: Even when planted in a neat row, trees have
                a mind of their own (or so the 'earth culture' people tell 
                us!).  They just won't grow to exactly the same height.  
                It's the same in FS2000 using the Trees Library.  Even 
                though you've told all the trees you want them to be 10m 
                tall, say, you'll find that they have each grown to a 
                slightly different size.  How's that for realism?

TrSq5_#     These create 5 x 5 squares of regularly-spaced trees in  a grid
  etc       pattern.  The parameters are the same as for the other macros.
            These macros are good for cultivated orchards and plantations
            where the trees are in neat rows.  One macro 'plants' 25 trees
            at a time - saves an awful lot of work - bet the forestry guys
            wish they could do that!  (But note that these macros won't 
            look brilliant when used with the 3D Groups).  Still can't make
            'em all grow to the same height though !?!

TrIso_#     These are a bit unusual.  They again create 5 x 5 grids of 25
            evenly-spaced trees, but this time the grid is skewed at 60
            to provide isometric spacing between all neighbouring trees.
            This gives a less regimented appearance, whilst still being 
            useful for 'blocking in' whole plantations of trees. They are
            also designed to work particularly well with the 3D Groups, 
            which use a technique from my earlier Treeline macros for FS98 
            to economically represent 18 trees in a single library object.
            A single macro can then be made to plant 450 trees at one go -
            how's that for saving you work!  And much less hit on frame 
            rates than 450 separate trees, too.

TrSt7_1     Now these trees really have got minds of their own!  These
  to        macros grow natural-looking 'stands' of 7 or 20 trees each,
TrSt20_4    arranged in a roughly circular group but with a lot of 
            variation in individual placements and sizes, just like natural
            woodland.  Or, when used with a large Scale for wide spacing, 
            trees scattered across the landscape.  Try several of these
            macros, appropriately spaced out and each with its own 
            different Rotation setting and varying scales, and landscape
            artists could be begging to paint a picture of your scenery in 
            oils ...

Tree IDs
--------
The Tree IDs are listed in the TREES_0.TXT index file ('nursery catalogue'
that accompanies Module 0, or in similar catalogues for the later add-on 
library modules.  

The ID's are all 5-character codes and there are lots to choose from!  With 
Module 0, most ID's will work with any Latitude Band.  The exception is the 
generic palm trees which are only available for use with Bands 1 and 2.  
But in the add-on libraries, many of the special tree types will work only 
in specific Latitude bands.  Failure to observe this rule, or use of any 
Tree ID value not listed in the index files, will result in 'Missing 
Object' errors when opening your scenery in FS2000.

Distribution of Completed Scenery
---------------------------------
You are encouraged to distribute your scenery for the enjoyment of other 
FlightSim enthusiasts by uploading it to one or more of the popular file
libraries maintained at www.flightsim.com, www.avsim.com, etc.

Users of your scenery will also need to install any of the Trees Library 
Modules that you have used.  This will always include the 'generic'
Module 0 as a minimum.  You can 

EITHER direct your users to download the required Library Modules from the 
       same internet file libraries for themselves

OR     you can include the necessary files in your own distribution 
       archive.  You MUST also include the documentation that accompanies
       each library module (apart from the TREES_#.TXT 'catalogue' index)
       and instruct your users to follow the installation instructions 
       contained therein.  

       To keep file sizes down, you MAY, if you wish, include only the
       texture files that your scenery actually uses, rather then the full 
       set, but if you do this then please be VERY careful that you DO 
       include all that are necessary.  You will always need to include the
       BGL(s) which contain the library objects ... and the documentation, 
       please.  (But I would really prefer that you distribute the whole of 
       any Module, if possible).

       Do NOT install the object library BGL's or their accompanying 
       textures in any local scenery folder used for your other files.
       To avoid problems, and clashes with other scenery using the Trees 
       Library, all the library files belong either in the main FS2000 
       scenery & texture folders or in folders within the <FS2000\scenedb> 
       path.


COPYRIGHT
=========
This SDK and the accompanying libraries are released as FREEWARE. 
Copyright (C) 2000 G Gray.

As FREEWARE, you are permitted to use the SDK to create scenery and 
to distribute that scenery free of any charge for the enjoyment of 
other flight simulator enthusiasts, providing that such scenery is 
distributed as Freeware or dedicated to the Public Domain.

You are also permitted to distribute the supporting object libraries
in unaltered form free of any charge to users of Freeware or Public 
Domain scenery based upon them.  The libraries themselves, or any part 
thereof, must always be distributed as Freeware and be accompanied by 
an acknowledgement of the author's copyright (a copy of this file will 
suffice).

Commercial or shareware scenery authors are hereby EXPRESSLY FORBIDDEN 
from using or distributing this library or any part thereof without 
first obtaining a LICENCE for such use or distribution from the 
author.  Any enquiries should be sent by e-mail in the first instance 
to the author as below.


SUPPORT
=======
Please read this documentation thoroughly - if you've got this far, you've
already read most of it, but don't forget the other files and the macro 
headers!  But if you still have any queries or problems after doing so, or 
believe that you have uncovered an error, or simply want to discuss some 
ideas, please feel free to e-mail the author.  I am not always free to 
respond immediately to all enquires, because of pressure of other work, 
(yes, I do have a life as well as a hobby!) but I do endeavour to reply
to everyone in due course.

(*) By the way, the professional software support guys tell me that "RTFM" 
    stands for something to do with reading the manual.  They often mutter 
    it under their breath, apparently, when answering our questions ...


Happy Flight-Simming!

Gerrish Gray
Dec 2000
mailto:gerrish.gray@wimborne-dorset.fsnet.co.uk
