@c shape.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: shape.texi,v 1.3 2004/01/12 18:41:01 lfinsto1 Exp lfinsto1 $

 
@node Shape Reference, Transform Reference, Input and Output, Top
@chapter Shape Reference

@tindex Shape 
Class @code{Shape} is defined in @file{shapes.web}.

@code{Shape} is an @dfn{abstract class}, which means that 
all of its member functions are pure virtual functions, and 
that it's only used as a base class, i.e., no objects of type
@code{Shape} may be declared.  

All of the ``drawable'' types in 3DLDF, @code{Point},
@code{Path}, @code{Ellipse}, etc., are derived from @code{Shape}.  

Deriving all of the drawable types from @code{Shape} makes it possible
to handle objects of different types in the same way.  This is
especially important in the @code{Picture} functions, where objects of
various types (but all derived from @code{Shape}) are accessed through
pointers to @code{Shape}.  @xref{Picture Reference}.

@menu
* Shape Data Members::          
* Shape Operators::             
* Copying Shapes::              
* Modifying Shapes::            
* Affine Transformations for Shapes::  
* Applying Transformations to Shapes::  
* Clearing Shapes::             
* Querying Shapes::             
* Showing Shapes::              
* Outputting Shapes::           
@end menu
 
@node Shape Data Members, Shape Operators, Shape Reference, Shape Reference
@section Data Members


@deftypevr  {Protected static constants} {signed short} DRAWDOT 
@deftypevrx {} {signed short} DRAW    
@deftypevrx {} {signed short} FILL    
@deftypevrx {} {signed short} FILLDRAW
@deftypevrx {} {signed short} UNDRAWDOT 
@deftypevrx {} {signed short} UNDRAW    
@deftypevrx {} {signed short} UNFILL    
@deftypevrx {} {signed short} UNFILLDRAW
@c
Values used in the @code{output()} functions of the classes derived from
@code{Shape}.  For example, in @code{Path}, if the data member
@code{fill_draw_value} = @code{DRAW}, then the MetaPost command
@code{draw} is written to @code{out_stream} when that @code{Path} is
output.  
@end deftypevr                                                      

@node Shape Operators, Copying Shapes, Shape Data Members, Shape Reference
@section Operators

@deftypefn {Pure virtual function} Transform operator*= ({const Transform&} @var{t})
@end deftypefn 

@node Copying Shapes, Modifying Shapes, Shape Operators, Shape Reference
@section Copying

@deftypefn {@code{const} pure virtual function} Shape* get_copy (void) 
Copies an object, allocating memory on the free store for the copy, 
and returns a pointer to @code{Shape} for accessing the copy.  

Used in the drawing and filling functions for copying the @code{Shape},
and putting a pointer to the copy onto the @code{vector<Shape*> shapes}
of the @code{Picture}.  
@end deftypefn 

@node Modifying Shapes, Affine Transformations for Shapes, Copying Shapes, Shape Reference
@section Modifying

@deftypefn {Pure virtual function} bool set_on_free_store (bool @var{b} = @code{true})
Sets the data member @code{on_free_store} to @var{b}.  All classes
derived from @code{Shape} must therefore also have a data member
@code{on_free_store}. 

This function is used in the template function
@code{create_new<@i{type}>}.
@xref{Dynamic Allocation of Shapes}, for more information.

@end deftypefn 

@node Affine Transformations for Shapes, Applying Transformations to Shapes, Modifying Shapes, Shape Reference
@section Affine Transformations

@deftypefn {Pure virtual functions} Transform rotate ({const real} @var{x}, {const real} @var{y}, {const real} @var{z})
@deftypefnx {} Transform scale (real @var{x}, real @var{y}, real @var{z})
@deftypefnx {} Transform shear (real @var{xy}, real @var{xz}, real @var{yx}, real @var{yz}, real @var{zx}, real @var{zy})
@deftypefnx {} Transform shift (real @var{x}, real @var{y}, real @var{z})
@deftypefnx {} Transform rotate ({const Point&} @var{p0}, {const Point&} @var{p1}, {const real} @var{r})
@xref{Affine Transformations for Points,,Point Reference; Affine
Transformations}. 
@end deftypefn 

@node Applying Transformations to Shapes, Clearing Shapes, Affine Transformations for Shapes, Shape Reference
@section Applying Transformations

@deftypefn {Pure virtual function} void apply_transform (void)
Applies the @code{Transform} stored in the @code{transform} data member
of the @code{Points} belonging to the @code{Shape} to their
@code{world_coordinates}.  The @code{transforms} are subsequently reset
to the identity @code{Transform}.  
@end deftypefn 

@node Clearing Shapes, Querying Shapes, Applying Transformations to Shapes, Shape Reference
@section Clearing

@deftypefn {Pure virtual function} void clear (void)
The precise definition of this function will depend on the nature of the
derived class.  In general, it will call the destructor on dynamically
allocated objects belonging to the @code{Shape}, and deallocate the
memory they occupied.
@end deftypefn 

@node Querying Shapes, Showing Shapes, Clearing Shapes, Shape Reference
@section Querying

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


@node Showing Shapes, Outputting Shapes, Querying Shapes, Shape Reference
@section Showing

@deftypefn {@code{const} pure virtual 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} = 0, [{const real} @var{factor} = 1]]]]]]]) 
Prints information about an object to standard output.  
See the descriptions of @code{show()} for the classes derived from
@code{Shape} for more information.
@c !! TO DO:  !! DESCRIBE ARGUMENTS!!
@end deftypefn 

@node Outputting Shapes,  , Showing Shapes, Shape Reference
@section Outputting

@deftypefn {Pure virtual function} void output (void)
Called by @code{Picture::output()} for writing MetaPost code to
@code{out_stream} for a @code{Shape} pointed to by a pointer on the
@code{vector<Shape*> shapes} belonging to the @code{Picture}.  Such 
a @code{Shape} will have been created by a drawing or filling
function.  
@end deftypefn 

@deftypefn {Pure virtual function} {vector<Shape*>} extract ({const Focus&} @var{f}, {const unsigned short} @var{proj}, real @var{factor})
Called in @code{Picture::output()}.  It determines whether a
@code{Shape} can be output.  If it can, and an @code{output()} function
for the type of the @code{Shape} exists, a @code{vector<Shape*>}
containing a pointer to the @code{Shape} is returned.  

On the other
hand, it is possible to define a type derived from @code{Shape}, without
an @code{output()} function of its own, and not derived from a type that
has one.  It may then consist of one or more objects of types that do
have @code{output()} functions.  In this case, the @code{vector<Shape*>}
returned by @code{extract()} will contain pointers to all of these
subsidiary @code{Shapes}, and @code{Picture::output()} will treat them
as independent objects.  In particular, if any one of them cannot be
projected using the arguments passed to @code{Picture::output()}, this
will have no effect on whether the others are outputted or not.

Currently, there are no @code{Shapes} without an @code{output()}
function, either belonging to the class, or inherited.  However, it's
useful to be able to define @code{Shapes} in this way, so that they can
be tested without having to define an @code{output()} function first.
@end deftypefn 

@deftypefn {Pure virtual function}  bool set_extremes (void)
Sets the values of @code{projective_extremes} for the @code{Shape}.
This is needed in @code{Picture::output()} for determining the order in
which objects are output.
@end deftypefn 


@deftypefn {@code{const} pure virtual functions}  real get_minimum_z (void) 
@deftypefnx {}  real get_maximum_z (void) 
@deftypefnx {}  real get_mean_z (void) 
These functions return the minimum, maximum, and mean z-value
respectively of the projected @code{Points} belonging to 
the @code{Shape}, i.e., from @code{projective_extremes}.  The values for
the @code{Shapes} on the @code{Picture} are used for determining the
order in which they are output 
@end deftypefn 


@deftypefn {@code{const} pure virtual function} {const valarray<real>} get_extremes (void)
Returns @code{projective_extremes}.
@end deftypefn 

@deftypefn {Pure virtual function} void suppress_output (void)
Sets @code{do_output} to @code{false}.  This function is called in 
@code{Picture::output()}, if a @code{Shape} on a @code{Picture} cannot
be output using the arguments passed to @code{Picture::output()}.
@end deftypefn 

@deftypefn {Pure virtual function} void unsuppress_output (void)
Sets @code{do_output} to @code{true}.  Called in
@code{Picture::output()} after @code{output()} is called on the @code{Shapes}.
This way, output of @code{Shapes} that couldn't be output when
@code{Picture::output()} was called with a particular set of arguments
won't necessarily be suppressed when 
@code{Picture::output()} is called again with different arguments.
@end deftypefn 


