@c intro.texi
  
@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: intro.texi,v 1.11 2004/01/12 18:39:23 lfinsto1 Exp lfinsto1 $

@comment  node-name,  next,  previous,  up
@node Introduction, Contributing to 3DLDF, Top, Top
@chapter Introduction

  
3DLDF is a free software package for three-dimensional drawing written by
Laurence D. Finston, who is also the author of this manual.
It is written in @cpp{} using CWEB and it outputs MetaPost code.

3DLDF is a GNU package. 
It is part of the GNU Project of the 
Free Software Foundation
and is published under the GNU General Public License.
See the website @uref{http://www.gnu.org} for more
information.  
3DLDF is available for downloading from
@uref{http://ftp.gnu.org/gnu/3dldf}.
The official 3DLDF website is 
@uref{http://www.gnu.org/software/3dldf}.
More information about 3DLDF can be found at the author's website: 
@uref{http://wwwuser.gwdg.de/~lfinsto1}.

Please send bug reports to:

@display
@email{bug-3DLDF@@gnu.org} and 
@end display

@c Not currently listing DANTE as a site for downloading. 
@c LDF 2003.11.20.
@c @uref{http://www.dante.de/software/ctan/, the Dante www-server} 

Two other mailing lists may be of interest to users of 3DLDF:  
@email{help-3DLDF@@gnu.org} is for people to ask other
users for help and @email{info-3DLDF@@gnu.org} is for sending
announcements to users.  To subscribe, send an email to the
appropriate mailing list or lists with the word "subscribe" as the
subject. 
The author's website is @uref{http://wwwuser.gwdg.de/~lfinsto1}.

My primary purpose in writing 3DLDF was to make it possible to use
MetaPost for three-dimensional drawing.  I've always enjoyed using MetaPost,
and thought it was a shame that I could only use it for making
two-dimensional drawings.  3DLDF is a front-end that operates on
three-dimensional data, performs the necessary calculations for the
projection onto two dimensions, and writes its output in the form of
MetaPost code.  

While 3DLDF's data types and operations are modelled on those of
Metafont and MetaPost, and while the only form of output 3DLDF currently
produces is MetaPost code, it is nonetheless not in principle tied to
MetaPost.  It could be modified to produce PostScript code directly, or
output in other formats.  It would also be possible to modify 3DLDF so
that it could be used for creating graphics interactively on a terminal,   
by means of an appropriate interface to the computer's graphics
hardware. 

The name  ``3DLDF'' (``3D''  plus the  author's initials)  was
chosen because,  while not  pretty, it's  unlikely to conflict
with any of the other programs called ``3D''-something.  

@menu
* Sources of Information::      
* About This Manual::           
* CWEB Documentation::          
* Metafont and MetaPost::       
* Caveats::                     
* Ports::                       
@end menu

@node Sources of Information, About This Manual, Introduction, Introduction
@section Sources of Information

This handbook, and the use of 3DLDF itself, presuppose at least some
familiarity on the part of the reader with Metafont, MetaPost,
CWEB, and @cpp {}.  If you are not familiar with any or all of them, I
recommend the following sources of information:

@bibskip
@noindent
Knuth, Donald Ervin.
@i{The METAFONTbook}. 
Computers and Typesetting; C.
Addison Wesley Publishing Company, Inc.
Reading, Massachusetts 1986.
@bibskip

@noindent
Hobby, John D.
@i{A User's Manual for MetaPost}.
AT & T Bell Laboratories.
Murray Hill, NJ. No date.
@bibskip

@noindent
Knuth, Donald E. and Silvio Levy.  
@i{The @b{CWEB} System of Structured Documentation}.
@w{Version 3.64---February 2002.}
@bibskip

@noindent
Stroustrup, Bjarne.
@i{The @cpp{} Programming Language}.
Special Edition.
Reading, Massachusetts 2000. 
Addison-Wesley.
@w{ISBN 0-201-70073-5.}
@bibskip

@cindex CTAN (Comprehensive @TeX{} Archive Network)
@cindex Comprehensive @TeX{} Archive Network (CTAN)
The manuals for MetaPost and CWEB are available from the Comprehensive
@TeX{} Archive Network (CTAN).  See one of the following web sites for
more information:

@table @asis
@item Germany 
@uref{http://dante.ctan.org}, @uref{http://ftp.dante.de}@*
@uref{http://www.dante.de}.

@item United Kingdom
@uref{http://www.cam.ctan.org}@*
@uref{http://ftp.tex.ac.uk}.

@item USA
@uref{http://www.tug.ctan.org}@*
@uref{http://www.ctan.tug.org}. 
@end table

@node About This Manual, CWEB Documentation, Sources of Information, Introduction
@section About This Manual

This manual has been created using 
Texinfo, a documentation system which is part of the GNU Project, whose
main sponsor is the Free Software Foundation.  
Texinfo can be used to generate online and printed documentation from
the same input files.  


For more information about Texinfo, see:

@bibskip
@noindent
Stallmann, Richard M. and Robert J. Chassell.  
@i{Texinfo.  The GNU Documentation Format}.  
The Free Software Foundation. Boston 1999.
@bibskip

For more information about the GNU Project and the Free Software
Foundation, see the following web site: @uref{http://www.gnu.org}.  

The edition of this manual is
@value{EDITION} and it documents version @value{VERSION} of 3DLDF.  
The edition number of the manual and the version number of the program
are the same (as of @value{UPDATED}),
but may diverge at a later date.

Note that ``I'', ``me'', etc., in this manual refers to 
Laurence D. Finston, so far the sole author of 
both 3DLDF and this manual.  ``Currently'' and similar formulations
refer to version @value{VERSION} of 3DLDF as of 
@value{UPDATED}.


This manual is intended for both beginning and advanced users of 3DLDF. 
So, if there's something you don't understand, it's probably best to
skip it and come back to it later.
Some of the more difficult points, or ones that presuppose familiarity
with features not yet described, are in the footnotes.  
@c Others are in
@c paragraphs marked by a ``dangerous bend'' sign, familiar from 
@c @cite{The @TeX{}book} and  @cite{The Metafont{}book}, which I've
@c borrowed from Prof.@: Knuth:
@c @tex 
@c \vrule height 14pt depth 8pt width 0pt\raise5pt\hbox{\dbend} 
@c @end tex

I firmly believe that an adequate program with good documentation is
more useful than a great program with poor or no documentation.  The
ideal case, of course, is a great program with great documentation.  I'm
sorry to say, that this manual is not yet as good as I'd like it to be.
I apologize for the number of typos and other errors.  I hope they don't
detract too much from its usefulness.  I would have liked to have
proofread and corrected it again before publication, but for reasons
external to 3DLDF, it is necessary for me to publish now.  I plan to set
up an errata list on 
@uref{http://www.gnu.org/software/3dldf, the official 3DLDF
website}, 
and/or
@uref{http://wwwuser.gwdg.de/~lfinsto1, my own website}.

Unless I've left anything out by mistake, this manual documents all of
the data types, constants and variables, namespaces, and functions
defined in 3DLDF.  However, some of the descriptions are terser than I
would like, and I'd like to have more examples and illustrations. There
is also more to be said on a number of topics touched on in this
manual, and some topics I haven't touched on at all.  In general, while
I've tried to give complete information on the ``what and how'', the
``why and wherefore'' has sometimes gotten short shrift.
I hope to correct these defects in future editions.

@menu
* Manual Conventions::          
* Illustrations::               
@end menu

@node Manual Conventions, Illustrations, About This Manual, About This Manual
@subsection Conventions
@c
Data types are formatted like this:  @code{int}, 
@code{Point}, @code{Path}.  Plurals are formatted in the same way:
@code{ints}, @code{Points}, @code{Paths}.  It is poor
typographical practice to typeset a single word using more than one
font, e.g., @code{int}s, @code{Point}s, @code{Path}s.  This applies to
data types whose plurals do not end in ``s'' as well, e.g.,
the plural of the @cpp {} @code{class Polyhedron} is @code{Polyhedra}. 
  
When @cpp {} functions are discussed in this manual, I always include a
pair 
of parentheses to make it clear that the item in question is a function
and not a variable, but I generally do not 
include the arguments.  For example, if I mention the
function 
@code{foo()}, this doesn't imply that @code{foo()} takes no
arguments.  If it were appropriate, I would include the argument type:

@example
foo(int)
@end example

@noindent
or the argument type and a placeholder name:

@example
foo(int arg)
@end example

@noindent
or I would write

@example
foo(void)
@end example

@cindex member function 
@cindex function, member
@noindent
to indicate that @code{foo()} takes no arguments.  Also, I
generally don't indicate the return type, unless it is relevant.  If it
is a member function
of a class, I may indicate this,
e.g.,, @code{bar_class::foo()}, or not,
depending on whether this information is relevant.  This convention
differs from that used in the @ref{Function Index}, which is generated
automatically by Texinfo.  There, only the name of the function appears,
without parentheses, parameters, or return values.  The class type
of member functions may appear in the Function Index, (e.g.,
@code{bar_class::foo}), but only in index entries that have been entered
explicitly by the author;  such entries are not generated by Texinfo
automatically. 

Examples are formatted as follows:

@example
Point p0(1, 2, 3);
Point p1(5, 6, 7.9);
Path pa(p0, p1);
p0.show("p0:");
@print{} p0: (1, 2, 3)
@end example




@ifnottex 
The beautiful mathematical typesetting produced by @TeX{} 
unfortunately does not appear in the Info and HTML versions of this
manual.  In these, the following symbols are used to replace the proper
mathematical symbols.

@table @asis
@item ^
Precedes a superscript.  For example, read @samp{a^2} as
``a squared''. 

@item _
Precedes a subscript.  For example, read @samp{x_1} as
``x sub one''. 

@item *
Multiplication.  For example, read @samp{x * y} as
``x times y''.

@item sqrt()
The square root function.  For example, read @samp{sqrt(x)} as
``the square root of x''.
@end table



In addition, examples 
@end ifnottex 
@iftex 
Examples
@end iftex
@c
can contain the following symbols:

@table @asis
@item @print{}
Indicates output to the terminal when 3DLDF is
run.  

@item @result{} 
Indicates a result of some sort.  It may precede a illustration
generated by the code in the example.

@item @error{} 
Indicates that the following text is an error message.
@end table

This manual does not use all of the symbols provided by Texinfo.  If you
find a symbol you don't understand in this manual (which shouldn't
happen), see page 103 of the Texinfo manual.

@cindex symbols 
@c
@iftex 
@tex
\bigskip
@end tex
@end iftex
@ifnottex 
@sp 1
@end ifnottex 
@c
@noindent
Symbols:
@table @asis
@item @NATURAL{} 
The set of the natural numbers
@iftex 
@tex
$\{0, 1, 2, 3, 4, \ldots\}$.
@end tex
@end iftex
@c
@ifnottex 
@{0, 1, 2, 3, 4, @dots{}@}
@end ifnottex 

@item @INT{} 
The set of the integers
@iftex 
@tex
$\{\ldots, -3, -2, -1, 0, 1, 2, 3, 4, \ldots\}$.
@end tex
@end iftex
@c
@ifnottex 
@{@dots{}, -3, -2, -1, 0, 1, 2, 3, 4, @dots{}@}
@end ifnottex 


@item @REAL{} 
The set of the real numbers.
@end table

@node Illustrations,  , Manual Conventions, About This Manual
@subsection Illustrations

The illustrations in this manual have been created using 3DLDF.  The
code that generates them is in the Texinfo files themselves, that
contain the text of the manual.  Texinfo is based on @TeX{}, so it's
possible to make use of the latter's facility for writing ASCII text to
files using @TeX{}'s @code{\write} command.

The file @file{3DLDF-@value{VERSION}/CWEB/exampman.web} contains the
@cpp{} code, and the file @file{3DLDF-@value{VERSION}/CWEB/examples.mp} 
contains the MetaPost code for generating the illustrations.
3DLDF was built using GCC 2.95 when the illustrations were generated.
For some reason, GCC 3.3 has difficulty with them.  It works to generate
them in batches of about 50 with GCC 3.3.


@cindex PNG (Portable Network Graphics)
@cindex Portable Network Graphics (PNG)
@cindex PS (PostScript)
@cindex PostScript (PS)
@cindex EPS (Encapsulated PostScript)
@cindex Encapsulated PostScript (EPS)
@c
MetaPost outputs Encapsulated PostScript files.  These can be included
in @TeX{} files, as explained below.  However, in order to display the
illustrations in the HTML version of this manual, I had to convert them
to @uref{http://www.libpng.org/pub/png/index.html, 
PNG (``Portable Network Graphics'') format}.
@xref{Converting EPS Files}, for instructions on how to do this. 

Please note that the illustrations cannot be shown in the Info output
format!  

If you have problems including the illustrations in the printed version,
for example, if your 
installation doesn't have @command{dvips}, look for the following lines
in @file{3DLDF.texi}:

@example
\doepsftrue    %% One of these two lines should be commented-out. 
%\doepsffalse  
@end example

@noindent
Now, remove the @samp{%} from in front of @samp{\doepsffalse} and put
one in front of @samp{\doepsftrue}.  This will prevent the illustrations
from being included.  This should only be done as a last resort,
however, because it will make it difficult if
not impossible to understand this manual.  

The @cpp {} code in an example is not always the complete code used to
create the illustration that follows it, since the latter may be
cluttered with commands that would detract from the clarity of the
example.  The actual code used always follows the example in the Texinfo
source file, so the latter may be referred to, if the reader wishes
to see exactly what code was used to generate the illustration.

You may want to skip the following paragraphs in this section, if you're
reading this manual for the 
first time.  Don't worry if you don't understand it, it's meaning should
become clear after reading the manual and some experience with
using 3DLDF.

The file @file{3DLDF.texi} in the directory 
@file{3DLDF-@value{VERSION}/DOC/TEXINFO}, the driver file for this manual, contains  
the following @TeX{} code:

@example
\newif\ifmakeexamples
\makeexamplestrue     %% One of these two lines should be commented-out. 
%\makeexamplesfalse    
@end example

@noindent
When @command{texi2dvi} is run on @file{3DLDF.texi}, 
@code{\makeexamplestrue} is not commented-out, and 
@code{\makeexamplesfalse} is,
the @cpp {} code for the illustrations is written to the file
@file{examples.web}.  
If the EPS files don't already exist (in the directory
@file{3DLDF-@value{VERSION}/DOC/TEXINFO/EPS}), 
the @TeX{} macro @code{\PEX},
which includes them in the Texinfo files, will signal an error each time
it can't find one.  Just type @samp{s} at the command line to tell
@TeX{} to keep going.
If you want to be sure that these are indeed the only errors, you can
type @samp{<RETURN>} after each one instead. 

@command{texi2dvi 3DLDF.texi} also generates the file
@file{extext.tex}, which contains @TeX{} code for including the
illustrations by themselves.

@file{examples.web} must now be moved to @file{3DLDF-@value{VERSION}/CWEB/} and 
ctangled, @file{examples.c} must compiled, 
and 3DLDF must be relinked.  @command{ctangle examples} also generates
the header file @file{example.h}, which is included
in @file{main.web}.  Therefore, if the contents of @file{examples.h} have
changed since the last time @file{main.web} was ctangled,
@file{main.web} will have to be ctangled, and @file{main.c} recompiled,
before @file{3dldf} is relinked.@c
@c
@footnote{@command{ctangle} creates 
@file{<@i{filename}>.c} from  
@file{@i{<filename>}.web}, 
so the compiler must compile the @cpp {} files
using the @option{-x c++} option.  Otherwise, it would handle them as if
they contained C code.}

Running @command{3dldf} and MetaPost now
generates the EPS (Encapsulated PostScript) files 
@file{3DLDFmp.1} through (currently) @file{3DLDFmp.199} 
for the illustrations.  They must be moved to 
@file{3DLDF-@value{VERSION}/DOC/TEXINFO/EPS}.
Now, when @command{texi2dvi 3DLDF.texi} is run again, the
@command{dvips} command
@samp{\epsffile} includes the EPS files for the illustrations in the
manual.  @file{3DLDF.texi} includes the line @samp{\input epsf}, so
that @samp{\epsffile} works.
Of course, @command{dvips} (or some other program that does the
job) must be used to convert @file{3DLDF.dvi} to  a PostScript file.  
To see exactly how this is done, take a look at the 
@file{.texi} source files of this manual.@c
@c
@footnote{If you want to try generating the illustrations yourself, you
can save a little run-time by calling @command{tex 3DLDF.texi} the
first time, rather than @command{texi2dvi}.  The latter program runs
@TeX{} twice, because it needs two passes in order to generate the
contents, indexing, and cross reference information (and maybe some
other things, too).}  

In the @file{3DLDF.texi} belonging to the 3DLDF distribution,
@code{\makeexamplestrue} will be commented-out, and
@code{makeexamplesfalse} won't be, because the EPS files for the
illustrations are included in the distribution.

The version of @file{examples.web} in @file{3DLDF-@value{VERSION}/CWEB} merely
includes the files @file{subex1.web} and @file{subex2.web}.  
If you rename @file{3DLDF-@value{VERSION}/CWEB/exampman.web} to @file{examples.web},
you can generate the illustrations. 




@node CWEB Documentation, Metafont and MetaPost, About This Manual, Introduction
@section CWEB Documentation 

As mentioned above, 3DLDF has been programmed using CWEB, which is a
``literate programming'' tool developed by 
Donald E. Knuth and Silvio Levy.  @xref{Sources of Information}, for a
reference to the CWEB manual.  
Knuth's @cite{@TeX{}---The Program} and 
@cite{Metafont---The Program} both include a section 
``How to read a WEB'' (pp.@: x--xv, in both volumes).

CWEB files combine source code
and documentation.  Running @command{ctangle} on a CWEB file, 
for example, @file{main.web}, produces the file @file{main.c} containing
C or @cpp {} code.  Running @command{cweave main.web} creates a 
@TeX{} file with pretty-printed source code and nicely formatted
documentation.  I find that using CWEB makes it more natural to
document my code as I write it, and makes the source files easier to
read when editing them.  It does have certain consequences
with regard to compilation, but these are taken care of by @command{make}. 
@xref{Adding a File}, and @ref{Changes}, for more
information. 

The CWEB files in the directory @file{3DLDF-@value{VERSION}/CWEB/} contain the 
source code for 3DLDF.  The file @file{3DLDFprg.web} in this directory
is only ever used for cweaving;  it is never ctangled and contains no
@cpp {} code for compilation.  It does, however, include all of the other 
CWEB files, so that @command{cweave 3DLDFprg.web} generates the @TeX{} file
containing the complete documentation of the source code of 3DLDF.   

The files @file{3DLDF-@value{VERSION}/CWEB/3DLDFprg.tex},
@file{3DLDF-@value{VERSION}/CWEB/3DLDFprg.dvi}, and  
@file{3DLDF-@value{VERSION}/CWEB/3DLDFprg.ps} are
included in the distribution of 3DLDF as a 
convenience.  However, users may generate them themselves, should there
be some reason for doing so, by entering @command{make ps}
from the command line of a shell from the working
directory @file{3DLDF-@value{VERSION}/} or @file{3DLDF-@value{VERSION}/CWEB}.  
Alternatively, the user may generate them 
by hand from the working directory @file{3DLDF-@value{VERSION}/CWEB/} in the
following way: 

@enumerate
@item
@command{cweave 3DLDFprg.web}
generates @file{3DLDFprg.tex}.

@item
@command{tex 3DLDFprg} or @command{tex 3DLDFprg.tex} generates
@file{3DLDFprg.dvi}.

@item
@command{dvips -o 3DLDFprg.ps 3DLDFprg} (possibly with additional options)
generates @file{3DLDFprg.ps}.   

@item
@command{lpr -P<@emph{print queue}> 3DLDFprg.ps} 
sends @file{3DLDFprg.ps} to a printer, on a UNIX or UNIX-like system.
@end enumerate

The individual commands may differ, depending on the system you're
using.  

@node Metafont and MetaPost, Caveats, CWEB Documentation, Introduction
@section Metafont and MetaPost

@cindex Metafont
Metafont is  a system created by Donald E. Knuth for generating fonts,
in particular for use with @TeX{}, his well-known
typsetting system.@footnote{Knuth, Donald E. @emph{The
@TeX{}book}. Computers and Typesetting; A. 
Addison-Wesley Publishing Company. Reading, Massachusetts 1986.}
Expressed in a
somewhat simplified way,  Metafont is a system for programming
curves, which  are then  digitized and  output in  the form of
run-time encoded bitmaps. (See Knuth's @cite{The Metafontbook} for more
information). 

@cindex MetaPost
@cindex EPS (Encapsulated PostScript) 
@cindex Encapsulated PostScript (EPS) 
John D. Hobby  modified  Metafont's  source  code  to  create
MetaPost, which  functions in  much the same way, but outputs
encapsulated PostScript (EPS) files instead of bitmaps.  MetaPost is
very  useful   for  creating  graphics  and  is  a  convenient
interface to  PostScript.   It is also easy both to imbed
@TeX{} code  in MetaPost  programs, for instance, for typesetting
labels, and  to include  MetaPost  graphics  in  ordinary  @TeX{}
files, e.g., by using @command{dvips}.@c
@c
@footnote{Rokicki, Tomas. @emph{Dvips: A
DVI-to-PostScript Translator} February 1997.  Available from CTAN.
@xref{Sources of Information}.}
@c
Apart from simply printing the PostScript file output by 
@command{dvips}, there are many programs that can process ordinary 
or encapsulated PostScript files and convert them to other formats.
Just two of the many possibilities are ImageMagick and GIMP, both of
which can be used to create animations from MetaPost graphics.
@c
@c !! GET REFERENCES TO IMAGEMAGICK AND GIMP!!  Maybe someday I'll do
@c this.  At the moment, I don't feel like looking for any more references.

However, MetaPost  inherited  a  significant  limitation  from
Metafont:  it's not possible to use it for making
three-dimensional graphics, except in a very limited way.
One insuperable problem is the severe limitation on the magnitude
of user-defined numerical variables in Metafont and 
MetaPost.@footnote{@c
@c
@iftex
@tex
``$\lbrack\ldots\rbrack$ 
@end tex
@end iftex
@c
@ifnottex 
``<@dots{}> 
@end ifnottex 
@c
METAFONT deals only with numbers in a limited
range:  A numeric token must be less than 4096, and its value is always
rounded to the nearest  multiple of 
@iftex
@tex
$1\over 65536$.''  Knuth, {\it The METAFONTbook}, p.~50.
@end tex
@end iftex
@c
@ifnottex 
1 / 65536.''  Knuth, The METAFONTbook, p. 50.
@end ifnottex 
}
@c
This
made  sense for Metafont's and MetaPost's original
purposes,  but   they  make   it  impossible  to  perform  the
calculations needed for 3D graphics.

Another problem is the data types defined in Metafont:  Points
are  represented   as  pairs   of  real   values  and   affine
transformations as sets of 6 real values.  This corresponds to
the representation of points and affine transformations in the
plane as  a two-element  vector on  the one  hand  and  a  six
element matrix  on the  other.  While  it  is
possible to  work around  the  limitation  imposed  by  having
points be  represented by  only two  values, it is 
impracticable in   the   case   of   the
transformations.

For these reasons, I decided to write a program that would behave more
or less like Metafont, but with suitable extensions, and the ability to
handle three dimensional data;  namely 3DLDF.  It stores the data and
performs the transformations and other necessary calculations and is not
subject to the limitations of MetaPost and its data types.  Upon output,
it performs a perspective transformation, converting the 3D image into a
2D one.  The latter can now be expressed as an ordinary MetaPost
program, so 3DLDF writes its output as MetaPost code to a file.

In the following, it may be a little unclear why I sometimes refer to
Metafont and sometimes to MetaPost.  The reason is that Metafont
inherited much of its functionality from Metafont.  Certain operations
in Metafont have no meaning in MetaPost and so have been removed, while
MetaPost's function of interfacing with PostScript has caused other
operations to be added.  For example, in MetaPost, @code{color} is a
data type, but not in Metafont.  Unless otherwise stated, when I refer to
Metafont, it can be assumed that what I say applies to MetaPost as well.
However, when I refer to MetaPost, it will generally be in connection
with features specific to MetaPost.

@node Caveats, Ports, Metafont and MetaPost, Introduction
@section Caveats
 
@menu
* Accuracy::                    
* No Input Routine::            
@end menu

@node Accuracy, No Input Routine, Caveats, Caveats
@subsection Accuracy

When 3DLDF is run, it uses the three-dimensional data contained in the
user code to create a two-dimensional projection.
Currently, this can be a perspective projection, or a parallel
projection onto one of the major planes.  MetaPost code representing
this projection is then written to the output file.
3DLDF does no @dfn{scan conversion},@c
@c
@footnote{@dfn{Scan conversion} is the process of digitizing geometric 
data.  The ultimate result is a 
@iftex
@tex
$2\times 2$
@end tex
@end iftex
@c
@ifnottex 
2 X 2
@end ifnottex 
@c
map of pixels, which can be used for printing or representing the projection on a
computer screen.  The number of pixels per a given unit of measurement
is the @dfn{resolution} of a given output device, e.g., 300 pixels per inch.} 
@c 
so all of the curves in the projection are
generated by means of the algorithms MetaPost inherited from Metafont.
These algorithms, however, are designed to find the 
``most pleasing curve''@c
@c
@footnote{Knuth, @cite{The METAFONTbook}, Chapter 14, p.@: 127.} 
@c
given one or more two-dimensional points and connectors;  they do not
account for the the fact that the two-dimensional points are projections
of three-dimensional ones.  This can lead to unsatisfactory results,
especially where extreme foreshortening occurs.  In particular, 
@samp{curl}, @code{dir}, @samp{tension}, and control points should be
used cautiously, or avoided altogether, when specifying connectors.  

3DLDF operates on
the assumption  that, given  an  adequate  number  of  points,
MetaPost will produce an adequate approximation to the desired
curve @emph{in perspective}, since the greater the number of
points given for a curve, the less ``choice'' MetaPost has for
the path  through them.   My  experience with 3DLDF bears this
out.   Generally, the curves look quite good.  Where problems arise, 
it usually helps to increase the number of points in a curve.

A more serious problem is the imprecision resulting from the operation
of rotation.  Rotations use the trigonometric functions, which return
approximate values.  This has the result that points that should have
identical coordinate values, sometimes do not.  
This has consequences for the functions that compare points.
The more rotations
are applied to points, the greater the divergence between their actual
coordinate values, and the values they should have.  So far, I haven't
found a solution for this problem.  On the other hand, it hasn't
yet affected the usability of 3DLDF.

@node No Input Routine,  , Accuracy, Caveats
@subsection No Input Routine

3DLDF does not yet include a routine for reading input
files.   This means  that user  code must  be written  in @cpp {},
compiled, and  linked with  the rest of the program.  I admit,
this is  not ideal, and writing an input routine for user code
is one of the next things I plan to add to 3DLDF.

I plan to use Flex and Bison to write the input routine.@c
@c
@footnote{Flex is a program for generating text scanners and Bison is a 
parser generator.  They are available from
@uref{http://www.gnu.org}.}  
@c
The syntax of the input code should be as close
as possible  to that  of MetaPost, while taking account of the
differences between  MetaPost and 3DLDF.   

For the present, however, the  use of 3DLDF is limited to
those who  feel comfortable  using  @cpp {} and compiling  and
relinking programs.  Please don't be put off by this!  It's not so
difficult, and @command{make} does most of the work of recompiling and
running 3DLDF.  @xref{Installing and Running 3DLDF}, for more
information. 

@node Ports,  , Caveats, Introduction
@section Ports

I originally developed 3DLDF on a DECalpha Personal Workstation with two
processors running under the operating system Tru64 Unix 5.1, using the
DEC @cpp {} compiler.   
I then ported it to a PC Pentium 4 running under Linux 2.4, using
the GNU @cpp{} compiler
GCC 2.95.3, and a PC Pentium II XEON under Linux 2.4, using GCC 3.3.  
I am currently only maintaining the last version.  I do not believe that
it's worthwhile to maintain a version for GCC 2.95.  While I would like 
3DLDF to run on as many platforms as possible, I would 
rather spend my time developing it than porting it. 
This is something where I would be grateful for help from other
programmers. 

Although I am no longer supporting ports to other systems,
I have left some conditionally compiled code for
managing platform dependencies in the CWEB sources of 3DLDF.  This may
make it easier for other people who want to port 3DLDF to other
platforms. 

Currently, the files @file{io.web}, @file{loader.web}, @file{main.web},
@file{points.web}, 
and  @file{pspglb.web} contain conditionally compiled code, depending on 
which compiler, or in the case of GCC, which version of the compiler, is
used.  The DEC @cpp {} compiler defines the preprocessor macro
@samp{__DECCXX} and GCC defines @samp{__GNUC__}.  In order to
distinguish between GCC 2.95.3 and GCC 3.3, I've added the macros
@samp{LDF_GCC_2_95} and  @samp{LDF_GCC_3_3} in @file{loader.web}, which
should be defined or undefined, depending on which compiler you're
using.  In the distribution,  @samp{LDF_GCC_3_3} is defined and 
@samp{LDF_GCC_2_95} is undefined, so if you want to try using GCC 2.95, you'll
have to change this (it's not guaranteed to work).

3DLDF @value{VERSION} now uses Autoconf and Automake, and the
@file{configure} script generates a @file{config.h} file, which is now
included in @file{loader.web}.  Some of
the preprocessor macros defined in @file{config.h} are used to
conditionally include library header files, but so far, there is no error
handling code for the case that a file can't be included.  I hope to improve the
way 3DLDF works together with Autoconf and Automake in the near future.
        
3DLDF 1.1.5 is the first release that contains template functions.  
Template instantiation differs from compiler to compiler, so using
template functions will tend to make 3DLDF less portable.  
@xref{Template Functions}, for more information.
I am no longer able to build 3DLDF on the DECalpha Personal Workstation.
I'm fairly sure that it would be possible to port it, but 
I don't plan to do this, since Tru64 Unix 5.1 and the DEC @cpp {}
compiler are non-free software.  


 

@c Local Variables:
@c mode:Texinfo
@c eval:(outline-minor-mode)
@c End:
