@c focus.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: focus.texi,v 1.4 2004/01/12 18:35:47 lfinsto1 Exp lfinsto1 $
 
@node Focus Reference, Line Reference, Point Reference, Top
@chapter Focus Reference

@tindex Focus
Class @code{Focus} is defined in @file{points.web}.
@code{Focuses} are used when creating a perspective projection.  
They represent the center of projection and can be thought of like a
camera viewing the scene.

@menu
* Focus Data Members::          
* Focus Global Variables::      
* Focus Constructors and Setting Functions::  
* Focus Operators::             
* Modifying Focuses::           
* Querying Focuses::            
* Showing Focuses::             
@end menu
    
@node Focus Data Members, Focus Global Variables, Focus Reference, Focus Reference
@section Data Members

@deftypevr {Private variable}  Point position
The location of the @code{Focus} in the world coordinate system.
@end deftypevr 

@deftypevr {Private variable}  Point direction
The direction of view from @code{position} into the scene.
@end deftypevr 

@deftypevr {Private variable}  Point up
The direction that will be at the top of the projected drawing.
@end deftypevr 

@deftypevr {Private variable}  real distance
The distance of the @code{Focus} from the plane of projection.
@end deftypevr 

@deftypevr {Private variable}  real angle
Used for determining the @code{up} direction.
@end deftypevr 

@deftypevr {Private variable}  char axis
The main axis onto which the @code{Focus} is transformed in order to
perform the perspective projection, z by default.

It will normally not matter which axis is used, but it might be
advantageous to use a particular axis in some special situations.
@end deftypevr 

@deftypevr {Private variable}  Transform transform
The @code{Transform}, which will be applied to the @code{Shapes} on the
@code{Picture}, when the latter is output.  The effect of this is
equivalent to transforming the @code{Focus}, so that it lies on a major
axis. 

@example
Focus f(5, 5, -10, 2, 4, 10, 10, 180);
@result{} 
@end example
@iftex 
@tex 
$$f.{\tt transform} \equiv
\pmatrix{0.989& -0.00733&  -0.148& 0\cr
             0&    0.999& -0.0494& 0\cr
         0.148&   0.0488&   0.988& 0\cr
         -3.46&    -4.47&   0.865& 1\cr}$$
@end tex
@end iftex
@ifnottex 
@display 
@code{f.transform} @equiv{}  
 0.989  -0.00733  -0.148  0
 0       0.999    -0.0494 0
 0.148   0.0488    0.988  0
-3.4    -4.47      0.865  1

@end display
@end ifnottex 
@end deftypevr 

@deftypevr {Private variable}  Transform persp
The @code{Transform} representing the perspective transformation for a
particular @code{Focus}.
Let @math{d} stand for @code{distance}, then   
@iftex 
@tex 
$${\tt persp} \equiv \pmatrix{1&0&0&0\cr
                    0&1&0&0\cr
                    0&0&0&1/d\cr
                    0&0&0&1\cr}$$
@end tex
@end iftex
@ifnottex 
@display 
@code{persp} @equiv{} 
1 0 0  0
0 1 0  0
0 0 0 1/d
0 0 0  1
@end display
@end ifnottex 
@end deftypevr 

@node Focus Global Variables, Focus Constructors and Setting Functions, Focus Data Members, Focus Reference
@section Global Variables

@deftypevar Focus default_focus
Effectively, the default @code{Focus} in @code{Picture::output()}.
@xref{Picture Output Functions,,Picture Reference; Outputting; Functions}. 
It's not really the default, but the version of 
@code{output()} that doesn't take a 
@code{Focus} argument calls another version
that does take one, passing @code{default_focus} to the
latter as its @code{Focus} argument.

It's necessary to do this in such a roundabout way, 
because @code{Picture::output()} must be declared before 
@code{class Focus} is completely defined and @code{default_focus} is declared. 

The declaration @samp{Focus& f = default_focus;} makes @code{f} a
reference to @code{default_focus}, i.e., it makes @code{f} another name
for @code{default_focus}.  This may be convenient, if you don't feel
like typing @code{default_focus}.  
@end deftypevar

@node  Focus Constructors and Setting Functions, Focus Operators, Focus Global Variables, Focus Reference
@section  Constructors and Setting Functions

@deftypefn {Default constructor} void Focus (void)
Creates an empty @code{Focus}
@end deftypefn

@deftypefn {Constructor} void Focus ({const real} @var{pos_x}, {const real} @var{pos_y}, {const real} @var{pos_z}, {const real} @var{dir_x}, {const real} @var{dir_y}, {const real} @var{dir_z}, {const real} @var{dist}, [{const real} @var{ang} = 0, [char @var{ax} = 'z']])
Constructs a @code{Focus} using the first three @code{real} arguments as
the x, y, and z-coordinates of @code{position}, and the fourth through the
sixth argument as the x, y, and z-coordinates of @code{direction}.  @var{dist}
specifies the distance of the @code{Focus}
from the plane of projection, @var{ang} the angle of rotation, which affects which
direction is considered to be ``up'', and @var{ax} the major axis to
which the @code{Focus} is aligned.
@end deftypefn

@deftypefn {Setting function} void set ({const real} @var{pos_x}, {const real} @var{pos_y}, {const real} @var{pos_z}, {const real} @var{dir_x}, {const real} @var{dir_y}, {const real} @var{dir_z}, {const real} @var{dist}, [{const real} @var{ang} = 0, [char @var{ax} = 'z']])
Resets an existing @code{Focus}.  Corresponds to the constructor above.
@end deftypefn

@deftypefn {Constructor} void Focus ({const Point&} @var{pos}, {const Point&} @var{dir}, {const real} @var{dist},  [{const real} @var{ang} = 0, [char @var{ax} = 'z']])
Constructs a @code{Focus} using @code{Point} arguments for
@code{position} and @code{direction}.  Otherwise, the arguments of this constructor
correspond to those of the one above.
@end deftypefn

@deftypefn {Setting function} void set ({const Point&} @var{pos}, {const Point&} @var{dir}, {const real} @var{dist}, [{const real} @var{ang} = 0, [char @var{ax} = 'z']])
Resets an existing @code{Focus}.  Corresponds to the constructor above.
@end deftypefn

@node Focus Operators, Modifying Focuses, Focus Constructors and Setting Functions, Focus Reference
@section Operators

@deftypefn {Assignment operator} {const Focus&} operator= ({const Focus&} @var{f})
Sets the @code{Focus} to @var{f}.
@end deftypefn

@node Modifying Focuses, Querying Focuses, Focus Operators, Focus Reference
@section Modifying

@deftypefun void reset_angle ({const real} @var{ang})
Resets the value of @code{angle} and recalculates the @code{Transforms}
@code{transform} and @code{persp}. 
@end deftypefun

@node Querying Focuses, Showing Focuses, Modifying Focuses, Focus Reference
@section Querying 

@deftypefn {Inline @code{const} function} {const Point&} get_position (void)
Returns @code{position}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const Point&} get_direction (void)
Returns @code{direction}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const real&} get_distance (void)
Returns @code{distance}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const Point&} get_up (void)
Returns @code{up}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const Transform&} get_transform (void)
Returns @code{transform}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const real&} get_transform_element ({const unsigned int} @var{row}, {const unsigned int} @var{column})
Returns an element of @code{transform}, given two @code{unsigned ints} for the row 
and the column.
@end deftypefn

@deftypefn {Inline @code{const} function} {const Transform&} get_persp (void)
Returns @code{persp}.
@end deftypefn

@deftypefn {Inline @code{const} function} {const real&} get_persp_element ({const unsigned int} @var{row}, {const unsigned int} @var{column})
Returns an element of @code{persp}, given two @code{unsigned ints} for the row 
and the column.
@end deftypefn

@node Showing Focuses,  , Querying Focuses, Focus Reference
@section Showing 

@deftypefn {@code{const} function} void show ([{const string} text_str = "Focus:", [{const bool} show_transforms = false]])
Prints @var{text_str} to standard output (@code{stdout}), then calls
@code{Point::show()} on @code{position}, @code{direction}, and
@code{up}.  Then the values of @code{distance}, @code{axis}, and
@code{angle} are printed to @code{stdout}.  If @var{show_transforms} is
@code{true}, @code{transform} and @code{persp} are shown as well.
@end deftypefn
