@c utility.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: utility.texi,v 1.6 2004/01/12 18:43:50 lfinsto1 Exp lfinsto1 $

@node Utility Functions, Adding a File, Polyhedron Reference, Top
@chapter Utility Functions

@deftypefun double trunc (double d)
Defined in @file{pspglb.web}.
For some reason, when I compile 3DLDF using GNU CC on a PC Pentium II
XEON under Linux 2.4.4 i686, the standard library function
@code{trunc()} is not available.  Therefore, I've had to write one.
@c
@c !! TO DO: 
@cindex kludge 
@c
This is a kludge!
Someday, I'll have to try to find a better solution to this problem.
@end deftypefun 

@deftypefun {pair<real, real>} solve_quadratic (real @var{a}, real @var{b}, real @var{c})
Defined in @file{pspglb.web}.
This function tries to find the solutions @math{S_0} and @math{S_1} to the
quadratic equation 
@math{ax^2 + bx + c} according to the formulae
@iftex
@tex
$S_0 \equiv (-b + \sqrt{\strut b^2 - 4ac}) / 2a$ and 
$S_1 \equiv (-b - \sqrt{\strut b^2 - 4ac}) / 2a$.
@end tex
@end iftex
@c
@ifnottex
@math{S_0 @equiv{} -b + sqrt(b^2 - 4ac) / 2a)} and 
@math{S_1 @equiv{} -b - sqrt( b^2 - 4ac) / 2a}.
@end ifnottex
@c
Let @code{r} stand for the return value.  If @math{S_0} cannot be found,
@code{r.first} will be @code{INVALID_REAL}, otherwise @math{S_0}.
If @math{S_1} cannot be found,
@code{r.second} will be @code{INVALID_REAL}, otherwise @math{S_1}.

@display
@math{(x + 4)(x + 2) = x^2 + 6x + 8 = 0}
@end display

@example
real_pair r = solve_quadratic(1, 6, 8);
@result{} r.first @equiv{} -2
@result{} r.second @equiv{} -4
@end example

@iftex
@tex
\bigskip
@end tex
@end iftex
@c
@example
real_pair r = solve_quadratic(1, -2, 4);
@result{} r.first @equiv{} INVALID_REAL
@result{} r.second @equiv{} INVALID_REAL
@end example

 
@end deftypefun 

@menu
* Perspective Functions::       
@end menu

@node Perspective Functions,  , Utility Functions, Utility Functions
@section Perspective Functions

@deftypefun void persp_0 ({const real} @var{front_corner_x}, {const real} @var{front_corner_z}, {const real} @var{side_lft}, {const real} @var{side_rt}, {const real} @var{angle_rt}, {const real} @var{f_2_cv}, {const real} @var{gl_2_cv}, [{const real} @var{horizon_lft} = 6, [real @var{horizon_rt} = 0, [real @var{gl_lft} = 0, [real @var{gl_rt} = 0]]]])
Defined in @file{utility.web}.
This function is used for the figure in @ref{The Perspective
Projection}, illustrating a perspective projection as it could be done
by hand.  It draws a rectangle in the ground plane and the construction
lines used for putting it into perspective.  It also labels the
vanishing and measuring points.

The arguments:
@table @var
@item @code{const real} front_corner_x
The x-coordinate of the front corner of the rectangle.
                        
@item @code{const real} front_corner_z
The z-coordinate of the front corner of the rectangle.
                        
@item @code{const real} side_lft
The length of the left side of the rectangle.     
                   
@item @code{const real} side_rt
The length of the right side of the rectangle.     
                        
@item @code{const real} angle_rt
The angle at which the right side of the rectangle recedes to the
horizon. 
                        
@item @code{const real} f_2_cv
The distance from the focus to the center of vision.         
               
@item @code{const real} gl_2_cv
The distance of the ground line to the center of vision.
                        
@item @code{const real} horizon_lft
Default: 6. 
The length of the horizon line leftwards of the center of vision.

@item @code{real} horizon_rt
Default: 0.
The length of the horizon line rightwards of the center of vision.

@item @code{real} gl_lft 
Default: 0.
The length of the ground line leftwards of the line from the focus to
the center of vision.

@item @code{real} gl_rt
Default: 0.
The length of the ground line rightwards of the line from the focus to
the center of vision.
@end table

Example:

@example
persp_0(3, 2, 10, 5, 47.5, 7, 5, 8.5, 9.5, 8.5, 9.5);
@end example

@c
@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{persp_0(3, 2, 10, 5, 47.5, 7, 5, 8.5, 9.5, 8.5, 9.5);} 
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.199.png"
alt="[Figure 199. Not displayed.]"
/>
<br>
<br>
Fig. 199.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 199 not displayed.]
@end ifinfo

@c
@end deftypefun 
