@c path.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: path.texi,v 1.6 2004/01/12 18:39:57 lfinsto1 Exp lfinsto1 $
 
@node Path Reference, Polygon Reference, Plane Reference, Top
@chapter Path Reference

@tindex Path
Class @code{Path} is defined in @file{paths.web}.
It is derived from @code{Shape} using @code{protected} derivation. 

@menu
* Path Data Members::           
* Path Constructors and Setting Functions::  
* Path Destructor::             
* Path Operators::              
* Appending to Paths ::         
* Copying Paths::               
* Clearing Paths ::             
* Modifying Paths ::            
* Affine Transformations for Paths::  
* Aligning Paths with an Axis::  
* Applying Transformations to Paths::  
* Drawing and Filling Paths::   
* Labelling Paths::             
* Showing Paths::               
* Querying Paths::              
* Outputting Paths::            
* Path Intersections::          
@end menu
 
@node Path Data Members, Path Constructors and Setting Functions, Path Reference, Path Reference
@section Data Members

@deftypevr {Protected variable} bool line_switch
@code{true} if the @code{Path} was created using the constructor
@code{Path(const Point& p0, const Point& p1)}, directly or indirectly.
@xref{Path Constructors and Setting Functions,,
Path Reference; Constructors and Setting Functions}. 

@example
Point p0;
Point p1(1, 1);
Point p2(2, 3);
Path q0(p0, p1);
cout << q0.get_line_switch();
@print{} 1
Path q1;
q1 = q0;
cout << q1.get_line_switch();
@print{} 1
Path q2 = p0.draw(p1);
cout << q2.get_line_switch();
@print{} 1
Path q3("..", false, &p1, &p2, &p0, 0);
cout << q3.get_line_switch();
@print{} 0
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point p0;}
\immediate\write\examples{p0.dotlabel("$p_0$", "bot"); }
\immediate\write\examples{Point p1(1, 1);}
\immediate\write\examples{p1.dotlabel("$p_1$"); }
\immediate\write\examples{Point p2(2, 3);}
\immediate\write\examples{p2.dotlabel("$p_2$"); }
\immediate\write\examples{Path q0(p0, p1);}
\immediate\write\examples{Path q1;}
\immediate\write\examples{q1 = q0;}
\immediate\write\examples{Path q2 = p0.draw(p1);}
\immediate\write\examples{Path q3("..", false, &p1, &p2, &p0, 0);}
\immediate\write\examples{q3.draw(black, "evenly");}
\immediate\write\examples{Point p4(p0.mediate(p1));}
\immediate\write\examples{p4.label("$q_0 @DBKS{equiv} q_1 @DBKS{equiv} q_2$", "rt");}
\immediate\write\examples{Point p5(p2);}
\immediate\write\examples{p5.shift(-3, -1);}
\immediate\write\examples{p5.label("$q_3$");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@cindex linear @code{Paths} 
Some @code{Path} functions only work on @emph{linear @code{Paths}}, 
so it's necessary to be able to distinguish them from non-linear ones. 
The function @code{is_linear()} should be enough to ensure that all of
these functions work, so I plan to make @code{line_switch} obsolete
soon.  However, at the moment, it's still needed.
@xref{Querying Paths,, Path Reference; Querying}.
@end deftypevr 

@deftypevr {Protected variable} bool cycle_switch  
@code{true} if the @code{Path} is cyclical, otherwise
@code{false}. 
@end deftypevr 

@deftypevr {Protected variable} bool on_free_store
@code{true} if the @code{Path} was dynamically allocated on the free
store.  Otherwise @code{false}.  Set to @code{true} only in
@code{create_new<Path>()}, which should be the only way @code{Paths} are
ever dynamically allocated.
@xref{Path Constructors and Setting Functions, Path Reference;
Constructors and Setting Functions}.  
@end deftypevr 


@deftypevr {Protected variable} bool do_output 
Used in @code{Picture::output()}.  Set to @code{false} if the @code{Path}
isn't projectable using the arguments passed to
@code{Picture::output()}.
@xref{Outputting Pictures,,Picture Reference; Outputting}.
@end deftypevr 

@deftypevr {Protected variable} {signed short} fill_draw_value 
Set in the drawing and filling functions, and 
used in @code{Path::output()}, to determine what MetaPost code to write
to @code{out_stream}.
@xref{Drawing and Filling Paths, , Path Reference; Drawing and Filling},
and @ref{Outputting Paths,,Path Reference; Outputting}.  
@end deftypevr 

@deftypevr {Protected variable} {const Color*} draw_color
Pointer to the @code{Color} used if the @code{Path} is drawn.
@end deftypevr 

@deftypevr {Protected variable} {const Color*} fill_color 
Pointer to the @code{Color} used if the @code{Path} is filled.
@end deftypevr 

@deftypevr {Protected variable} string dashed
String written to @code{out_stream} for the ``dash pattern'' in a
MetaPost @code{draw} or @code{undraw} command.  If and only if
@code{dashed} is not the empty string, ``@code{dashed}
<@emph{dash pattern}>'' is written to @code{out_stream}.

Dash patterns have no meaning inside 3DLDF;  @code{dashed}, if
non-empty, is written unchanged to @code{out_stream}.  I may change this 
in the future.  
@end deftypevr 

@deftypevr {Protected variable} string pen 
String written to @code{out_stream} for the @code{pen} to be used in a
MetaPost @code{draw}, @code{undraw}, @code{filldraw}, or
@code{unfilldraw} command.  If and only if @code{pen} is not the 
empty string, ``@code{withpen} <@dots{}>'' is written to
@code{out_stream}. 

Pens have no meaning inside 3DLDF;  @code{pen}, if
non-empty, is written unchanged to @code{out_stream}.  I may change this 
in the future.  
@end deftypevr 

@deftypevr {Protected variable} bool arrow 
Indicates whether an arrow should be drawn when outputting a
@code{Path}.  Set to @code{true} on a @code{Path} created on the free
store and put onto a @code{Picture} by @code{drawarrow()}.  
@end deftypevr 

@deftypevr {Protected variable} {valarray<real>} projective_extremes    
Contains the maxima and minima of the x, y, and z-coordinates of the
@emph{projections} of @code{Points} on a @code{Path} using a particular
@code{Focus}.  Set in @code{set_extremes()} and used in
@code{Picture::output()} for surface hiding.
@end deftypevr 

@deftypevr {Protected variable} {vector<Point*>} points 
Pointers to the @code{Points} on the @code{Path}.
@end deftypevr 

@deftypevr {Protected variable} {vector<string>} connectors
The connectors between the @code{Points} on the @code{Path}.  Connectors
are simply @code{strings} in 3DLDF, they are written unchanged to 
@code{out_stream}.  
@end deftypevr 

@deftypevr {Public static variable} {const Color*} help_color
Pointer to a @code{const Color}, which becomes the default for
@code{draw_help()}.  
@xref{Drawing and Filling Paths,,Path Reference; Drawing and Filling}. 

Please note that @code{help_color} is a pointer to a
@code{const Color}, not a @code{const} pointer to a @code{Color} or a
@code{const} pointer to a @code{const Color}!  It's easy to get confused
by the syntax for these types of pointers.@c
@footnote{Stroustrup, @cite{The @cpp{} Programming Language}, p.@w{ }96.}  
@end deftypevr 

@deftypevr {Public static variable} string help_dash_pattern
The default dash pattern for @code{draw_help()}.
@end deftypevr 

@deftypevr {Public static variable} bool do_help_lines
@code{true} if help lines should be output, otherwise @code{false}.  
If @code{false}, a call to @code{draw_help()} does not cause a copy of
the @code{Path} to be created and put onto a @code{Picture}.
@xref{Drawing and Filling Paths,,Path Reference; Drawing and Filling}. 
@end deftypevr 

@node Path Constructors and Setting Functions, Path Destructor, Path Data Members, Path Reference
@section Constructors and Setting Functions

@deftypefn {Default constructor} void Path (void)
Creates an empty @code{Path} with no
@code{Points} and no connectors.
@end deftypefn


@deftypefn {Constructor} void Path ({const Point&} @var{p0}, {const Point&} @var{p1})
Creates a line (more precisely, a line segment) between @var{p0}
and @var{p1}.  The single 
connector between the two @code{Points} is set to @code{"--"} and the
data member @code{line_switch} (of type @code{bool}) is set to
@code{true}.  There are certain operations on @code{Paths} that are only
applicable to lines, so it's necessary to store the information that a
@code{Path} is a line.@c
@c
@footnote{It isn't sufficient to check whether a
@code{Path} consists of only two @code{Points} to determine whether it
is a line or not, since a connector with ``@code{curl}'' could cause it
to be non-linear.  On the other hand, @code{Paths} containing only
colinear @code{Points} and the connector @code{"--"} are perfectly
legitimate lines.  I'm in the process of changing all of the code that
tests for linearity by checking the value of @code{line_switch}, so that
it uses @code{is_linear()} instead.  When I've done this, it may be
possible to eliminate @code{line_switch}.  
@xref{Path Data Members,,Path Reference; Data Members}, and
@ref{Querying Paths,,Path Reference; Querying}.}


@example
Point A(-2, -2.5, -1);
Point B(3, 2, 2.5)
Path p(A, B);
p.show("p:");
@print{} p:
   (-2, -2.5, -1) -- (3, 2, 2.5);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 2, -10, 2, 2, 10, 10);} 
\immediate\write\examples{Point A(-2, -2.5, -1);}
\immediate\write\examples{Point B(3, 2, 2.5);}
\immediate\write\examples{A.dotlabel("$A$", "llft"); }
\immediate\write\examples{A.label(Point::WORLD_VALUES, "lrt");} 
\immediate\write\examples{B.dotlabel("$B$", "ulft"); }
\immediate\write\examples{B.label(Point::WORLD_VALUES, "urt");} 
\immediate\write\examples{Path p(A, B);}
\immediate\write\examples{p.draw();}
\immediate\write\examples{draw_axes(gray);} 
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn


@deftypefn {Setting function} void set ({const Point&} @var{p0}, {const Point&} @var{p1})
Corresponds to the constructor above.

@example
Point P0(1, 2, 3);
Point P1(3.5, -12, 75);
Path q;
q.set(P0, P1);
q.show("q:");
@print{} q: 
   (1, 2, 3) -- (3.5, -12, 75);
@end example

@end deftypefn 


@deftypefn {Constructor} void Path (string @var{connector}, bool @var{cycle}, Point* @var{p}, [@dots{}], 0)
For @code{Paths} with an arbitrary number of @code{Points}
and one type of connector.  

@var{connector} is passed unchanged to @code{out_file}, so it
must be a valid connector in MetaPost.    

@var{cycle} indicates whether the @code{Path} is a cycle or not.
@code{cycle_switch} is set to @var{cycle}.
@xref{Path Data Members,,Path Reference; Data Members}.
The filling and unfilling functions 
only work for
@code{Paths} that are cycles.  
@xref{Drawing and Filling Paths, , Path Reference; Drawing and Filling}.
If a @code{Path} is a cycle, it is up to the user to make sure that it
has sensible @code{Point} and connector values;  3DLDF doesn't check
them.  If they are not sensible, for instance, if the @code{Path}
crosses itself, and you try to fill it, this will cause an error in
MetaPost.  It is possible that a @code{Path} will be ``sensible'' in
some projections and not in others, although I have not tested this. 

@var{p} is a pointer to the first @code{Point} that should go onto the
@code{Path}.  
The ellipsis points (@code{...}) represent an arbitrary number of
pointers to @code{Points} that should go onto the @code{Path}.  
The final 
argument must be @code{0}, 
which is interpreted by the @cpp{} compiler as the null
pointer.@c
@c
@footnote{Stroustrup, @cite{The @cpp{} Programming Language}, p.@w{ }88.}  

It is admittedly a bit
awkward to have to type ``@code{&p0}'' rather than ``@code{p0}'', and
I have frequently forgotten to do it, which causes a compiler error,
but all of the arguments must be pointers in order to be able to use 0 to
indicate the end of the argument list.  Convenience in typing function
calls is not a high priority in 3DLDF, because once I've written
an input routine, these function calls should be generated
automatically.  It will be more important to define a convenient syntax
for the input routine.  


@example
Point P0; 
Point P1(2);
Point P2(2,2);
Point P3(0,2);
Path p("..", true, &P0, &P1, &P2, &P3, 0);
p.draw();


@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point P0;}
\immediate\write\examples{Point P1(2);}
\immediate\write\examples{Point P2(2,2);}
\immediate\write\examples{Point P3(0,2);}
\immediate\write\examples{Path p("..", true, &P0, &P1, &P2, &P3, 0);}
\immediate\write\examples{p.draw();}
\immediate\write\examples{P0.dotlabel("$P_0$", "llft");} 
\immediate\write\examples{P1.dotlabel("$P_1$", "lrt");}
\immediate\write\examples{P2.dotlabel("$P_2$");} 
\immediate\write\examples{P3.dotlabel("$P_3$");} 
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn

@deftypefn {Setting function} void set (string @var{connector}, bool @var{cycle}, Point* @var{p}, [@dots{}], 0)
Corresponds to the constructor above.

@example
Point P[4];
P[0].set(2, 1, 3);
P[3] = P[2] =  P[1] = P[0];
P[3] *= P[2] *=  P[1].rotate(3, 12, 18);
P[3] *= P[2].shift(-2, -1, 3);
P[3].shear(1.5, .5, 3.5);
Path q("...", false, &P[0], &P[1], &P[2], &P[3], 0);
q.show("q:");
@print{} q:
   (2, 1, 3) ... (0.92139, 1.51449, 3.29505) ... 
   (-1.07861, 0.514487, 6.29505) ... (2.84065, -3.26065, 6.29505);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 2, -10, 2, 2, 10, 10);}
\immediate\write\examples{Point P[4];}
\immediate\write\examples{P[0].set(2, 1, 3);}
\immediate\write\examples{P[3] = P[2] =  P[1] = P[0];}
\immediate\write\examples{P[3] *= P[2] *=  P[1].rotate(3, 12, 18);}
\immediate\write\examples{P[3] *= P[2].shift(-2, -1, 3);}
\immediate\write\examples{P[3].shear(1.5, .5, 3.5);}
\immediate\write\examples{Path q("...", false, &P[0], &P[1], &P[2], &P[3], 0);}
\immediate\write\examples{q.dotlabel(); }
\immediate\write\examples{q.draw();}
\immediate\write\examples{draw_axes(gray);}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn

@deftypefn {Constructor} void Path (Point* @var{first_point_ptr}, char* @var{s}, Point* @var{p}, [@dots{}], 0)
Constructor for @code{Paths} with an arbitrary number of @code{Points}
and connectors.  The first, required, argument is a pointer to a
@code{Point}, followed by pointers to @code{char} alternating with pointers to
@code{Points}.@c
@c
@footnote{Where possible, I prefer to use the @cpp{} data
type @code{string} rather than @code{char*}, however it was necessary to
use @code{char*} here because 0 is not a valid @code{string}, even
though @code{string} may be implemented as @code{char*},
and 0 must be a valid argument, since it is needed to indicate the end
of the argument list.}
@c
The last argument must be 0, i.e., the null pointer.

There is no need to indicate by means of an argument whether the
@code{Path} is a cycle or not:  If it is, the last argument before the 0
will be a @code{char*} (pointer to @code{char}), if not, it will be a
@code{Point*}.  The data member @code{cycle_switch} (of type
@code{bool}) will be set to @code{true} or @code{false} accordingly. 

@example
Point A;
Point B(2, 0);
Point C(3, 2);
Point D(1, 3);
Path p(&A, "..", &B, "..", &C, "--", &D, "...", 0);
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point A;} 
\immediate\write\examples{Point B(2, 0);}
\immediate\write\examples{Point C(3, 2);}
\immediate\write\examples{Point D(1, 3);}
\immediate\write\examples{A.dotlabel("A", "llft");} 
\immediate\write\examples{B.dotlabel("B", "lrt");} 
\immediate\write\examples{C.dotlabel("C");} 
\immediate\write\examples{D.dotlabel("D");}
\immediate\write\examples{Path p(&A, "..", &B, "..", &C, "--", &D, "...", 0);}
\immediate\write\examples{p.draw();} 
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn

@deftypefn {Setting function} void set (Point @var{*first_point_ptr}, string @var{s}, Point @var{*p}, [@dots{}], 0)
Corresponds to the constructor above.
@end deftypefn 

@deftypefn {Copy constructor} void Path ({const Path&} @var{p})
Creates a new @code{Path}, making it a copy of @var{p}.
@end deftypefn


@deftypefn {Template specializations} Path* create_new<Path> ({const Path*} @var{p})
@c
@deftypefnx {} Path* create_new<Path> ({const Path&} @var{p})
@c
Pseudo-constructors for dynamic allocation of @code{Paths}.
They create a @code{Path} on the free store and allocate memory for it using 
@code{new(Path)}.  They return a pointer to the new @code{Path}.  

If @var{p} is a non-zero pointer or a reference,
the new @code{Path} will be a copy of
@var{p}.  If the new object is not meant to be a
copy of an existing one, @samp{0} must be passed to
@code{create_new<Path>()} as its argument.
@xref{Dynamic Allocation of Shapes}, for more information. 


@code{create_new<Path>()} is used in the drawing and filling functions
for copying a @code{Path} and putting the copy onto a @code{Picture}.  
@xref{Drawing and Filling Paths, , Path Reference; Drawing and Filling}.
@end deftypefn 





@node Path Destructor, Path Operators, Path Constructors and Setting Functions, Path Reference
@section Destructor

@deftypefn {@code{virtual} Destructor} void {~Path} (@code{void})
All of the @code{Points} on a @code{Path} are created by
@code{create_new<Point>()}, which allocates them dynamically on
the free store.  Therefore, the destructor calls @code{delete()} on all
of the pointers on @code{points}.  Following this, it calls
@code{points.clear()} and @code{connectors.clear()}.
@code{draw_color} and @code{fill_color} may or may not have been
allocated on the free store, so @code{~Path()} checks this first, and
deletes them, if they were.  Then, it sets them to 0.
@end deftypefn 

@node Path Operators, Appending to Paths , Path Destructor, Path Reference
@section Operators

@deftypefn {Virtual function} Transform operator*= ({const Transform&} @var{t})
Calls @code{Point::operator*=(@var{t})} on each of the @code{Points}
on the @code{Path}.  
@xref{Point Operators, ,Point Reference; Operators}.
This has the effect of
transforming the entire @code{Path} by @var{t}.  Please note that
@code{Path} does not have a @code{transform} data member of its own.
@end deftypefn 

@deftypefun void operator+= ({const Point&} @var{pt})
Copies @var{pt} and pushes a pointer to the copy onto 
@code{points}.  The last connector 
in the @code{Path} will be used to connect the new @code{Point} and the
previous one. 

@example
Point A(1, 2, 3);
Point B(3, 4, 5);
Path q;
q += A;
q += B;
q.show("q:");
@print{} q:
   (1, 2, 3) -- (3, 4, 5);
@end example

@end deftypefun 

@deftypefn {@code{const} function} Path operator+ ({const Point&} @var{pt})
Copies the @code{Path} and @var{pt}, and pushes a pointer to the copy of
@var{pt} onto @code{points} in the new @code{Path}.  The
last connector in the new @code{Path} will be used to connect the new
@code{Point} and the previous one.  The @code{Path} remains unchanged.
@end deftypefn 

@deftypefun void operator&= ({const Path&} @var{pa})
Concatenates two @code{Paths}.  The result is assigned to @code{*this}.
Neither @code{*this} nor @var{pa} may be cyclical, i.e.,
@code{cycle_switch} must be @code{false} for both @code{Paths}.
@end deftypefun 

@deftypefn {@code{const} function} Path operator& ({const Path&} @var{pa})
Returns a @code{Path} representing the concatenation of @code{*this} and
@var{pa}.  @code{*this} remains unchanged.
Neither @code{*this} nor @var{pa} may be cyclical, i.e.,
@code{cycle_switch} must be @code{false} for both @code{Paths}.
@end deftypefn 

@deftypefun void operator+= ({const string} @var{s})
Pushes @var{s} onto @code{connectors}.
@end deftypefun


@node Appending to Paths , Copying Paths, Path Operators, Path Reference
@section Appending

@deftypefun Path append ({const Path&} @var{pa}, [string @var{connector} = "--", [bool @var{assign} = @code{true}]])
Appends @var{pa} to @code{*this} using @var{connector} to join them and
returns the resulting @code{Path}.  If
@var{assign} @equiv{} @code{true}, then the return value is
assigned to @code{*this}, otherwise, @code{*this} remains unchanged. 

If necessary, a @code{const} version could be added, for 
@code{const Paths}. 

@example
Point A(-2, 2);
Point B(-2, -2);
Point C(2, -2);
Point D(2, 2);
Path q("--", false, &A, &B, &C, &D, 0);
Point E(1, 2);
Point F(0, 4);
Point G(-.5, 3);
Path r("..", false, &E, &F, &G, 0);
q.append(r, "..", true);
q += "..";
q += "--";
q.set_cycle();
q.show("q:");
@print{} q:
   (-2, 2, 0) -- (-2, -2, 0) --
   (2, -2, 0) -- (2, 2, 0) ..
   (1, 2, 0) .. (0, 4, 0) .. 
   (-0.5, 3, 0) -- cycle;
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point A(-2, 2);}
\immediate\write\examples{Point B(-2, -2);}
\immediate\write\examples{Point C(2, -2);}
\immediate\write\examples{Point D(2, 2);}
\immediate\write\examples{A.dotlabel("$A$", "ulft"); }
\immediate\write\examples{B.dotlabel("$B$", "llft"); }
\immediate\write\examples{C.dotlabel("$C$", "lrt"); }
\immediate\write\examples{D.dotlabel("$D$", "urt"); }
\immediate\write\examples{Path q("--", false, &A, &B, &C, &D, 0);}
\immediate\write\examples{Point E(1, 2);}
\immediate\write\examples{Point F(0, 4);}
\immediate\write\examples{Point G(-.5, 3);}
\immediate\write\examples{E.dotlabel("$E$", "urt");}
\immediate\write\examples{F.dotlabel("$F$");  }
\immediate\write\examples{G.dotlabel("$G$", "rt"); }
\immediate\write\examples{Path r("..", false, &E, &F, &G, 0);}
\immediate\write\examples{q.append(r, "..", true);}
\immediate\write\examples{q += "..";}
\immediate\write\examples{q += "--";}
\immediate\write\examples{q.set_cycle();}
\immediate\write\examples{q.draw();}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@node Copying Paths, Clearing Paths , Appending to Paths , Path Reference
@section Copying 

@deftypefn {@code{const} virtual function} {Shape*} get_copy (void)
Creates a copy of the @code{Path} using @code{create_new<Path>()}, which
returns a pointer to @code{Path}.  @code{get_copy()} then
casts this pointer to a pointer to @code{Shape} and returns it. 

This function is used when copying @code{Pictures} and in
@code{Solid::output()}, where objects of types derived from @code{Shape}
must be handled in the same way, without their actual types being known.
@end deftypefn 

@node Clearing Paths , Modifying Paths , Copying Paths, Path Reference
@section Clearing 

@deftypefn {Virtual function} void clear (void)
Does the same thing the destructor @code{~Path()} does:
Calls @code{delete()} on the pointers to @code{Points} on @code{points},
clears @code{points} and @code{connectors}, deletes @code{draw_color}
and @code{fill_color}, if they point to @code{Colors} that were
allocated on the free store, and sets them to 0.  

@code{clear()} is a pure virtual function in @code{class Shape},
so @code{Path} must be have a @code{clear()} function.  
It is needed, because it is sometimes called through a
pointer to @code{Shape}, so that @code{~Path()} cannot be accessed.
At least, so far I haven't found a way to call a destructor through the
virtual function facility.  
@end deftypefn 

@node Modifying Paths , Affine Transformations for Paths, Clearing Paths , Path Reference
@section Modifying   

@deftypefn {Virtual function} bool set_on_free_store ([bool @var{b} = @code{true}])
Sets @code{on_free_store} to @var{b}.  This is used in the
template function @code{create_new()}.
@xref{Path Constructors and Setting Functions,,
Path Reference; Constructors and Setting Functions}.
@end deftypefn 

@deftypefn {Virtual function} void set_fill_draw_value ({const signed short} @var{s})
Sets @code{fill_draw_value} to @var{s}, which should be one of
@code{Shape::DRAW}, @code{Shape::FILL}, @code{Shape::FILLDRAW}, 
@code{Shape::UNDRAW}, @code{Shape::UNFILL}, or @code{Shape::UNFILLDRAW}.
@end deftypefn

@deftypefn {Virtual function} void set_draw_color ({const Color&} @var{c})
@deftypefnx {Virtual function} void set_draw_color ({const Color *} @var{c})
Sets @code{draw_color} (a pointer to a @code{const Color}) to @var{&c}
or @var{c}, depending on whether the 
version with a reference argument or the version with a pointer argument
is used.  

@code{set_draw_color()} is used in the @code{Solid} drawing and filling
functions, because @code{Path::draw_color} is @code{protected}, and 
the @code{Solid} cannot access it directly.
@xref{Drawing and Filling Solids,,
Solid Reference; Drawing and Filling}.
@end deftypefn 

@deftypefn {Virtual function} void set_fill_color ({const Color&} @var{c})
@deftypefnx {Virtual function} void set_fill_color ({const Color*} @var{c})
Sets @code{fill_color} (a pointer to a @code{const Color}) to @var{&c}
or @var{c}, depending on whether the 
version with a reference argument or the version with a pointer argument
is used.  

@code{set_fill_color()} is used in the @code{Solid} drawing and filling
functions, because 
@code{Path::fill_color} is @code{protected}, and 
the @code{Solid} cannot access it directly.
@xref{Drawing and Filling Solids,,
Solid Reference; Drawing and Filling}.
@end deftypefn 

@deftypefn {Virtual function} void set_dash_pattern ([{const string} @var{s} = ""])
Sets @code{dashed} to @var{s}.
@end deftypefn 

@deftypefn {Virtual function} void set_pen ([{const string} @var{s} = ""])
Sets @code{pen} to @var{s}.
@end deftypefn 

@deftypefn {Virtual function} void set_connectors ([{const string} @var{s} = ".."])
Clears @code{connectors} and then pushes @var{s} onto it, making @var{s}
the only connector.  Additional connectors can be added by using
@code{Path::operator+=(const string)}.
@xref{Path Operators, ,Path Reference; Operators}.

I plan to add a version of this function taking a vector of
@code{strings} as its argument, to make it possible to set several 
connectors at one time.
@end deftypefn 

@node Affine Transformations for Paths, Aligning Paths with an Axis, Modifying Paths , Path Reference
@section Affine Transformations

@deftypefn {Virtual function} Transform rotate ({const real} @var{x}, [{const real} @var{y} = 0, [{const real} @var{z} = 0]])
Creates a @code{Transform t} locally and calls 
@code{t.rotate(@var{x}, @var{y}, @var{z})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.
@end deftypefn 

@deftypefun Transform scale (real @var{x}, [real y = @var{1}, [real z = @var{1}]])
Creates a @code{Transform t} locally and calls
@code{t.scale(@var{x}, @var{y}, @var{z})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.

The @code{Points} on the @code{Path} are scaled according to the
arguments:

@example
Point pt[8];
pt[0] = (-1, -1);
for (int i = 1; i < 8; ++i)
  @{
    pt[i] = pt[0];
    pt[i].rotate(0, 0, i * 45);
  @}
Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], 
       &pt[4], &pt[5], &pt[6],
       &pt[7], 0); 
p.draw();
p.scale(2, 2);
p.draw();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP 
\immediate\write\examples{origin.dotlabel("(0, 0, 0)", "bot");} 
\immediate\write\examples{Point pt[8];}
\immediate\write\examples{pt[0] = (-1, -1);}
\immediate\write\examples{for (int i = 1; i < 8; ++i)}
\BGRP
\immediate\write\examples{pt[i] = pt[0];}
\immediate\write\examples{pt[i].rotate(0, 0, i * 45);}
\EGRP 
\immediate\write\examples{Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], }
\immediate\write\examples{&pt[4], &pt[5], &pt[6],}
\immediate\write\examples{&pt[7], 0); }
\immediate\write\examples{p.draw();}
\immediate\write\examples{p.scale(2, 2);}
\immediate\write\examples{p.draw();}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefun Transform shear (real @var{xy}, [real @var{xz} = 0, [real @var{yx} = 0, [real @var{yz} = 0, [real @var{zx} = 0, [real @var{zy} = 0]]]]])
Creates a @code{Transform t} locally and calls
@code{t.shear(@var{xy}, @var{xz}, @var{yx}, @var{yz}, @var{zx}, @var{zy})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.

@example
Point p0;
Point p1(1);
Point p2(1, 1);
Point p3(0, 1);
Path q("--", true, &p0, &p1, &p2, &p3, 0);
q.rotate(0, 45);
q.shift(1);
q.filldraw(black, light_gray);
q.shear(1.5, 2, 2.5, 3, 3.5, 5);
q.filldraw(black, light_gray);
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP 
\immediate\write\examples{default_focus.set(3, 3, -10, 3, 3, 10, 10);}
\immediate\write\examples{Point p0;}
\immediate\write\examples{Point p1(1);}
\immediate\write\examples{Point p2(1, 1);}
\immediate\write\examples{Point p3(0, 1);}
\immediate\write\examples{Path q("--", true, &p0, &p1, &p2, &p3, 0);}
\immediate\write\examples{q.rotate(0, 45);}
\immediate\write\examples{q.shift(1);}
\immediate\write\examples{q.filldraw(black, light_gray);}
\immediate\write\examples{q.get_point(0).dotlabel(Point::WORLD_VALUES, "llft"); }
\immediate\write\examples{q.get_point(1).dotlabel(Point::WORLD_VALUES, "rt"); }
\immediate\write\examples{q.get_point(2).dotlabel(Point::WORLD_VALUES, "rt"); }
\immediate\write\examples{q.get_point(3).dotlabel(Point::WORLD_VALUES, "lft"); }
\immediate\write\examples{q.shear(1.5, 2, 2.5, 3, 3.5, 5);}
\immediate\write\examples{q.filldraw(black, light_gray);}
\immediate\write\examples{q.get_point(0).dotlabel(Point::WORLD_VALUES, "ulft"); }
\immediate\write\examples{q.get_point(1).dotlabel(Point::WORLD_VALUES, "lft"); }
\immediate\write\examples{q.get_point(2).dotlabel(Point::WORLD_VALUES, "rt"); }
\immediate\write\examples{q.get_point(3).dotlabel(Point::WORLD_VALUES, "rt"); }
\immediate\write\examples{draw_axes(gray);}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefun Transform shift (real @var{x}, [real @var{y} = 0, [real @var{z} = 0]])
Creates a @code{Transform t} locally and calls
@code{t.shift(@var{x}, @var{y}, @var{z})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.

Shifts each of the @code{Points} on the @code{Path} according to the
arguments. 

@example
default_focus.set(5, 10, -10, 0, 10, 10, 10);
Point pt[6];
pt[0].set(-2, -2);
pt[1].set(0, -3);
pt[2].set(2, -2);
pt[3].set(2, 2);
pt[4].set(0, 3);
pt[5].set(-2, 2);
Path p("--", true, &pt[0], &pt[1], &pt[2], 
       &pt[3], &pt[4], &pt[5], 0);
p.draw();
p.shift(3, 3, 3);
p.draw();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP 
\immediate\write\examples{default_focus.set(5, 10, -10, 0, 10, 10, 10);}
\immediate\write\examples{draw_axes(2.5, "bot", "lft", "rt", gray);}
\immediate\write\examples{Point pt[6];}
\immediate\write\examples{pt[0].set(-2, -2);}
\immediate\write\examples{pt[1].set(0, -3);}
\immediate\write\examples{pt[2].set(2, -2);}
\immediate\write\examples{pt[3].set(2, 2);}
\immediate\write\examples{pt[4].set(0, 3);}
\immediate\write\examples{pt[5].set(-2, 2);}
\immediate\write\examples{Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], &pt[4], &pt[5], 0);}
\immediate\write\examples{Point p_center(origin);}
\immediate\write\examples{origin.label("$p$", "lrt");}
\immediate\write\examples{p.draw();}
\immediate\write\examples{p_center *= p.shift(3, 3, 3);}
\immediate\write\examples{origin.drawarrow(p_center, black, "evenly");} 
\immediate\write\examples{p_center.label("$p$");} 
\immediate\write\examples{p.draw();}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefun Transform shift ({const Point&} @var{p})
Creates a @code{Transform t} locally and calls
@code{t.shift(@var{p})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.

This version of @code{shift()} uses the x, y, and z-coordinates of the 
@code{Point} @var{p} to shift the @code{Path}.

@example
default_focus.set(5, 10, -10, 0, 10, 10, 10);
Point pt[6];
pt[0].set(-2, -2);
pt[1].set(0, -3);
pt[2].set(2, -2);
pt[3].set(2, 2);
pt[4].set(0, 3);
pt[5].set(-2, 2);
Path p("--", true, &pt[0], &pt[1], &pt[2], 
       &pt[3], &pt[4], &pt[5], 0);
p.draw();
Point s(1, 1, 1);
p.shift(s);
p.draw();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP 
\immediate\write\examples{default_focus.set(5, 10, -10, 0, 10, 10, 10);}
\immediate\write\examples{draw_axes(2.5, "bot", "lft", "rt", gray);}
\immediate\write\examples{Point pt[6];}
\immediate\write\examples{pt[0].set(-2, -2);}
\immediate\write\examples{pt[1].set(0, -3);}
\immediate\write\examples{pt[2].set(2, -2);}
\immediate\write\examples{pt[3].set(2, 2);}
\immediate\write\examples{pt[4].set(0, 3);}
\immediate\write\examples{pt[5].set(-2, 2);}
\immediate\write\examples{Path p("--", true, &pt[0], &pt[1], &pt[2], }
\immediate\write\examples{&pt[3], &pt[4], &pt[5], 0);} 
\immediate\write\examples{p.draw();}
\immediate\write\examples{Point A;}
\immediate\write\examples{A.label("$p$", "lrt");}
\immediate\write\examples{Point s(2, -2, 4);}
\immediate\write\examples{A *= p.shift(s);}
\immediate\write\examples{origin.drawarrow(A, black, "evenly");} 
\immediate\write\examples{A.label("$p$");}
\immediate\write\examples{p.draw();}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefn {Virtual function} void shift_times (real @var{x}, [real @var{y} = 1, [real @var{z} = 1]])
@deftypefnx {Virtual function} void shift_times ({const Point& @var{p}})
Each of these functions calls the corresponding version of
@code{Point::shift_times()} on all of the 
@code{Points} on @code{points}.  
@xref{Affine Transformations for Points,, Point Reference; 
Affine Transformations}. 
The return value is @code{void},
because there is no guarantee that all of the @code{Points} on a
@code{Path} will have identical @code{transform} members (although it's
likely). 

Please note that @code{shift_times()} will only have an effect on
the @code{Points} on a @code{Path} if it's called @emph{after} a call to
@code{shift()} and @emph{before} an operation is applied that causes
@code{Point::apply_transform()} to be called.
@end deftypefn 

@deftypefn {Virtual function} Transform rotate ({const Point&} @var{p0}, {const Point&} @var{p1}, [{const real} @var{angle} = 180])
Creates a @code{Transform t} locally and calls
@code{t.rotate(@var{p0}, @var{p1}, @var{angle})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.
@end deftypefn 

@deftypefun Transform rotate ({const Path&} @var{p}, [{const real} @var{angle} = 180])
If @code{p.is_linear()} returns @code{true}, this function
creates a @code{Transform} @var{t} locally and calls
@code{@var{t}.rotate(@var{p}, @var{angle})}.
@code{t} is then applied to all of the @code{Points} on @code{points}.
The return value is @code{t}.
Otherwise, it issues an error message and returns
@code{INVALID_TRANSFORM}.  
@end deftypefun 

@node Aligning Paths with an Axis, Applying Transformations to Paths, Affine Transformations for Paths, Path Reference
@section Aligning with an Axis

@deftypefn {@code{const} function} Transform align_with_axis ([{const char} @var{axis} = 'z'])
@deftypefnx {Function} Transform align_with_axis (bool @var{assign}, [{const char} @var{axis} = 'z'])
@deftypefnx {Function} Transform align_with_axis ({const Point&} @var{p0}, {const Point&} @var{p1}, {const char} @var{axis})
These functions return the @code{Transform} which, if applied to the
@code{Path}, would align it with the major axis indicated by the
@var{axis} argument.  

The first and second versions can only be called
for @code{Paths} where @code{line_switch} is @code{true}.  The first
version is @code{const}, so the @code{Path} remains unchanged.  The second
version should only be called with @code{@var{assign} = true}, so that the
@code{Transform} is applied to the @code{Path}, actually aligning it with
the axis indicated.  If the second version is called with 
@code{@var{assign} = false}, a warning message is issued to the standard error
output (@code{stderr}), since one might as well use the first version in
this case, but it won't do any harm.  The third version creates a
@code{Transform} @var{t} locally that would align the line from @var{p0} to
@var{p1} with the axis indicated, and applies @var{t} to the @code{Path}.

@example
Point A(2, 3, 2);
Point B(-1, 1, 3);
Path p(A, B);
Transform t = p.align_with_axis(true, 'z');
t.show("t:");
@print{} t:
    -0.316   0.507  -0.802       0 
         0  -0.845  -0.535       0 
    -0.949  -0.169   0.267       0 
      2.53    1.86    2.67       1 
p *= t;
p.show("p:");
@print{} p:
   (2.53, 1.86, 2.67) -- (-1.02, 1.23, 3.67);

Point C(1);
C *= t.inverse();

Path q;
q += "..";
q += C;

for (int i = 0; i < 15; ++i)
  @OCB
    C.rotate(A, B, 360.0/16);
    q += C;
  @CCB
q.set_cycle(true);
q.show("q:");
@print{} q:
   (1.68, 3, 1.05) .. (1.9, 2.68, 1.06) .. 
   (2.13, 2.4, 1.21) .. (2.35, 2.22, 1.48) .. 
   (2.51, 2.15, 1.83) .. (2.59, 2.22, 2.21) .. 
   (2.58, 2.4, 2.55) .. (2.49, 2.68, 2.81) .. 
   (2.32, 3, 2.95) .. (2.1, 3.32, 2.94) .. 
   (1.87, 3.6, 2.79) .. (1.65, 3.78, 2.52) .. 
   (1.49, 3.85, 2.17) .. (1.41, 3.78, 1.79) .. 
   (1.42, 3.6, 1.45) .. (1.51, 3.32, 1.19) .. cycle;
q.align_with_axis(A, B, 'z');
q.show("q:");
@print{} q:
   (1, 0, 0) .. (0.924, 0.383, 0) .. 
   (0.707, 0.707, 0) .. (0.383, 0.924, 0) .. 
   (0, 1, 0) .. (-0.383, 0.924, 0) .. 
   (-0.707, 0.707, 0) .. (-0.924, 0.383, 0) .. 
   (-1, 0, 0) .. (-0.924, -0.383, 0) .. 
   (-0.707, -0.707, 0) .. (-0.383, -0.924, 0) .. 
   (0, -1, 0) .. (0.383, -0.924, 0) .. 
   (0.707, -0.707, 0) .. (0.924, -0.383, 0) .. cycle;
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 2, -10, 2, 2, 10, 10);}
\immediate\write\examples{Point A(2, 3, 2);}
\immediate\write\examples{Point B(-1, 1, 3);}
\immediate\write\examples{Path p(A, B);}
\immediate\write\examples{A.dotlabel("$A$", "urt"); }
\immediate\write\examples{B.dotlabel("$B$", "lft"); }
\immediate\write\examples{A.mediate(B).label("$p$"); }
\immediate\write\examples{p.draw();}
\immediate\write\examples{Transform t = p.align_with_axis(true, 'z');}
\immediate\write\examples{p *= t;}
\immediate\write\examples{Point C(1);}
\immediate\write\examples{C *= t.inverse();}
\immediate\write\examples{Path q;}
\immediate\write\examples{q += "..";}
\immediate\write\examples{q += C;}
\immediate\write\examples{for (int i = 0; i < 15; ++i)}
\immediate\write\examples{  @OCB}
\immediate\write\examples{    C.rotate(A, B, 360.0/16);}
\immediate\write\examples{    q += C;}
\immediate\write\examples{  @CCB}
\immediate\write\examples{q.set_cycle(true);}
\immediate\write\examples{q.draw();}
\immediate\write\examples{q.get_point(14).label("$q$", "ulft");}
\immediate\write\examples{q.align_with_axis(A, B, 'z');}
\immediate\write\examples{q.draw();}
\immediate\write\examples{origin.mediate(q.get_point(6)).label("$q$");}
\immediate\write\examples{draw_axes(gray);   }
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn 

@node Applying Transformations to Paths, Drawing and Filling Paths, Aligning Paths with an Axis, Path Reference
@section Applying Transformations

@deftypefn {Virtual function} void apply_transform (void)
Calls @code{Point::apply_transform()} on all of the @code{Points} on
@code{points}. 
@xref{Applying Transformations to Points,,Point Reference; 
Applying Transformations}.   
@end deftypefn 

@node Drawing and Filling Paths, Labelling Paths, Applying Transformations to Paths, Path Reference
@section Drawing and Filling


@deftypefn {@code{const} virtual function} void draw ([{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [{const string} @var{ddashed} = "", [{const string} @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]])
@deftypefnx {@code{const} Virtual function} void draw (Picture& @var{picture}, [{const Color&} @var{ddraw_color} = *Colors::default_color, [string @var{ddashed} = "", [string @var{ppen} = ""]]])
Allocates a copy of the @code{Path} on the free store, puts a pointer to
the copy on @var{picture}.@code{shapes}, sets
its @code{fill_draw_value} to @code{DRAW}, and 
the values of its
@code{draw_color}, @code{dashed}, and @code{pen} according to the
arguments.  

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.

All of the arguments to @code{draw()} are optional, so it can be invoked
as follows:

@example
Point A;
Point B(2);
Point C(3, 3);
Point D(1, 2);
Point E(-1, 1);
Path p("..", true, &A, &B, &C, &D, &E, 0);
p.draw();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point A;}
\immediate\write\examples{Point B(2);}
\immediate\write\examples{Point C(3, 3);}
\immediate\write\examples{Point D(1, 2);}
\immediate\write\examples{Point E(-1, 1);}
\immediate\write\examples{A.dotlabel("A", "bot");}
\immediate\write\examples{B.dotlabel("B", "bot");}
\immediate\write\examples{C.dotlabel("C");}
\immediate\write\examples{D.dotlabel("D");}
\immediate\write\examples{E.dotlabel("E", "lft");}
\immediate\write\examples{Path p("..", true, &A, &B, &C, &D, &E, 0);}
\immediate\write\examples{p.draw();}
\OEX{Projections::PARALLEL_X_Y}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

The arguments:

@table @var
@item ddraw_color
Used to specify a color for the
@code{Path}.  @var{ddraw_color} is a reference to a @code{Color}.
Colors are described in @ref{Color Reference}.

The most basic @code{Colors} are predefined in 3DLDF (in the
@code{namespace Colors}), and
users may create new @code{Colors} and specify their red-green-blue
values.  

The @code{Path p} could be drawn in red by calling
@code{p.draw(Colors::red)}. This manual isn't intended to be printed in
color, so there's no figure to demonstrate this.  However, gray values
can be printed on non-color printers.

@example
using namespace Colors;
p.draw(gray, "", "pencircle scaled .25mm");
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\immediate\write\examples{A.dotlabel("A", "bot");}
\immediate\write\examples{B.dotlabel("B", "bot");}
\immediate\write\examples{C.dotlabel("C");}
\immediate\write\examples{D.dotlabel("D");}
\immediate\write\examples{E.dotlabel("E", "lft");}
\immediate\write\examples{out_stream << "pickup pencircle scaled 2mm;" << endl;}
\immediate\write\examples{p.draw(Colors::gray);}
\immediate\write\examples{current_picture.output(Projections::PARALLEL_X_Y);}
\immediate\write\examples{out_stream << "pickup pencircle scaled .25mm;" << endl;}
\OEX{Projections::PARALLEL_X_Y}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@item ddashed
A @code{string} representing a ``dash pattern'', as defined in 
MetaPost@c
@c
@footnote{Hobby, @cite{A User's Manual for MetaPost}, p.@w{ }32.}.
@c
Dash patterns have no meaning in 3DLDF, they are simply @code{strings}
that are written unchanged to @code{out_stream}. 

@example
p.draw(black, "evenly");
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\immediate\write\examples{A.dotlabel("A", "bot");}
\immediate\write\examples{B.dotlabel("B", "bot");}
\immediate\write\examples{C.dotlabel("C");}
\immediate\write\examples{D.dotlabel("D");}
\immediate\write\examples{E.dotlabel("E", "lft");}
\immediate\write\examples{p.draw(black, "evenly");}
\OEX{Projections::PARALLEL_X_Y}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@item ppen
A @code{string} representing a ``pen'', as defined in Metafont and
MetaPost@c
@c
@footnote{Knuth, @cite{The METAFONTbook}, Chapter 4, p.@w{ }21ff.
Hobby, @cite{A User's Manual for MetaPost}, p.@w{ }32.}.
@c  
Pens have no meaning in 3DLDF, they are simply @code{strings}
that are written unchanged to @code{out_stream}.

@example
p.draw(black, "", "pensquare xscaled 3mm 
       yscaled .25mm scaled .5mm");
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\immediate\write\examples{Point A0(A);}
\immediate\write\examples{Point B0(B);}
\immediate\write\examples{Point C0(C);}
\immediate\write\examples{Point D0(D);}
\immediate\write\examples{Point E0(E);}
\immediate\write\examples{A0 *= B0.shift(0, -.1);}
\immediate\write\examples{C0.shift(0, .05);}
\immediate\write\examples{D0.shift(0, .15);}
\immediate\write\examples{E0.shift(-.175);}
\immediate\write\examples{A0.label("A", "bot");}
\immediate\write\examples{B0.label("B", "bot");}
\immediate\write\examples{C0.label("C");}
\immediate\write\examples{D0.label("D");}
\immediate\write\examples{E0.label("E", "lft");}
\immediate\write\examples{p.draw(black, "", "pensquare xscaled 3mm yscaled .25mm scaled .5mm");}
\OEX{Projections::PARALLEL_X_Y}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@item picture
Indicates the @code{Picture} on which the @code{Path} should be
drawn. 

The two versions of @code{draw()} differ in the position of the
@var{picture} argument:  In the first version, it's the last argument,
while in the second version, it's the first argument.  If a
@var{picture} argument is used, it's often more convenient to use the second
version. 

The following example puts @code{Path p} onto @code{temp_picture}.  It
also demonstrates how the labels are put onto @code{temp_picture}, and
how @code{temp_picture} is output.  In
the previous examples, the commands for making the labels and outputting
@code{current_picture} were left out in order to reduce clutter.
@xref{Labelling Points,, Point Reference; Labelling}, and
@ref{Picture Output Functions,,Picture Reference; Outputting; 
Output Functions}. 

@example
Picture temp_picture;
p.draw(temp_picture);
A.dotlabel("A", "bot", temp_picture);
B.dotlabel("B", "bot", temp_picture);
C.dotlabel("C", "top", temp_picture);
D.dotlabel("D", "top", temp_picture);
E.dotlabel("E", "lft", temp_picture);
temp_picture.output(Projections::PARALLEL_X_Y);
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\immediate\write\examples{Picture temp_picture;}
\immediate\write\examples{A.dotlabel("A", "bot", temp_picture);}
\immediate\write\examples{B.dotlabel("B", "bot", temp_picture);}
\immediate\write\examples{C.dotlabel("C", "top", temp_picture);}
\immediate\write\examples{D.dotlabel("D", "top", temp_picture);}
\immediate\write\examples{E.dotlabel("E", "lft", temp_picture);}
\immediate\write\examples{p.draw(temp_picture);}
\immediate\write\examples{temp_picture.output(Projections::PARALLEL_X_Y);}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end table
@end deftypefn 

@deftypefn {@code{const} function} void draw_help ([{const Color&} @var{ddraw_color} = *help_color, [string @var{ddashed} = help_dash_pattern, [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]])
@deftypefnx {@code{const} function} void draw_help (Picture& @var{picture}, [{const Color&} @var{ddraw_color} = @code{*help_color}, [string @var{ddashed} = @code{help_dash_pattern}, [string @var{ppen} = ""]]])
@c
This functions are for drawing help lines.
They are like @code{draw()}, except that @code{draw_help()} returns immediately,
if @code{do_help_lines} (a static data member in 
@code{Path}) is @code{false}.  
Also, the defaults for @var{ddraw_color} and
@var{ddashed} differ from those for @code{draw()}.
@end deftypefn 

@deftypefn {@code{const} virtual function} void drawarrow ([{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]])
@deftypefnx {@code{const} virtual function} void drawarrow (Picture& @var{picture}, [{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [string @var{ddashed} = "", [string @var{ppen} = ""]]]) 
Like @code{draw()}, except that the MetaPost command @code{drawarrow} is
written to @code{out_stream} when @code{picture}
is output.
The second version is convenient for passing a @code{Picture} argument
without having to specify all of the other arguments. 

@c !! TO DO:  Do something about adding arguments for the size and shape
@c of the arrowhead.  LDF 2003.07.13.

@example
Point m;
Point n(2, 2);
m.dotlabel("$m$", "bot"); 
n.dotlabel("$n$"); 
m.drawarrow(n);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point m;}
\immediate\write\examples{Point n(2, 2);}
\immediate\write\examples{m.dotlabel("$m$", "bot"); }
\immediate\write\examples{n.label("$n$"); }
\immediate\write\examples{m.drawarrow(n);}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn

@deftypefn {Non-member function} void draw_axes ([real @var{dist} = 2.5, [string @var{pos_x} = "bot", [string @var{pos_y} = "lft", [string @var{pos_z} = "bot", [{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [{const string} @var{ddashed} = "", [{const string} @var{ppen} = "", [{const Point&} @var{shift_x} = @code{origin}, [{const Point&} @var{shift_y} = @code{origin}, [{const Point&} @var{shift_z} = @code{origin}, [Picture& @var{picture} = @code{current_picture}]]]]]]]]]]]) 
@deftypefnx {Non-member function} void draw_axes ({const Color&} @var{ddraw_color}, [real @var{dist} = 2.5, [string @var{pos_x} = "bot", [string @var{pos_y} = "lft", [string @var{pos_z} = "bot", [{const string} @var{ddashed} = "", [{const string} @var{ppen} = "", [{const Point&} @var{shift_x} = @code{origin}, [{const Point&} @var{shift_y} = @code{origin}, [{const Point&} @var{shift_z} = @code{origin}, [Picture& @var{picture} = @code{current_picture}]]]]]]]]]]) 
@c
These functions draw lines centered on the origin, and ending in arrows in the
directions of the positive x, 
y, and z-axes, and labels them with the appropriate letters.  
@code{draw_axes()} is used in
many of the figures in this handbook.  It can be helpful in determining
whether a @code{Focus} has a good ``@code{up}'' direction.
@xref{Focus Data Members,,Focus Reference; Data Members}. 

In the first version, all of the arguments are optional.  In the second
version, @var{ddraw_color} is required and has been moved to the front
of the argument list.  This version is often convenient, when a
@code{Color} other than the default is desired.

The arguments:
@table @var
@item dist
The length of the lines drawn.  The default is 2.5.  The value 0 can be
used as a dummy argument, if the default for @var{dist} is desired, but
other arguments must be specified.  

@item
@itemx pos_x
@itemx pos_y
@itemx pos_z
The position arguments for the labelling commands for each of the axes. 
The defaults are @code{"bot"} for the x and z-axes, and @code{"lft"} for
the y-axis.
The usual @code{strings} for the
position of labels can be used, 
namely: @code{"top"}, @code{"bot"}, @code{"lft"},
@code{"rt"}, @code{"ulft"}, @code{"urt"}, @code{"llft"}, 
@code{"lrt"}, and @code{""}.  If @code{""} is used, that axis is not
drawn.  This can be useful for parallel projections onto one of the 
major planes@c
@c
@footnote{The usual interpretation of @code{""} as a
position argument to a 
labelling command would be to put it directly onto @code{*(Label.pt)},  
which in this case would put it onto the arrowhead.  Since this
will probably never be desirable, I've decided to use @code{""} to
suppress drawing axes.  Formerly, @code{draw_axes()} used three
additional arguments for this purpose.}.
@c
In addition, @code{"d"} can be used to indicate that the default should
be used for that label.  This can be useful if one needs a placeholder,
but doesn't remember what the default is for that label.

@example
draw_axes(0, "bot", "rt", "");
current_picture.output(Projections::PARALLEL_X_Y);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{draw_axes(0, "bot", "rt", "");}
\immediate\write\examples{current_picture.output(PARALLEL_X_Y);}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

In addition, the arguments @var{shift_x}, @var{shift_y},
and @var{shift_z} can be used to adjust the positions of the labels
further (see below). 

@item  ddraw_color 
@itemx   ddashed
@itemx   ppen
Arguments for the @code{drawarrow()} command, described above, in this
section. 

@item  shift_x
@itemx  shift_y
@itemx  shift_z
Offsets for the labels.  These arguments make it possible to adjust the
positions of the labels.  The defaults are @code{origin}, so no shifting 
takes place, if they are used.  In @NEXTFIG{},
@code{draw_axes} is called without any arguments, so the defaults
are used. 

@example
draw_axes();
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{draw_axes();} 
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

In @NEXTFIG{}, the @code{Point P} is used to shift the labels.  
Please note that placeholders must be used for the first arguments. 

@example
Point P(.5, .5, .5);
draw_axes(0, "d", "d", "d", black, "", "", P, -P, P);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point P(.5, .5, .5);}
\immediate\write\examples{draw_axes(0, "d", "d", "d", black, "", "", P, -P, P);}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

Please note that the @code{Points} used for placing the labels are
three-dimensional @code{Points}, whether the @var{shift_x}, 
@var{shift_y}, and/or @var{shift_z} arguments are used or not.
It is not currently possible to adjust the positions of the
labels on the two-dimensional projection itself.  This would
probably be more useful, but would require changing the way
@code{Picture::output()} functions.

@item  picture
The @code{Picture}, onto which the @code{Paths} and @code{Labels} are put.
@end table
@end deftypefn 

@deftypefn {@code{const} function} void fill ([{const Color&} @var{ffill_color} = @code{*Colors::default_color}, [Picture& @var{picture} = @code{current_picture}]])
@deftypefnx {Function} void fill (Picture& @var{picture}, [{const Color&} @var{ffill_color} = @code{*Colors::default_color}])

Allocates a copy of the @code{Path} on the free store, puts a pointer to
it onto @var{picture}.@code{shapes}, sets
its @code{fill_draw_value} to @code{FILL}, and 
its @code{fill_color} to @code{*@var{ffill_color}}.

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.

The arguments are similar to those of @code{draw()}, except that the
@code{Color} argument is called @var{ffill_color} instead of
@var{ddraw_color}.

@example
p.fill(gray);
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\immediate\write\examples{A.dotlabel("A", "bot");}
\immediate\write\examples{B.dotlabel("B", "bot");}
\immediate\write\examples{C.dotlabel("C");}
\immediate\write\examples{D.dotlabel("D");}
\immediate\write\examples{E.dotlabel("E", "lft");}
\immediate\write\examples{p.fill(gray);}
\OEX{Projections::PARALLEL_X_Y}
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn 

@deftypefn {@code{const} function} void filldraw ([{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [{const Color&} @var{ffill_color} = @code{*Colors::background_color}, [string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]]]])
@deftypefnx {@code{const} function} void filldraw (Picture& @var{picture}, [{const Color&} @var{ddraw_color} = @code{*Colors::default_color}, [{const Color&} @var{ffill_color} = @code{*Colors::background_color}, [string @var{ddashed} = "", [string @var{ppen} = ""]]]])
@c
Allocates a copy of the @code{Path} on the free store, puts a pointer to
the copy onto @var{picture}.@code{shapes}, sets
its @code{fill_draw_value} to @code{FILLDRAW}, 
its @code{draw_color} and @code{fill_color} to 
@code{*@var{ddraw_color}} and @code{*@var{ffill_color}}, respectively, 
its @code{dashed} to @var{ddashed}, and its @code{pen} 
to @var{ppen}.

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.

The arguments are similar to those of @code{draw()} and @code{fill()},
except that both @var{ddraw_color} and @var{ffill_color} are used.  

3DLDF's @code{filldraw()} differs from Metafont's and MetaPost's
@code{filldraw} commands:  In Metafont and MetaPost, @code{filldrawing}
is equivalent to filling a @code{path} and then drawing its 
border using the @code{pen}.
Metafont does not have colors.  While MetaPost does, its @code{filldraw}
command does not foresee the use of different colors for drawing and
filling.  

@example
p.filldraw(black, gray, "", "pencircle scaled 2mm");
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\immediate\write\examples{A0.label("A", "bot");}
\immediate\write\examples{B0.label("B", "bot");}
\immediate\write\examples{C0.label("C");}
\immediate\write\examples{D0.label("D");}
\immediate\write\examples{E0.label("E", "lft");}
\immediate\write\examples{p.filldraw(black, gray, "", "pencircle scaled 2mm");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

It can often be useful to draw the outline of a @code{Path}, but to have
it hide objects that lie behind it.  This is why the default for
@var{ffill_color} is @code{*Colors::background_color}.  


@example
default_focus.set(3, 0, -10, 3, 10, 10, 10);  
Point p[8];
p[0] = p[1] = p[2] = p[3] = p[4] 
     = p[5] = p[6] = p[7].set(-1,-1, 5);
p[1] *= p[2] *= p[3] *= p[4] *= p[5] 
     *= p[6] *= p[7].rotate(0, 0, 45);
p[2] *= p[3] *= p[4] 
     *= p[5] *= p[6] *= p[7].rotate(0, 0, 45);
p[3] *= p[4] *= p[5] *= p[6] 
     *= p[7].rotate(0, 0, 45);
p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45);
p[5] *= p[6] *= p[7].rotate(0, 0, 45);
p[6] *= p[7].rotate(0, 0, 45);
p[7].rotate(0, 0, 45);
Path r0("..", true, &p[0], &p[1], &p[2], 
        &p[3], &p[4], &p[5], &p[6], &p[7], 0);
r0.filldraw(black, light_gray);
r0.scale(2, .5);
r0.shift(0, 0, -2.5); 
r0.filldraw(black, gray);
r0.scale(.25, 3);
r0.shift(0, 0, -2.5);
r0.filldraw();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(3, 0, -10, 3, 0, 10, 10);}
\immediate\write\examples{Point p[8];}
\immediate\write\examples{p[0] = p[1] = p[2] = p[3] = p[4] = p[5] 
                          = p[6] = p[7].set(-1,-1, 5);}
\immediate\write\examples{p[1] *= p[2] *= p[3] *= p[4] *= p[5] 
                          *= p[6] *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[2] *= p[3] *= p[4] *= p[5] *= p[6] 
                          *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[3] *= p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[5] *= p[6] *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[6] *= p[7].rotate(0, 0, 45);}
\immediate\write\examples{p[7].rotate(0, 0, 45);}
\immediate\write\examples{Path r0("..", true, &p[0], &p[1], &p[2], 
                          &p[3], &p[4], &p[5], &p[6], &p[7], 0);}
\immediate\write\examples{r0.filldraw(black, light_gray);}
\immediate\write\examples{r0.scale(2, .5);}
\immediate\write\examples{r0.shift(0, 0, -2.5); }
\immediate\write\examples{r0.filldraw(black, gray, "evenly scaled 4", } 
\immediate\write\examples{"pencircle scaled .5mm");} 
\immediate\write\examples{r0.scale(.25, 3);}
\immediate\write\examples{r0.shift(0, 0, -2.5);}
\immediate\write\examples{r0.filldraw();}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn 

@deftypefun void undraw ([string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = @code{current_picture}]]])
@deftypefunx void undraw (Picture& @var{picture}, [string @var{ddashed} = "", [string @var{ppen} = ""]])
Allocates a copy of the @code{Path} on the free store, puts a pointer to
it on @var{picture}.@code{shapes}, sets
its @code{fill_draw_value} to @code{UNDRAW}, and 
the values of its
@code{dashed} and @code{pen} according to the
arguments.  

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.

This function ``undraws'' a @code{Path}.  This is equivalent to drawing
the @code{Path} using the background color
(@code{*Colors::background_color}).  

Undrawing is useful for removing a portion of a @code{Path}.  

@c
@c Make this illustration a letter.  LDF 2003.07.16.
@c

@example
Point P0(1, 1);
Point P1(2, 1);
Point P2(2, 3);
Point P3(-1, 1);
Path p("--", false, &origin, &P0, &P1, &P2, &P3, 0);
p.draw(black, "", "pencircle scaled 3mm");
p.undraw("", "pencircle scaled 1mm");
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point P0(1, 1);}
\immediate\write\examples{Point P1(2, 1);}
\immediate\write\examples{Point P2(2, 3);}
\immediate\write\examples{Point P3(-1, 1);}
\immediate\write\examples{Path p("--", false, &origin, &P0, &P1, &P2, &P3, 0);}
\immediate\write\examples{p.draw(black, "", "pencircle scaled 3mm");}
\immediate\write\examples{p.undraw("", "pencircle scaled 1mm");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefun void unfill ([Picture& @var{picture} = @code{current_picture}])
Allocates a copy of the @code{Path} on the free store, puts a pointer to
it on @var{picture}.@code{shapes} and sets
its @code{fill_draw_value} to @code{UNFILL}  

This function is useful for removing a portion of a filled region.

@example
Point pt[4];
pt[0].set(-2, -2);
pt[1].set(2, -2);
pt[2].set(2, 2);
pt[3].set(-2, 2);
Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], 0);
p.draw();
p.dotlabel(); 
p.filldraw(black, gray);
p.scale(.5, .5);
p.unfill();
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP 
\immediate\write\examples{Point pt[4];}
\immediate\write\examples{pt[0].set(-2, -2);}
\immediate\write\examples{pt[1].set(2, -2);}
\immediate\write\examples{pt[2].set(2, 2);}
\immediate\write\examples{pt[3].set(-2, 2);}
\immediate\write\examples{Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], 0);}
\immediate\write\examples{p.draw();}
\immediate\write\examples{p.filldraw(black, gray);}
\immediate\write\examples{p.scale(.5, .5);}
\immediate\write\examples{p.unfill();}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@deftypefun void unfilldraw ([{const Color&} @var{ddraw_color} = @code{*Colors::background_color}, [string @var{ddashed} = "", [string @var{ppen} = "", [Picture& @var{picture} = current_picture]]]])
@deftypefunx void unfilldraw (Picture& @var{picture}, [{const Color&} @var{ddraw_color} = @code{*Colors::background_color}, [string @var{ddashed} = "", [string @var{ppen} = ""]]])
@c
Allocates a copy of the @code{Path} on the free store, puts a pointer to
it on @var{picture}.@code{shapes}, sets
its @code{fill_draw_value} to @code{UNFILLDRAW}, and 
the values of its
@code{draw_color}, @code{dashed}, and @code{pen} according to the
arguments.  While the default for @var{ddraw_color} is
@code{*Colors::background_color}, any other @code{Color} can be used,
so that @code{unfilldraw()} can unfill a @code{Path} and draw an outline
around it.

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.

This function is similar to @code{unfill()} 
(@pxref{Drawing and Filling Paths,,Path Reference; Drawing and Filling}),
except that the outline of the @code{Path} will be ``undrawn'' using the
pen specified with the @var{ppen} argument, or MetaPost's
@code{currentpen}, if no @var{ppen} argument is specified.  In addition,
the @code{Path} will be drawn using the @code{Color} specified in the
@var{ddraw_color} argument.  Since the default is
@code{*Colors::background_color}, the @code{Path} will be ``undrawn''
unless a different @code{Color} is specified.  

@example
Point pt[6];
pt[0].set(-2, -2);
pt[1].set(0, -3);
pt[2].set(2, -2);
pt[3].set(2, 2);
pt[4].set(0, 3);
pt[5].set(-2, 2);
Path p("--", true, &pt[0], &pt[1], &pt[2], 
       &pt[3], &pt[4], &pt[5], 0);
p.fill(gray);
p.scale(.5, .5);
p.unfilldraw(black, "", "pensquare xscaled 3mm");
@end example

@iftex
@tex 
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{Point pt[6];}
\immediate\write\examples{pt[0].set(-2, -2);}
\immediate\write\examples{pt[1].set(0, -3);}
\immediate\write\examples{pt[2].set(2, -2);}
\immediate\write\examples{pt[3].set(2, 2);}
\immediate\write\examples{pt[4].set(0, 3);}
\immediate\write\examples{pt[5].set(-2, 2);}
\immediate\write\examples{Path p("--", true, &pt[0], &pt[1], 
                          &pt[2], &pt[3], &pt[4], &pt[5], 0);}
\immediate\write\examples{p.fill(gray);}
\immediate\write\examples{p.scale(.5, .5);}
\immediate\write\examples{p.unfilldraw(black, "", "pensquare xscaled 3mm");}
\OEX{Projections::PARALLEL_X_Y}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun 

@node Labelling Paths, Showing Paths, Drawing and Filling Paths, Path Reference
@section Labelling 

@deftypefn {@code{const} function} void label ([{unsigned int} @var{i} = 0, [string @var{position_string} = "top", [short @var{text_short} = 0, [bool @var{dot} = @code{false}, [Picture& @var{picture} = @code{current_picture}]]]]])
@deftypefnx {@code{const} function} void label (Picture& @var{picture}, [{unsigned int} @var{i} = 0, [string @var{position_string} = "top", [short @var{text_short} = 0, [bool @var{dot} = @code{false}]]]])
@c
Calls @code{Point::label()} on all of the @code{Points} on
@code{points}.  They are numbered consecutively starting with @var{i}.
The other arguments are used for all of the @code{Points}, so it's not
possible to specify different positions for the labels for different
@code{Points}.  @var{dot} will normally not be specified, unless a
@var{picture} argument is used in the first version.  @code{dotlabel()}
calls @code{label()} with @var{dot} = @code{true}.

The second version is convenient for passing a
@code{Picture} argument without having to specify all of the other arguments.
@end deftypefn 

@deftypefn {@code{const} function} void dotlabel ([{unsigned int} @var{i} = 0, [string @var{position_string} = "top", [short @var{text_short} = 0, Picture& @var{picture} = @code{current_picture}]]])
@deftypefnx {@code{const} function} void dotlabel (Picture& @var{picture}, [{unsigned int} @var{i} = 0, [string @var{position_string} = "top", [short @var{text_short} = 0]]])
@c
Like @code{label()}, except that the @code{Points} are dotted.  
@end deftypefn 

@node Showing Paths, Querying Paths, Labelling Paths, Path Reference
@section Showing 

@deftypefn {@code{const} function} void show ([string @var{text} = "", [char @var{coords} = 'w', [{const bool} @var{do_persp} = @code{true}, [{const bool} @var{do_apply} = @code{true}, [Focus* @var{f} = 0, [{const unsigned short} @var{proj} = @code{Projections::PERSP}, [{const real} @var{factor} = 1]]]]]]])
@c
Prints information about the @code{Path} to standard output
(@code{stdout}).  @var{text} is simply printed out, unless it's the
empty string, in which case @code{"Path:"} is printed out.
@var{coords} indicates which set of coordinates should be shown.  Valid values are
@code{'w'} for the @code{world_coordinates}, @code{'p'} for the
@code{projective_coordinates}, @code{'u'} for the
@code{user_coordinates}, and @code{'v'} for the @code{view_coordinates},
whereby the latter two are currently not in use
(@pxref{Point Data Members,,Point Reference; Data Members}).  
If @var{do_apply} is @code{true}, @code{apply_transform()} is called
on each @code{Point}, updating its @code{world_coordinates} and
resetting its @code{transform}.  Otherwise,
it's not.
The arguments @var{do_persp}, @var{f}, @var{proj}, and @var{factor} are only
relevant when showing @code{projective_coordinates}.  If @code{do_persp}
is @code{true}, the @code{Points} are projected using the values of
@var{f}, @var{proj}, and @var{factor}
(@pxref{Outputting Paths,,Path Reference; Outputting}).  
Otherwise, the values currently
stored in @code{projective_coordinates} are shown.
The @code{Points} and connectors are printed out alternately to standard
output, followed by the word ``cycle'', if @code{cycle_switch = true}.@c
@c
@footnote{The following example shows only one @code{Point} per 
line.  In actual use, two @code{Points} are shown, but this causes
overfull boxes in Texinfo.}   

@example
default_focus.set(0, 3, -10, 0, 3, 10, 10);
Reg_Polygon r(origin, 5, 3, 45);
r.fill(gray);
Point p[10];
for (int i = 0; i < 5; ++i)
    p[i] = r.get_point(i);
p[5] = Point::intersection_point(p[4], p[0], p[2], p[1]).pt;
p[6] = Point::intersection_point(p[0], p[1], p[2], p[3]).pt;
p[7] = Point::intersection_point(p[1], p[2], p[4], p[3]).pt;
p[8] = Point::intersection_point(p[2], p[3], p[0], p[4]).pt;
p[9] = Point::intersection_point(p[3], p[4], p[0], p[1]).pt;
Path q("--", true, &p[0], &p[5], &p[1], &p[6], &p[2], &p[7], 
       &p[3], &p[8], &p[4], &p[9], 0);
q.draw();
q.show("q:");
@print{} q:
fill_draw_value == 0
(0, 1.06066, 1.06066) 
-- (-2.30826, 2.24651, 2.24651) 
-- (-1.42658, 0.327762, 0.327762) 
-- (-3.73485, -0.858092, -0.858092) 
-- (-0.881678, -0.858092, -0.858092) 
-- (4.92996e-07, -2.77684, -2.77684) 
-- (0.881678, -0.858092, -0.858092) 
-- (3.73485, -0.858092, -0.858092) 
-- (1.42658, 0.327762, 0.327762) 
-- (2.30826, 2.24651, 2.24651) -- cycle;
q.show("q:", 'p');
@print{} q:
fill_draw_value == 0
Projective coordinates.
(0, -1.75337, 0.0958948) 
-- (-1.88483, -0.615265, 0.183441) 
-- (-1.38131, -2.58743, 0.031736) 
-- (-4.08541, -4.22023, -0.0938636) 
-- (-0.964435, -4.22023, -0.0938636) 
-- (0, -7.99767, -0.384436) 
-- (0.964436, -4.22023, -0.0938636) 
-- (4.08541, -4.22023, -0.0938636) 
-- (1.38131, -2.58743, 0.031736) 
-- (1.88483, -0.615266, 0.183441) -- cycle;
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(0, 3, -10, 0, 3, 10, 10);}
\immediate\write\examples{Reg_Polygon r(origin, 5, 3, 45);}
\immediate\write\examples{r.fill(gray);}
\immediate\write\examples{Point p[10];}
\immediate\write\examples{for (int i = 0; i < 5; ++i)}
\immediate\write\examples{    p[i] = r.get_point(i);}
\immediate\write\examples{p[0].dotlabel(0); }
\immediate\write\examples{p[1].dotlabel(1, "ulft"); }
\immediate\write\examples{p[2].dotlabel(2, "llft"); }
\immediate\write\examples{p[3].dotlabel(3, "lrt"); }
\immediate\write\examples{p[4].dotlabel(4, "urt"); }
\immediate\write\examples{p[5] = Point::intersection_point(p[4], p[0], p[2], p[1]).pt;}
\immediate\write\examples{p[5].dotlabel(5); }
\immediate\write\examples{p[6] = Point::intersection_point(p[0], p[1], p[2], p[3]).pt;}
\immediate\write\examples{p[6].dotlabel(6, "lft"); }
\immediate\write\examples{p[7] = Point::intersection_point(p[1], p[2], p[4], p[3]).pt;}
\immediate\write\examples{p[7].dotlabel(7, "bot"); }
\immediate\write\examples{p[8] = Point::intersection_point(p[2], p[3], p[0], p[4]).pt;}
\immediate\write\examples{p[8].dotlabel(8, "rt"); }
\immediate\write\examples{p[9] = Point::intersection_point(p[3], p[4], p[0], p[1]).pt;}
\immediate\write\examples{p[9].dotlabel(9); }
\immediate\write\examples{Path q("--", true, &p[0], &p[5], &p[1], &p[6], &p[2], &p[7], }
\immediate\write\examples{       &p[3], &p[8], &p[4], &p[9], 0);}
\immediate\write\examples{q.draw();}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn 

@deftypefun void show_colors ([bool @var{} = @code{false}])
Shows the values of @code{draw_color} and @code{fill_color}.  These will
normally be 0, unless the @code{Path} is on a @code{Picture}.  
@end deftypefun   


@node Querying Paths, Outputting Paths, Showing Paths, Path Reference
@section Querying
@c
@c !! ADD EXAMPLES to the function descriptions in this section.  
@c LDF 2003.07.16. 

@deftypefn {@code{const} function} bool is_on_free_store (void)
Returns @code{true}, if the @code{Path} was dynamically allocated on the
free store, otherwise @code{false}. 
@end deftypefn 

@deftypefn {@code{const} virtual function} bool is_planar ([{const bool} @var{verbose} = @code{false}, [string @var{text} = ""]]) 
@c
Uses @code{get_normal()} to determine
whether the @code{Path} is planar or not.  Returns @code{true}, if it is,
otherwise @code{false}.  If @var{verbose} is @code{true}, @var{text} is written to
standard output, or ``Path:'', if @var{text} is the empty string,
followed by a message saying whether the @code{Path} is planar or not.
@end deftypefn 

@deftypefn {@code{const} function} bool is_linear ([{const bool} @var{verbose} = @code{false}, [string @var{text} = ""]])
@c
Returns @code{true}, if @code{line_switch} is @code{true}.  Otherwise,
@code{is_linear()} uses @code{get_normal()} to determine whether the
@code{Path} is linear.  If it is, @code{is_linear()} returns
@code{true}, otherwise @code{false}.
@end deftypefn

@deftypefn {Inline @code{const} function} bool is_cycle (void)
Returns @code{true} if the @code{Path} is cyclical, i.e.,
@code{cycle_switch = true}, otherwise @code{false}.  Only cyclical
@code{Paths} are fillable.
@end deftypefn

@deftypefn {Inline function} int size (void)
Returns the number of @code{Points} on @code{points}, i.e.,
@code{points.size()}. 
@end deftypefn

@deftypefn {Inline @code{const} function} bool get_line_switch (void)
@c
Returns the value of @code{line_switch}.  @code{line_switch} is only
true, if the @code{Path} was created, directly or indirectly, using the
constructor taking two @code{Point} arguments only.
@xref{Path Constructors and Setting Functions,,
Path Reference; Constructors and Setting Functions}. 
@end deftypefn

@deftypefun real slope ([char @var{a} = 'x', [char @var{b} = 'y']])
Returns the slope of the @code{Path} in the plane indicated by the
arguments, if @code{is_linear()} returns @code{true}.  Otherwise,
@code{slope()} issues an error message and returns @code{INVALID_REAL}. 
@end deftypefun

@deftypefn {@code{const} function} Path subpath (size_t @var{start}, size_t @var{end}, [{const bool} @var{cycle} = false, [{const string} @var{connector} = ""]])
Returns a new @code{Path} using @code{points[@var{start}]} through
@code{points[@var{end} - 1]}.  If @var{cycle} is @code{true}, then the new 
@code{Path} will be a cycle, whether 
@code{*this} is or not.  One optional connector
argument can be used.  If it is, it will be the only connector.
Otherwise, the appropriate connectors from @code{*this} are used.  

@var{start} must be @math{<} @var{end}.  It is not possible to
have @var{start} @math{>} @var{end}, even if @code{*this} is a cycle.
@end deftypefn

@deftypefn {@code{const} function} {const Point&} get_point ({const unsigned short} @var{a})
Returns the @code{Point} @code{*points[@var{a}]}, if @var{a} @math{<}
@code{points.size()} and the @code{Path} is non-empty, otherwise
@code{INVALID_POINT}.  
@end deftypefn 

@deftypefn {@code{const} function} {const Point&} get_last_point (void)
Returns the @code{Point} pointed to by the last pointer on @code{points}.
Equivalent to  @code{get_point(get_size() - 1)}, but more convenient to
type.  Returns @code{INVALID_POINT}, if the @code{Path} is empty. 
@end deftypefn 

@deftypefn {@code{const} inline virtual function} size_t get_size (void)
Returns @code{points.size()}.  
@end deftypefn 

@deftypefn {@code{const} function} Line get_line (void)
Returns a @code{Line} corresponding to the @code{Path}, if the latter is 
linear.  Otherwise, @code{INVALID_LINE} is returned.
@xref{Line Reference}.
@end deftypefn 

@deftypefn {@code{const} virtual function} Point get_normal (void)
Returns a @code{Point} representing a unit vector in the direction of the
normal to the plane of the @code{Path}, or @code{INVALID_POINT}, if
the @code{Path} is non-planar.

@example
Point P(1, 1, 1);
Rectangle r(P, 4, 4, 30, 30, 30);
Point N = r.get_normal();
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 3, -10, 0, 3, 10, 10);}
\immediate\write\examples{Point P(1, 1, 1);}
\immediate\write\examples{P.dotlabel("$P$", "bot"); }
\immediate\write\examples{Rectangle r(P, 4, 4, 30, 30, 30);}
\immediate\write\examples{r.get_point(0).dotlabel(0, "bot");}
\immediate\write\examples{r.get_point(1).dotlabel(1, "rt");}
\immediate\write\examples{r.get_point(2).dotlabel(2);}
\immediate\write\examples{r.get_point(3).dotlabel(3, "lft");}
\immediate\write\examples{r.filldraw(black, light_gray);}
\immediate\write\examples{Point N = r.get_normal();}
\immediate\write\examples{N.label("$@DBKS{vec}@OCB N@CCB$");}
\immediate\write\examples{origin.drawarrow(N);}
\immediate\write\examples{N.shift(P);}
\immediate\write\examples{P.drawarrow(N);}
\immediate\write\examples{N.label("$@DBKS{vec}@OCB N@CCB$", "rt");}
\immediate\write\examples{draw_axes(0, "d", "d", "d", black, "evenly");}
\immediate\write\examples{current_picture.output(default_focus, Projections::PERSP, 1, Sorting::NO_SORT);}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

In 3DLDF, plane figures generally have constructors taking a |Point|
argument for the center, a variable number of |real| arguments for the 
dimensions, and three |real| arguments for the rotation about the major
axes.  The object is first created in the x-z plane, and the
@code{Points} are generated to be traversed in the counter-clockwise
direction, when seen from a @code{Point} with a positive y-coordinate.
If no rotation is specified, the normal will point in the direction of
the positive y-axis.  If non-zero arguments are used for rotation, the
normal will be rotated accordingly.  This direction considered to be
``outside''.  However, according to Huw
Jones, @cite{Computer Graphics Through Key Mathematics}, p.@: 197,
``outside'' is considered to be the side of a plane, where the
@code{Points} are meant to be traversed in the clockwise direction.  
I hope that no problems arise from this discrepancy!
@end deftypefn 

@deftypefn {@code{const} virtual function} Plane get_plane (void)
Creates and returns a @code{Plane} @var{p} corresponding to the @code{Path}, 
if the latter is planar, otherwise @code{INVALID_PLANE}.  
If the @code{Path} is planar, @var{p}.@code{point} will be the
@code{Point} pointed to by @code{this->points[0]}. 
@xref{Plane Reference}.

@example
Point P(1, 1, 1);
Rectangle r(P, 4, 4, 45, 20, 15);
Plane q = r.get_plane();
q.show("q:");
@print{} q:
   normal: (0.0505914, 0.745607, -0.664463)
   point: (0.0178869, -0.727258, -1.01297)
   distance == -0.131735
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(4, 3, -10, 0, 3, 10, 10);}
\immediate\write\examples{Point P(1, 1, 1);}
\immediate\write\examples{P.dotlabel("$P$", "bot"); }
\immediate\write\examples{Rectangle r(P, 4, 4, 45, 20, 15);}
\immediate\write\examples{r.filldraw(black, light_gray);}
\immediate\write\examples{Plane q = r.get_plane();}
\immediate\write\examples{q.point.dotlabel("@OCB@DBKS{tt} q.point@CCB", "bot");}
\immediate\write\examples{origin.drawarrow(q.normal);} 
\immediate\write\examples{q.normal.label("@OCB@DBKS{tt} q.normal@CCB", "lft");}
\immediate\write\examples{P.mediate(r.get_point(2), .5).label("$r$", "");} 
\immediate\write\examples{draw_axes(0, "d", "d", "d", black, "evenly");}
\immediate\write\examples{current_picture.output(default_focus, Projections::PERSP, 1, Sorting::NO_SORT);}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefn 

@deftypefun void set_cycle ([{const bool} @var{c} = @code{true}])
Sets @code{cycle_switch} to @var{c}.
@end deftypefun 


@deftypefn {Function} Path reverse (bool @var{assign})
@deftypefnx {@code{const} function} Path reverse (void)
@c
These functions return a @code{Path} with the same @code{Points} and
connectors as @code{*this}, but in reversed order.
@code{reverse()} can only be applied to non-cyclical @code{Paths}.  If
@code{*this} is a cycle, @code{reverse()} issues an error message and
returns @code{*this} unreversed.  

If the first version is called with @var{assign} @math{=} @code{true},
@code{*this} itself is reversed.  If @code{*this} should remain
unchanged, the @code{const} version without an argument should be
called.  If, on the other hand, the first version is called with
@var{assign} @math{=} @code{false}, a warning message is issued, but the
reversed @code{Path} is returned just the same, leaving @code{*this}
unchanged. 

@c !! ADD EXAMPLE.  LDF 2003.07.16.
@end deftypefn 

@node Outputting Paths, Path Intersections, Querying Paths, Path Reference
@section Outputting 

@deftypefun bool project ({const Focus&} @var{f}, {const unsigned short} @var{proj}, real @var{factor})
Calls @code{Point::project(@var{f}, @var{proj}, @var{factor})} on the
@code{Points} on the @code{Path}.  
If @code{Point::project()} fails (i.e., returns @code{false}), for any of
the @code{Points}, this function 
returns @code{false}.  Otherwise, it returns @code{true}. 
@end deftypefun 

@deftypefun {vector<Shape*>} extract ({const Focus&} @var{f}, {const unsigned short} @var{proj}, real @var{factor})
Checks that the @code{Points} on @code{points} can be projected using
the values for @var{f}, @var{proj}, and @var{factor}.  If they can, a
@code{vector<Shape*>} containing only @code{this} is returned.  Called in
@code{Picture::output()}. 
@end deftypefun 

@deftypefn {Virtual function} bool set_extremes (void)
Sets the appropriate elements in @code{projective_extremes} to the
minimum and maximum values of the x, y, and z-coordinates of 
the @code{Points} on the @code{Path}.  Used in @code{Picture::output()}
for determining whether a @code{Path} can be output using the arguments
passed to @code{Picture::output()}.
@end deftypefn 

@deftypefn {Inline @code{const} virtual function} {const valarray<real>} get_extremes (void)
Returns @code{projective_extremes}.  Used in @code{Picture::output()}.
@end deftypefn 

@deftypefn {@code{const} virtual function} real get_minimum_z (void)
@deftypefnx {@code{const} virtual function} real get_mean_z (void)
@deftypefnx {@code{const} virtual function} real get_maximum_z (void)
These functions return the minimum, mean, or maximum value,
respectively, of the 
z-coordinates of the @code{Points} on the @code{Path}.
Used in the surface hiding algorithm in @code{Picture::output()}.
@end deftypefn 

@deftypefn {Virtual function} void suppress_output (void)
Called in @code{Picture::output()}.  
Sets @code{do_output} to
@code{false}, if the @code{Path} cannot  be output using the arguments
passed to @code{Picture::output()}. 
@end deftypefn 

@deftypefn {Virtual function} void unsuppress_output (void)
Called in @code{Picture::output()}.  Resets @code{do_output} to
@code{true} after @code{output()} is called on the @code{Shapes} on
@code{shapes} in a @code{Picture}, so that the @code{Path} can be output
if @code{Picture::output()} is called again, with arguments that allow
the @code{Path} to be output.
@end deftypefn 

@deftypefn {Virtual function} void output (void)
Called in @code{Picture::output()}.  Writes the MetaPost code to
@code{out_stream} for drawing, filling, filldrawing, undrawing,
unfilling, or unfilldrawing the @code{Path}, if the latter was 
projectable using the arguments passed to @code{Picture::output()}.  
@end deftypefn 

@node Path Intersections,  , Outputting Paths, Path Reference
@section Intersections

@deftypefun bool_point intersection_point ({const Path&} @var{p}, {const bool} @var{trace})
@c
Finds the intersection point, if any, of two linear @code{Paths}.
Let @code{bp} be the @code{bool_point} returned by
this function.  @code{bp.pt} will contains the 
intersection point, if it exists.  If not, it will contain
@code{INVALID_POINT}.  If the intersection point exists and lies on both
of the line segments represented by the @code{Path} and @code{p},
@code{bp.b} will be @code{true}, otherwise, @code{false}.  

This function calls @code{Point::intersection_points()}, passing the first
and last @code{Points} on @code{*this} and @var{p} as its arguments.  If
the @var{trace} argument is @code{false}, the version of
@code{Point::intersection_points()} that finds the intersection point by
means of a vector calculation is used.  If it's @code{true}, the version
that finds the intersection point of the traces of the lines on the
major planes is used.  
@xref{Point Intersections,,Point Reference; Intersections}. 

@example
Point A(-1, -1, -1);
Point B(1, 1, 1);
Path p0(A, B);
Point C(-2, 1, 1);
Point D(1.75, 0.25, 0.25);
Path p1(C, D);
bool_point bp = p0.intersection_point(p1);
bp.pt.dotlabel("$i$"); 
bp.pt.show("bp.pt:");
@print{} bp.pt: (0.5, 0.5, 0.5)
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 10, -10, 2, 10, 10, 10);}
\immediate\write\examples{Point A(-1, -1, -1);}
\immediate\write\examples{Point B(1, 1, 1);}
\immediate\write\examples{Path p0(A, B);}
\immediate\write\examples{p0.draw();}
\immediate\write\examples{Point C(-2, 1, 1);}
\immediate\write\examples{Point D(1.75, 0.25, 0.25);}
\immediate\write\examples{Path p1(C, D);}
\immediate\write\examples{p1.draw();}
\immediate\write\examples{bool_point bp = p0.intersection_point(p1);}
\immediate\write\examples{bp.pt.dotlabel("$i$"); }
\immediate\write\examples{A.dotlabel("$A$", "bot"); }
\immediate\write\examples{B.dotlabel("$B$"); }
\immediate\write\examples{C.dotlabel("$C$", "lft"); }
\immediate\write\examples{D.dotlabel("$D$", "rt"); }
\immediate\write\examples{draw_axes(gray, 0, "d", "d", "rt");}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

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

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

@end deftypefun
