This is 3DLDF.info, produced by makeinfo version 4.5 from 3DLDF.texi.

This is the 3DLDF User and Reference Manual, edition 1.1.5 for 3DLDF
1.1.5.  This manual was last updated on 14 January 2004.  3DLDF is a
GNU package for three-dimensional drawing with MetaPost output.  The
author is Laurence D. Finston.

   Copyright (C) 2003, 2004 Laurence D. Finston.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".
   
INFO-DIR-SECTION GNU packages
START-INFO-DIR-ENTRY
* 3DLDF: (3DLDF).            3D drawing with MetaPost output.
END-INFO-DIR-ENTRY


File: 3DLDF.info,  Node: Plane Tesselations,  Next: Roulettes and Involutes,  Prev: Pattern Reference,  Up: Pattern Reference

Plane Tesselations
==================

   3DLDF can be used to make perspective projections of plane
tesselations and other two-dimensional patterns.  These can be used for
drawing tiled floors and other architectural items, among other things.
While patterns can be generated by using the basic facilities of C++
and 3DLDF without any specially defined functions, it can be useful to
define such functions.

   3DLDF currently contains only one function for drawing patterns
based on a plane tessellation.  I plan to add more soon.

 - Function: unsigned int hex_pattern_1 ([real DIAMETER_OUTER = 5,
          [real DIAMETER_MIDDLE = 0, [real DIAMETER_INNER = 0,
          [unsigned short FIRST_ROW = 5, [unsigned short DOUBLE_ROWS =
          10, [unsigned short ROW_SHIFT = 2, [Color DRAW_COLOR_OUTER =
          `*Colors::default_color', [Color FILL_COLOR_OUTER =
          `*Colors::background_color', [Color DRAW_COLOR_MIDDLE =
          `*Colors::default_color', [Color FILL_COLOR_MIDDLE =
          `*Colors::background_color', [Color DRAW_COLOR_INNER =
          `*Colors::default_color', [Color FILL_COLOR_INNER =
          `*Colors::background_color', [string PEN_OUTER = "pencircle
          scaled .5mm", [string PEN_MIDDLE = "pencircle scaled .3mm",
          [string PEN_INNER = "pencircle scaled .3mm", [Picture&
          PICTURE = `current_picture', [unsigned int MAX_HEXAGONS =
          1000]]]]]]]]]]]]]]]]])
     Draws a pattern consisting of hexagons forming a tesselation of
     the x-z plane, with additional hexagons within them.

     The arguments:
    `real' DIAMETER_OUTER
          Default:  5.  The diameter of the outer hexagon in each set
          of three hexagons.  The outer hexagons form a tessellation of
          the plane.

    `real' DIAMETER_MIDDLE
          Default: 0.  The diameter of the middle hexagon in a set of
          three hexagons.

    `real' DIAMETER_INNER
          Default: 0.  The diameter of the inner hexagon in a set of
          three hexagons.

    `unsigned short' FIRST_ROW
          Default: 5.  The number of sets of hexagons in the first
          single row.  The second single row will have FIRST_ROW + 1
          sets of hexagons.

    `unsigned short' DOUBLE_ROWS
          Default: 10.  The number of double rows drawn.

    `unsigned short' ROW_SHIFT
          Default: 2.  For ROW_SHIFT != 0, the number of sets of
          hexagons in each (single) row is increased by 2 every
          ROW_SHIFT rows.  If ROW_SHIFT == 0, the number sets of
          hexagons remains constant.  The rows remain centered around
          the z-axis.

    `Color' DRAW_COLOR_OUTER
          Default: `*Colors::default_color'.  The `Color' used for
          drawing the outer hexagons.

    `Color' FILL_COLOR_OUTER
          Default: `*Colors::background_color'.  The `Color' used for
          filling the outer hexagons.

    `Color' DRAW_COLOR_MIDDLE
          Default:  `*Colors::default_color'.  The `Color' used for
          drawing the middle hexagon.

    `Color' fill_color_middle
          Default:  `*Colors::background_color'.  The `Color' used for
          filling the middle hexagons.

    `Color' DRAW_COLOR_INNER
          Default:  `*Colors::default_color'.  The `Color' used for
          drawing the inner hexagons.

    `Color' FILL_COLOR_INNER
          Default:  `*Colors::background_color'.  The `Color' used for
          filling the inner hexagons.

    `string' PEN_OUTER
          Default: `"pencircle scaled .5mm"'.  The pen used for drawing
          the outer hexagons.

    `string' PEN_MIDDLE
          Default:  `"pencircle scaled .3mm"'.  The pen used for
          drawing the middle hexagons.

    `string' pen_inner
          Default:  `"pencircle scaled .3mm"'.  The pen used for
          drawing the inner hexagons.

    `Picture&' PICTURE
          Default:  `current_picture'.  The `Picture' onto which the
          pattern is put.

    `unsigned int' MAX_HEXAGONS
          Default:  1000.  The maximum number of hexagons that will be
          drawn.


     Draws a pattern in the x-z plane consisting of hexagons.  The outer
     hexagons form a tessellation.  The middle and inner hexagons fit
     within the outer hexagons.  The hexagons are drawn in double rows.
     The tessellation can be repeated by copying a double row and
     shifting the copy to lie directly behind the first double row.  If
     the `Picture' with the pattern is projected with the `Focus' in
     front of the pattern, looking in the direction of the back of the
     pattern, the first row of hexagons will appear larger than the rows
     behind it.  Therefore, in order for the perspective projection of
     the pattern to fill a rectangular area on the plane of projection,
     it will generally be necessary to increase the number of sets of
     hexagons in each double row.  On the other hand, if the same
     number of sets of hexagons were used in the front double row, as
     will be needed for the back double row, many of them would
     probably be unprojectable.

     The return value of this function is the number of hexagons drawn.

          default_focus.set(0, 10, -10, 0, 10, 25, 10);
          hex_pattern_1(1, 0, 0, 5, 5);

     [Figure 178 not displayed.]

          default_focus.set(-5, 5, -10, 0, 10, 25, 10);
          hex_pattern_1(2, 1.5, 1, 2, 5, 2, black, gray, black,
                        light_gray, black);

     [Figure 179 not displayed.]



File: 3DLDF.info,  Node: Roulettes and Involutes,  Prev: Plane Tesselations,  Up: Pattern Reference

Roulettes and Involutes
=======================

     "A "roulette" is the curve generated by a point which is carried by
     a curve which rolls on a fixed curve. [...]  The locus of a point
     carried by a circle rolling on a straight line is a "trochoid".  If
     the point is inside the circle the trochoid has inflexions;  if it
     is outside the circle, but rigidly attached to it, the trochoid
     has loops.  [...]  In the particular case when the point is on the
     circumference of the rolling circle the roulette is a "cycloid".
     When the circle rolls on the outside of another circle the
     corresponding curves are the "epitrochoids" and "epicycloids";  if
     it rolls on the inside, they are the "hypotrochoids" and
     "hypocycloids"."
       H. Martyn Cundy and A. P. Rollett, _Mathematical Models_, p. 46.

* Menu:

* Epicycloids::


File: 3DLDF.info,  Node: Epicycloids,  Prev: Roulettes and Involutes,  Up: Roulettes and Involutes

Epicycloids
-----------

 - Function: unsigned int epicycloid_pattern_1 (real DIAMETER_INNER,
          real DIAMETER_OUTER_START, real DIAMETER_OUTER_END, real
          STEP, int ARC_DIVISIONS, unsigned int OFFSETS, [vector<const
          Color*> COLORS = `Colors::default_color_vector'])
     Draws a pattern consisting of epicycloids.  The  outer circle rolls
     around the circumference of the inner circle and a `Point' on the
     outer circle traces an epicycloid.

     If OFFSETS is greater than 1, the outer circle is rotated OFFSET
     times around the center of the inner circle by 360 / offsets
     (starting from the outer circle's original position).  From each
     of these new positions, an epicycloid is drawn.

     While DIAMETER_OUTER_START is greater than or equal to
     DIAMETER_OUTER_END, the diameter of the outer circle is reduced by
     STEP, and another set of epicycloids is traced, as described
     above.  Each time the diameter of the outer circle is reduced, a
     new `Color' is taken from COLORS for the drawing commands.  If
     there are more iterations than `Colors', the last `Color' on
     COLORS is used for the remaining iterations.

     The arguments:
    `real' DIAMETER_INNER
          The diameter of the inner circle.

    `real' DIAMETER_OUTER_START
          The diameter of the outer circle for the first iteration.  It
          must be greater than or equal to DIAMETER_OUTER_END.

    `real' DIAMETER_OUTER_END
          The diameter of the outer circle for the last iteration.  It
          must be less than or equal to DIAMETER_OUTER_START.

    `real' STEP
          The amount by which the diameter of the outer circle is
          _reduced_ upon each iteration.

    `int' ARC_DIVISIONS
          The number of divisions of the circle used for calculating
          `Points' on the epicycloid.  For instance, if ARC_DIVISIONS
          is 90, then the `Path' for each epicycloid will only have 4
          `Points', since 360 / 90 = 4.

    `unsigned int' OFFSETS
          The number of epicycloids drawn upon each iteration.  Each
          one is rotated by 360 / OFFSETS around the center of the
          inner circle.  OFFSETS must be greater than or equal to 1.

    `vector<const Color*>' COLORS
          Default: `Colors::default_color_vector'.  The `Colors' pointed
          to by the pointers on this vector are used for drawing the
          epicycloids.  One `Color' is used for each iteration.


     Example:
          epicycloid_pattern_1(5, 3, 3, 1, 72);
          current_picture.output(Projections::PARALLEL_X_Z);

     [Figure 180 not displayed.]

     Example:
          default_focus.set(2, 5, -10, 2, 5, 10, 10);
          epicycloid_pattern_1(5, 3, 3, 1, 36);
          current_picture.output();

     [Figure 181 not displayed.]



File: 3DLDF.info,  Node: Solid Reference,  Next: Faced Solid Reference,  Prev: Pattern Reference,  Up: Top

Solid Reference
***************

   Class `Solid' is defined in `solids.web'.  It's derived from `Shape'
using public derivation.  It is intended to be used as a base class for
more specialized classes representing solid figures, e.g., cuboids,
polyhedra, solids of rotation, etc.

* Menu:

* Solid Data Members::
* Solid Constructors and Setting Functions::
* Solid Destructor::
* Solid Operators::
* Copying Solids::
* Setting Solid Members::
* Querying Solids::
* Returning Elements and Information Solids::
* Showing Solids::
* Affine Transformations for Solids::
* Applying Transformations to Solids::
* Outputting Solids::
* Drawing and Filling Solids::
* Clearing Solids::


File: 3DLDF.info,  Node: Solid Data Members,  Next: Solid Constructors and Setting Functions,  Prev: Solid Reference,  Up: Solid Reference

Data Members
============

 - Protected variable: bool on_free_store
     `true', if the `Solid' was dynamically allocated on the free
     store, otherwise `false'.  `Solids' should only be allocated on
     the free store by `create_new<Solid>()', or analogous functions
     for derived classes.  *Note Solid Reference; Constructors and
     Setting Functions: Solid Constructors and Setting Functions.

 - Protected variable: Point center
     The center of the `Solid'.  An object of a type derived from
     `Solid' need not have a meaningful `center'.  However, many do, so
     it's convenient to be able to access it using the member functions
     of `Solid'.

 - Protected variable: bool do_output
     Set to `false' in `Picture::output()', if the `Solid' cannot be
     projected using the arguments of that particular invocation of
     `output()'.  Reset to `true' at the end of `Picture::output()', so
     that the `Solid' will be tested for projectability again, if
     `output()' is called on the `Picture' again.

 - Protected variables: vector<Path*> paths
 - : vector<Circle*> circles
 - : vector<Ellipse*> ellipses
 - : vector <Reg_Polygon*> reg_polygons
 - : vector<Rectangle*> rectangles
     Vectors of pointers to the `Paths', `Circles', `Ellipses',
     `Reg_Polygons', and `Rectangles', respectively, belonging to the
     `Solid', if any exist.

 - Protected variable: valarray<real> projective_extremes
     The maximum and minimum values for the x, y, and z-coordinates of
     the `Points' belonging to the `Solid'.  Used in
     `Picture::output()' for testing whether a `Solid' is projectable
     using a particular set of arguments.

 - Public static `const' variables: unsigned short CIRCLE
 - : unsigned short ELLIPSE
 - : unsigned short PATH
 - : unsigned short RECTANGLE
 - : unsigned short REG_POLYGON
     Used as arguments in the functions `get_shape_ptr()' and
     `get_shape_center()' (*note Returning Elements and Information:
     Returning Elements and Information Solids.).


File: 3DLDF.info,  Node: Solid Constructors and Setting Functions,  Next: Solid Destructor,  Prev: Solid Data Members,  Up: Solid Reference

Constructors and Setting Functions
==================================

 - Default constructor: `void' Solid (`void')
     Creates an empty `Solid'.

 - Copy constructor: `void' Solid (const Solid& S)
     Creates a new `Solid' and makes it a copy of S.

 - Template specializations: Solid* create_new<Solid> (const Solid* S)
 - : Solid* create_new<Solid> (const Solid& S)
     Pseudo-constructors for dynamic allocation of `Solids'.  They
     create a `Solid' on the free store and allocate memory for it using
     `new(Solid)'.  They return a pointer to the new `Solid'.

     If S is a non-zero pointer or a reference, the new `Solid' will be
     a copy of S.  If the new object is not meant to be a copy of an
     existing one, `0' must be passed to `create_new<Solid>()' as its
     argument.  *Note Dynamic Allocation of Shapes::, for more
     information.


File: 3DLDF.info,  Node: Solid Destructor,  Next: Solid Operators,  Prev: Solid Constructors and Setting Functions,  Up: Solid Reference

Destructor
==========

 - `virtual' Destructor: void ~Solid (`void')
     This function currently has an empty definition, but its existence
     prevents GCC 3.3 from issuing the following warning: "`class
     Solid' has virtual functions but non-virtual destructor".


File: 3DLDF.info,  Node: Solid Operators,  Next: Copying Solids,  Prev: Solid Destructor,  Up: Solid Reference

Operators
=========

 - Virtual function: const Solid& operator= (const Solid& S)
     Assignment operator.  Makes `*this' a copy of S, discarding the
     old contents of `*this'.

 - Virtual function: Transform operator*= (const Transform& T)
     Multiplication by a `Transform'.  All of the `Shapes' that make up
     the `Solid' are transformed by T.


File: 3DLDF.info,  Node: Copying Solids,  Next: Setting Solid Members,  Prev: Solid Operators,  Up: Solid Reference

Copying
=======

 - `const' virtual function: Shape* get_copy (`void')
     Dynamically allocates a new `Solid' on the free store, using
     `create_new<Solid>()', and makes it a copy of `*this'.  Then, a
     pointer to `Shape' is pointed at the copy and returned.  Used for
     putting `Solids' onto `Picture::shapes' in the drawing and filling
     functions for `Solid'.  *Note Solid Reference; Drawing and
     Filling: Drawing and Filling Solids.


File: 3DLDF.info,  Node: Setting Solid Members,  Next: Querying Solids,  Prev: Copying Solids,  Up: Solid Reference

Setting Members
===============

 - Virtual function: bool set_on_free_store ([bool B = `true'])
     Sets `on_free_store' to B.  This function is called in the
     template function `create_new()'.  *Note Solid Reference;
     Constructors and Setting Functions: Solid Constructors and Setting
     Functions.


File: 3DLDF.info,  Node: Querying Solids,  Next: Returning Elements and Information Solids,  Prev: Setting Solid Members,  Up: Solid Reference

Querying
========

 - `const' virtual function: bool is_on_free_store (`void')
     Returns the value of `on_free_store'; `true', if the `Solid' was
     dynamically allocated on the free store, otherwise `false'.
     `Solids', and objects of classes derived from `Solid', should only
     ever be allocated on the free store by a specialization of the
     template function `create_new()'.  *Note Solid Reference;
     Constructors and Setting Functions: Solid Constructors and Setting
     Functions.


File: 3DLDF.info,  Node: Returning Elements and Information Solids,  Next: Showing Solids,  Prev: Querying Solids,  Up: Solid Reference

Returning Elements and Information
==================================

 - `const' virtual function: const Point& get_center (void)
     Returns `center'.  If the `Solid' doesn't have a meaningful
     center, the return value will probably be `INVALID_POINT'.

* Menu:

* Getting Shape Centers Solids::
* Getting Shapes Solids::


File: 3DLDF.info,  Node: Getting Shape Centers Solids,  Next: Getting Shapes Solids,  Prev: Returning Elements and Information Solids,  Up: Returning Elements and Information Solids

Getting Shape Centers
---------------------

 - `const' virtual function: const Point& get_shape_center (const
          unsigned short SHAPE_TYPE, const unsigned short S)
     Returns the `center' of a `Shape' belonging to the `Solid'.
     Currently, the object can be a `Circle', `Ellipse', `Rectangle',
     or `Reg_Polygon', and it is accessed through a pointer on one of
     the following vectors of pointers to `Shape': `circles',
     `ellipses', `rectangles', or `reg_polygons'.  The type of object
     is specified using the SHAPE_TYPE argument.  The following `public
     static const' data members of `Solid' can (and probably should) be
     passed as the SHAPE_TYPE argument: `CIRCLE', `ELLIPSE',
     `RECTANGLE', and `REG_POLYGON'.

     The argument S is used to index the vector.

     This function is called within the more specialized functions in
     this section, namely: `get_circle_center()',
     `get_ellipse_center()', ``get_rectangle_center()'', and
     `get_reg_polygon_center()'.  I don't expect it to be needed in user
     code very often.

          Dodecahedron d(origin, 3);
          d.filldraw();
          Point C = d.get_shape_center(Solid::REG_POLYGON, 1);
          C.dotlabel("C");

     [Figure 182 not displayed.]

     Note that this function will have to be changed, if new vectors of
     `Shape' pointers are added to `class Solid'!

 - `const' virtual functions: const Point& get_circle_center (const
          unsigned short S)
 - : const Point& get_ellipse_center (const unsigned short S)
 - : const Point& get_rectangle_center (const unsigned short S)
 - : const Point& get_reg_polygon_center (const unsigned short S)
     These functions all return the center of the `Shape' pointed to by
     a pointer on one of the vectors of `Shapes' belonging to the
     `Solid'.  The argument S indicates which element on the vector is
     to be accessed.  For example, `get_rectangle_center(2)' returns
     the center of the `Rectangle' pointed to by `rectangles[2]'.

          Cuboid c(origin, 3, 4, 5, 0, 30);
          c.draw();
          for (int i = 0; i < 6; ++i)
            c.get_rectangle_center(i).label(i, "");

     [Figure 183 not displayed.]



File: 3DLDF.info,  Node: Getting Shapes Solids,  Prev: Getting Shape Centers Solids,  Up: Returning Elements and Information Solids

Getting Shapes
--------------

   The functions in this section all return `const' pointers to
`Shape', or one of its derived classes. Therefore, they must be invoked
in such a way, that the `const' qualifier is not discarded.  See the
description of `get_reg_polygon_ptr()' below, for an example.

 - `const' virtual function: Shape* get_shape_ptr (const unsigned short
          shape_type, const unsigned short s)
     Copies one of the objects belonging to the `Solid', and returns a
     pointer to `Shape' that points to the copy.  The object is found
     by dereferencing one of the pointers on one of the vectors of
     pointers belonging to the `Solid'.  Currently, these vectors are
     `circles', `ellipses', `paths', `rectangles', and `reg_polygons'.
     The argument SHAPE_TYPE specifies the vector, and the argument S
     specifies which element of the vector should be accessed.  The
     following `public static const' data members of `Solid' can (and
     probably should) be passed as the SHAPE_TYPE argument: `CIRCLE',
     `ELLIPSE', `PATH', `RECTANGLE', and `REG_POLYGON'.

     This function was originally intended to be called within the more
     specialized functions in this section, namely: `get_circle_ptr()',
     `get_ellipse_ptr()', `get_path_ptr()', `get_rectangle_ptr', and
     `get_reg_polygon_ptr'.  However, these functions no longer use
     `get_shape_ptr()', so this function is probably no longer needed.

          Icosahedron I(origin, 3);
          I.filldraw();
          Reg_Polygon* t =
          static_cast<Reg_Polygon*>(I.get_shape_ptr(Solid::REG_POLYGON, 9));
          t->fill(gray);

     [Figure 184 not displayed.]


 - `const' virtual functions: const Reg_Polygon* get_circle_ptr (const
          unsigned short S)
 - : const Reg_Polygon* get_ellipse_ptr (const unsigned short S)
 - : const Reg_Polygon* get_path_ptr (const unsigned short S)
 - : const Reg_Polygon* get_rectangle_ptr (const unsigned short S)
 - : const Reg_Polygon* get_reg_polygon_ptr (const unsigned short S)
     Each of these functions returns a pointer from one of the vectors
     of `Shape' pointers belonging to the `Solid'.  The argument S
     specifies which element of the appropriate vector should be
     returned.  For example, `get_reg_polygon_ptr(2)' returns the
     `Reg_Polygon*' in `reg_polygons[2]'.

     Since these functions return `const' pointers, they must be invoked
     in such a way, that the `const' qualifier is not discarded, as
     noted at the beginning of this section.  The following example
     demonstrates two ways of invoking `get_reg_polygon_ptr()':

          Dodecahedron d(origin, 3);
          d.draw();
          const Reg_Polygon* ptr = d.get_reg_polygon_ptr(0);
          ptr->draw(black, "evenly scaled 4", "pencircle scaled 1mm");
          Reg_Polygon A = *d.get_reg_polygon_ptr(5);
          A.fill(gray);

     [Figure 185 not displayed.]



File: 3DLDF.info,  Node: Showing Solids,  Next: Affine Transformations for Solids,  Prev: Returning Elements and Information Solids,  Up: Solid Reference

Showing
=======

 - `const' virtual function: `void' show ([string TEXT = "", [char
          COORDS = 'w', [const bool DO_PERSP = `true', [const bool
          DO_APPLY = `true', [Focus* f = 0, [const unsigned short PROJ
          = `Projections::PERSP', [const real FACTOR = 1]]]]]]])
     Prints TEXT and the value of `on_free_store' to the standard
     output (`stdout'), and then calls `show()' on the objects pointed
     to by the pointers on `paths', `circles', `ellipses',
     `reg_polygons', and `rectangles', unless the vectors are empty.
     The arguments are passed to `Path::show()', `Ellipse::show()',
     etc.  If a vector is empty, a message to this effect is printed to
     the standard output.


File: 3DLDF.info,  Node: Affine Transformations for Solids,  Next: Applying Transformations to Solids,  Prev: Showing Solids,  Up: Solid Reference

Affine Transformations
======================

 - Virtual functions: Transform scale (real X, [real Y = 0, [real Z =
          0]])
     `Solid'.

 - : Transform shear (real XY, [real XZ = 0, [real YX = 0, [real YZ =
          0, [real ZX = 0, [real ZY = 0]]]]])
 - : Transform shift (real X, [real Y = 0, [real Z = 0]])
 - : Transform shift (const Point& PT)
 - : Transform rotate (const real X, [const real Y = 0, [const real Z =
          0]])
 - : Transform rotate (const Point& P0, const Point& P1, [const real
          ANGLE = 180])
     These functions perform the corresponding transformations on all
     of the `Shapes' belonging to the `Solid'.  *Note Transform
     Reference; Affine Transformations: Affine Transformations for
     Transforms.


File: 3DLDF.info,  Node: Applying Transformations to Solids,  Next: Outputting Solids,  Prev: Affine Transformations for Solids,  Up: Solid Reference

Applying Transformations
========================

 - Virtual function: void apply_transform (`void')
     Calls `apply_transform()' on all of the `Shapes' belonging to the
     `Solid'.


File: 3DLDF.info,  Node: Outputting Solids,  Next: Drawing and Filling Solids,  Prev: Applying Transformations to Solids,  Up: Solid Reference

Outputting
==========

   The functions in this section are are called, directly or
indirectly, by `Picture::output()'.  *Note Picture Reference;
Outputting: Outputting Pictures.

 - Virtual function: void output (`void')
     Writes the MetaPost code for drawing, filling, filldrawing,
     undrawing, unfilling, or unfilldrawing the `Solid' to `out_stream'.

 - Virtual function: void suppress_output (`void')
     Used in `Picture::output()'.  Sets `do_output' to `false', if the
     `Solid' cannot be projected using a particular set of arguments to
     `Picture::output()'.

 - Virtual function: void unsuppress_output (`void')
     Used in `Picture::output()'.  Resets `do_output' to `true', so
     that the `Solid' will be tested for projectability again, if the
     `Picture' it's on is output again.

 - Virtual function: vector<Shape*> extract (const Focus& F, const
          unsigned short PROJ, real FACTOR)
     Tests whether all of the `Shapes' belonging to the `Solid' are
     projectable, using the arguments passed to `output()'.  If it is,
     this function returns a vector of pointers to `Shape' containing a
     single pointer to the `Solid'.  If not, an empty vector is
     returned.

 - Virtual function: bool set_extremes (`void')
     Sets `projective_extremes' to contain the maximum and minimum
     values for the x, y, and z-coordinates of the `Points' on the
     `Shape'.  Used for determining projectability of a `Solid' using a
     particular set of arguments.

 - `const' inline virtual function: const valarray<real> get_extremes
          (`void')
     Returns `projective_extremes'.

 - `const' virtual functions: real get_minimum_z (`void')
 - : real get_maximum_z (`void')
 - : real get_mean_z (`void')
     Returns the minimum, maximum, or mean z-value, respectively, of the
     `Points' belonging to the `Solid'.  Used for surface hiding.
     *Note Surface Hiding::.


File: 3DLDF.info,  Node: Drawing and Filling Solids,  Next: Clearing Solids,  Prev: Outputting Solids,  Up: Solid Reference

Drawing and Filling
===================

 - `const' virtual function: void draw ([const vector<const Color*> V =
          `Colors::default_color_vector', [const string DDASHED = "",
          [const string PPEN = "", [Picture& PICTURE =
          `current_picture']]]])
     Draws the `Solid'.

     This function allocates a new `Solid', makes it a copy of `*this',
     and puts a pointer to the copy onto `PICTURE.shapes'.  The data
     members of the `Shapes' belonging to the copy are set
     appropriately, so that they can be drawn, when `Picture::output()'
     is called.

     The `Colors' used for drawing the various `Paths', `Circles',
     `Ellipses', etc., belonging to the `Solid' are passed in V.  If
     the `Solid' contains more `Shapes' than V contains pointers to
     `Color', the `Color' pointed to by the last pointer on V is used
     to draw the remaining `Shapes'.

     Currently, a `Solid' can only be drawn with a single dash pattern
     (DDASHED), and pen (PPEN).

 - `const' virtual function: void fill ([const vector<const Color*> V =
          `Colors::default_color_vector', [Picture& PICTURE =
          `current_picture']])
     Fills the `Solid'.

     This function allocates a new `Solid' makes it a copy of `*this',
     and puts a pointer to it onto PICTURE.`shapes'.  The data members
     of the `Shapes' belonging to the copy are set appropriately, so
     that they can be filled, when `Picture::output()' is called.

     The `Colors' used for filling the various `Paths', `Circles',
     `Ellipses', etc., belonging to the `Solid' are passed in V.  If
     the `Solid' contains more `Shapes' than V contains pointers to
     `Color', the `Color' pointed to by the last pointer on V is used
     to fill the remaining `Shapes'.

 - `const' virtual function: void filldraw ([const vector<const Color*>
          DRAW_COLORS = Colors::default_color_vector, [const
          vector<const Color*> FILL_COLORS =
          Colors::background_color_vector, [const string DDASHED = "",
          [const string PPEN = "", [Picture& PICTURE =
          `current_picture']]]]])
     Filldraws the `Solid'.

     This function allocates a new `Solid', makes it a copy of `*this',
     and puts a pointer to it onto `PICTURE.shapes'.  The data members
     of the `Shapes' belonging to the copy are set appropriately, so
     that they can be filldrawn, when `Picture::output()' is called.

     The `Colors' used for drawing and filling the various `Paths',
     `Circles', `Ellipses', etc., belonging to the `Solid' are passed
     in DRAW_COLORS and FILL_COLORS.  If the `Solid' contains more
     `Shapes' than DRAW_COLORS contains pointers to `Color', the
     `Color' pointed to by the last pointer on DRAW_COLORS is used to
     draw the remaining `Shapes'.  The same applies to `fill_colors'.

     Currently, a `Solid' can only be filldrawn with a single dash
     pattern (DDASHED), and pen (PPEN).

 - `const' virtual function: void undraw ([const string DDASHED = "",
          [const string PPEN = "", [Picture& PICTURE =
          `current_picture']]])
     Undraws the `Solid'.

     This function allocates a new `Solid', makes it a copy of `*this',
     and puts a pointer to it onto PICTURE.`shapes'.  The data members
     of the `Shapes' belonging to the copy are set appropriately, so
     that they can be undrawn, when `Picture::output()' is called.

     A `Solid' can currently only be undrawn using a single dash
     pattern (DDASHED), and pen (PPEN).

 - `const' virtual function: void unfill ([Picture& PICTURE =
          `current_picture'])
     Unfills the `Solid'.

     This function allocates a new `Solid' makes it a copy of `*this',
     and puts a pointer to it onto PICTURE.`shapes'.  The data members
     of the `Shapes' belonging to the copy are set appropriately, so
     that they can be unfilled, when `Picture::output()' is called.


 - `const' virtual function: void unfilldraw ([const string DDASHED =
          "", [const string PPEN = "", [Picture& PICTURE =
          `current_picture']]])
 - `const' virtual function: void undraw ([const string DDASHED = "",
          [const string PPEN = "", [Picture& PICTURE =
          `current_picture']]])
     Unfilldraws the `Solid'.

     This function allocates a new `Solid', makes it a copy of `*this',
     and puts a pointer to it onto PICTURE.`shapes'.  The data members
     of the `Shapes' belonging to the copy are set appropriately, so
     that they can be unfilldrawn, when `Picture::output()' is called.

     A `Solid' can currently only be unfilldrawn using a single dash
     pattern (DDASHED), and pen (PPEN).


File: 3DLDF.info,  Node: Clearing Solids,  Prev: Drawing and Filling Solids,  Up: Solid Reference

Clearing
========

 - Virtual function: void clear (`void')
     Calls `clear()' on all the `Shapes' belonging to the `Solid'.
     Used in `Picture::clear()' for deallocating and destroying
     `Solids'.

     Currently, <SHAPE>.`clear()' always resolves to `Path::clear()',
     since none of the other types of `Shape' that a `Solid' can
     contain, e.g., `Ellipse', `Circle', etc., overloads
     `Path::clear()'.


File: 3DLDF.info,  Node: Faced Solid Reference,  Next: Cuboid Reference,  Prev: Solid Reference,  Up: Top

Faced Solid Reference
*********************

   Class `Solid_Faced' is defined in `solfaced.web'.  It is derived
from `Solid' using public derivation.

   `Solid_Faced' currently has no member functions.  It is intended for
use as a base class.  The classes `Cuboid' and `Polyhedron' are derived
from `Solid_Faced'.  *Note Cuboid Reference::, and *Note Polyhedron
Reference::.

* Menu:

* Solid_Faced Data Members::


File: 3DLDF.info,  Node: Solid_Faced Data Members,  Prev: Faced Solid Reference,  Up: Faced Solid Reference

Data Members
============

 - Protected variable: unsigned short faces
     The number of faces of the `Solid_Faced'.

 - Protected variable: unsigned short vertices
     The number of vertices of the `Solid_Faced'.

 - Protected variable: unsigned short edges
     The number of edges of the `Solid_Faced'.


File: 3DLDF.info,  Node: Cuboid Reference,  Next: Polyhedron Reference,  Prev: Faced Solid Reference,  Up: Top

Cuboid Reference
****************

   Class `Cuboid' is defined in `cuboid.web'.  It is derived from
`Solid_Faced' using public derivation.

* Menu:

* Cuboid Data Members::
* Cuboid Constructors and Setting Functions::
* Cuboid Operators::


File: 3DLDF.info,  Node: Cuboid Data Members,  Next: Cuboid Constructors and Setting Functions,  Prev: Cuboid Reference,  Up: Cuboid Reference

Data Members
============

 - Protected variables: real height
 - : real width
 - : real depth
     The height, width, and depth of the `Cuboid', respectively.

     Please note, that "`height'", "`width'", and "`depth'" are
     conventional terms.  There are no restrictions on the orientation
     of a `Cuboid'.


File: 3DLDF.info,  Node: Cuboid Constructors and Setting Functions,  Next: Cuboid Operators,  Prev: Cuboid Data Members,  Up: Cuboid Reference

Constructors and Setting Functions
==================================

 - Default constructor: void Cuboid (`void')
     Creates an empty `Cuboid'.

 - Copy constructor: void Cuboid (const Cuboid& C)
     Creates a new `Cuboid' and makes it a copy of C.

 - Constructor: void Cuboid (const Point& C, const real H, const real
          W, const real D, [const real X = 0, [const real Y = 0, [const
          real Z = 0]]])
     Creates a `Cuboid' with `center' at the origin, with `height' ==
     H, `width' == W, and `depth' == D.  If X, Y, or Z is non-zero, the
     `Cuboid' is rotated by the amounts indicated around the
     corresponding main axes.  Finally, the `Cuboid' is shifted such
     that `center' comes to lie at C.

          Point P(-3, -2, 12);
          Cuboid c(P, 3, 5, 2.93, 35, 10, 60);

     [Figure 186 not displayed.]


 - Template specializations: Cuboid* create_new<Cuboid> (const Cuboid*
          C)
 - : Cuboid* create_new<Cuboid> (const Cuboid& C)
     Pseudo-constructors for dynamic allocation of `Cuboids'.  They
     create a `Cuboid' on the free store and allocate memory for it
     using `new(Cuboid)'.  They return a pointer to the new `Cuboid'.

     If C is a non-zero pointer or a reference, the new `Cuboid' will
     be a copy of C.  If the new object is not meant to be a copy of an
     existing one, `0' must be passed to `create_new<Cuboid>()' as its
     argument.  *Note Dynamic Allocation of Shapes::, for more
     information.

 - Destructor: void ~Cuboid (`void')
     Deallocates the `Rectangles' pointed to by the pointers on
     `rectangles' (a `Solid' data member), and calls
     `rectangles.clear()'.  `Cuboids' consist entirely of `Rectangles',
     so nothing must be done to the other vectors.


File: 3DLDF.info,  Node: Cuboid Operators,  Prev: Cuboid Constructors and Setting Functions,  Up: Cuboid Reference

Operators
=========

 - Assignment operator: void operator= (const Cuboid& C)
     Makes the `Cuboid' a copy of C.  The old contents of `*this' are
     deallocated (where necessary) and discarded.


File: 3DLDF.info,  Node: Polyhedron Reference,  Next: Utility Functions,  Prev: Cuboid Reference,  Up: Top

Polyhedron Reference
********************

   Class `Polyhedron' is defined in `polyhed.web'.  It is derived from
`Solid_Faced' using public derivation.  It is intended for use as a
base class for specific types of polyhedra.  Currently, the classes
`Tetrahedron', `Dodecahedron', `Icosahedron', and `Trunc_Octahedron'
(truncated octahedron) are derived from `Polyhedron'.

   There is a great deal of work left to do on the polyhedra.

* Menu:

* Polyhedron Data Members::
* Regular Platonic Polyhedra::
* Semi-Regular Archimedean Polyhedra::


File: 3DLDF.info,  Node: Polyhedron Data Members,  Next: Regular Platonic Polyhedra,  Prev: Polyhedron Reference,  Up: Polyhedron Reference

Data Members
============

 - Protected variable: unsigned short number_of_polygon_types
     The number of different types of polygon making up the faces of a
     `Polyhedron'.  The Platonic polyhedra have only one type of face,
     while the Archimedean can have more.

 - Protected variable: real face_radius
     The radius of the sphere that touches the centers of the polygonal
     faces of the polyhedron (_Inkugel_, in German).

 - Protected variable: real edge_radius
     The radius of the sphere that touches the centers of the edges of
     the polyhedron.

 - Protected variable: real vertex_radius
     The radius of the sphere touching the vertices of the polyhedron
     (_Umkugel_, in German).


File: 3DLDF.info,  Node: Regular Platonic Polyhedra,  Next: Semi-Regular Archimedean Polyhedra,  Prev: Polyhedron Data Members,  Up: Polyhedron Reference

Regular Platonic Polyhedra
==========================

   3DLDF currently has classes for three of the five regular Platonic
polyhedra: `Tetrahedron', `Dodecahedron', and `Icosahedron'.  There is
no need for a special `Cube' class, because cubes can be created using
`Cuboid' with equal width, height, and depth arguments (*note Cuboid
Reference::).  `Octahedron' is missing at the moment, but I plan to add
it soon.

* Menu:

* Tetrahedron::
* Dodecahedron::
* Icosahedron::


File: 3DLDF.info,  Node: Tetrahedron,  Next: Dodecahedron,  Prev: Regular Platonic Polyhedra,  Up: Regular Platonic Polyhedra

Tetrahedron
-----------

   Class `Tetrahedron' is defined in `polyhed.web'.  It is derived from
`Polyhedron' using public derivation.

* Menu:

* Tetrahedron Data Members::
* Tetrahedron Constructors and Setting Functions::
* Tetrahedron Net::


File: 3DLDF.info,  Node: Tetrahedron Data Members,  Next: Tetrahedron Constructors and Setting Functions,  Prev: Tetrahedron,  Up: Tetrahedron

Data Members
............

 - Protected static `const' variable: real dihedral_angle
     The angle in radians between the faces of the `Tetrahedron', namely
     70 degrees  32' .  Only the Platonic polyhedra have a single
     dihedral angle, so `dihedral_angle' is not a member of
     `Polyhedron'.  This means that it must be a member of all of the
     classes representing Platonic polyhedra.

 - Protected variable: real triangle_radius
     The radius of the circle enclosing a triangular face of the
     `Tetrahedron'.


File: 3DLDF.info,  Node: Tetrahedron Constructors and Setting Functions,  Next: Tetrahedron Net,  Prev: Tetrahedron Data Members,  Up: Tetrahedron

Constructors and Setting Functions
..................................

 - Default constructor: void Tetrahedron (`void')
     Creates an empty `Tetrahedron'.

 - Constructor: void Tetrahedron (const Point& P, const real
          DIAMETER_OF_TRIANGLE, [real ANGLE_X = 0, [real ANGLE_Y = 0,
          [real ANGLE_Z = 0]]])
     Creates a `Tetrahedron' with its center at the origin.  The faces
     have enclosing circles of diameter DIAMETER_OF_TRIANGLE.  If any
     of ANGLE_X, ANGLE_Y, or ANGLE_Z is non-zero, the `Tetrahedron' is
     rotated by the amounts specified around the corresponding axes.
     Finally, if P is not the origin, the `Tetrahedron' is shifted such
     that `center' comes to lie at P.

     The center of a `Tetrahedron' is the intersection of the line
     segments connecting the vertices with the centers of the opposite
     faces.

          Tetrahedron t(origin, 3);
          t.draw();

     [Figure 187 not displayed.]

          Point P(1, 0, 1);
          Tetrahedron t(P, 2.75, 30, 32.5, 20);
          t.draw();

     [Figure 188 not displayed.]


 - Setting function: void set (const Point& P, const real
          DIAMETER_OF_TRIANGLE, [real ANGLE_X = 0, [real ANGLE_Y = 0,
          [real ANGLE_Z = 0]]])
     Corresponds to the constructor above.


File: 3DLDF.info,  Node: Tetrahedron Net,  Prev: Tetrahedron Constructors and Setting Functions,  Up: Tetrahedron

Net
...

 - Static function: vector<Reg_Polygon*> get_net (const real
          TRIANGLE_DIAMETER)
     Returns the "net" of the `Tetrahedron', i.e., the two-dimensional
     pattern of triangles that can be folded into a model of a
     tetrahedron.(1) The net lies in the x-z plane.  The triangles have
     enclosing circles of diameter TRIANGLE_DIAMETER.  The center of
     the middle triangle is at the origin.

          vector<Reg_Polygon*> vrp = Tetrahedron::get_net(2);
          for (vector<Reg_Polygon*>::iterator iter = vrp.begin();
               iter != vrp.end();
               ++iter)
            {
              (**iter).draw();
            }

     [Figure 189 not displayed.]

     This function is used in the non-default constructor.  *Note
     Polyhedron Reference; Regular Platonic Polyhedra; Tetrahedron;
     Constructors and Setting Functions: Tetrahedron Constructors and
     Setting Functions.  The constructor starts with the net and
     rotates three of the triangles about the adjacent vertices of the
     middle triangle.  Currently, all of the `Polyhedron' constructors
     work this way.  However, this is not ideal, because rotation uses
     the sine and cosine functions, which cause inaccuracies to creep
     in.  I think there must be a better way of constructing
     `Polyhedra', but I haven't found one yet.

     The `Polyhedron' constructors are also especially sensitive to
     changes made to `Transform::align_with_axis()'.  I have already
     had to rewrite them twice, and since
     `Transform::align_with_axis()' may need to be changed or rewritten
     again, it's possible that the `Polyhedron' constructors will have
     to be, too.  It has also occurred in the past, that the `Polyhedra'
     were constructed correctly on one platform, using a particular
     compiler, but not on another platform, using a different compiler.

 - Static function: void draw_net (const real TRIANGLE_DIAMETER, [bool
          MAKE_TABS = `true'])
     Draws the net for a `Tetrahedron' in the x-y plane.  The triangles
     have enclosing circles of diameter TRIANGLE_DIAMETER.  The origin
     is used as the center of the middle triangle.  The centers of the
     triangles are numbered.  If the argument MAKE_TABS is used, tabs
     for gluing and/or sewing a cardboard model of the `Tetrahedron'
     together will be drawn, too.  The dots on the tabs mark where to
     stick the needle through, when sewing the model together (I've had
     good results with sewing).

          Tetrahedron::draw_net(3, true);

     [Figure 190 not displayed.]

     The net is drawn in the x-y plane, because it currently doesn't
     work to draw it in the x-z plane.  I haven't gotten around to
     fixing this problem yet.

   ---------- Footnotes ----------

   (1) Albrecht Du"rer invented this method of constructing polyhedra.


File: 3DLDF.info,  Node: Dodecahedron,  Next: Icosahedron,  Prev: Tetrahedron,  Up: Regular Platonic Polyhedra

Dodecahedron
------------

   Class `Dodecahedron' is defined in `polyhed.web'.  It is derived
from `Polyhedron' using public derivation.

   Dodecahedra have 12 regular pentagonal faces.

* Menu:

* Dodecahedron Data Members::
* Dodecahedron Constructors and Setting Functions::
* Dodecahedron Net::


File: 3DLDF.info,  Node: Dodecahedron Data Members,  Next: Dodecahedron Constructors and Setting Functions,  Prev: Dodecahedron,  Up: Dodecahedron

Data Members
............

 - Protected static `const' variable: real dihedral_angle
     The angle between the faces of the `Dodecahedron', namely 116
     degrees  34'  = \pi - \arctan(2).

 - Protected variable: real pentagon_radius
     The radius of the circle enclosing a pentagonal face of the
     `Dodecahedron'.


File: 3DLDF.info,  Node: Dodecahedron Constructors and Setting Functions,  Next: Dodecahedron Net,  Prev: Dodecahedron Data Members,  Up: Dodecahedron

Constructors and Setting Functions
..................................

 - Default constructor: void Dodecahedron (`void')
     Creates an empty `Dodecahedron'.

 - Constructor: void Dodecahedron (const Point& P, const real
          PENTAGON_DIAMETER, [real ANGLE_X = 0, [real ANGLE_Y = 0,
          [real ANGLE_Z = 0]]])
     Creates a `Dodecahedron' with its center at the origin, where the
     pentagonal faces have enclosing circles of diameter
     PENTAGON_DIAMETER.  If any of ANGLE_X, ANGLE_Y, or ANGLE_Z is
     non-zero, the `Dodecahedron' is rotated by the amounts specified
     around the corresponding axes.  Finally, if P is not the origin,
     the `Dodecahedron' is shifted such that `center' comes to lie at P.

          Point P(-1, -2, 4);
          Dodecahedron d(P, 3, 12.5, 16, 2);
          d.draw();

     [Figure 191 not displayed.]

          d.filldraw();

     [Figure 192 not displayed.]



File: 3DLDF.info,  Node: Dodecahedron Net,  Prev: Dodecahedron Constructors and Setting Functions,  Up: Dodecahedron

Net
...

 - Static function: vector<Reg_Polygon*> get_net (const real
          PENTAGON_DIAMETER, [bool DO_HALF = false])
     Returns the "net", i.e., the two-dimensional pattern of pentagons
     that can be folded into a model of a dodecahedron.  The net lies
     in the x-z plane.  The pentagons have enclosing circles of diameter
     PENTAGON_DIAMETER.  The center of the center pentagon of the first
     half of the net is at the origin.  If the argument DO_HALF is
     `true', only the first half of the net is created.  This is used
     in the non-default constructor.  *Note Polyhedron Reference;
     Regular Platonic Polyhedra; Dodecahedron; Constructors and Setting
     Functions: Dodecahedron Constructors and Setting Functions.

          vector<Reg_Polygon*> vrp = Dodecahedron::get_net(1);
          for(vector<Reg_Polygon*>::iterator iter = vrp.begin();
              iter != vrp.end(); ++iter)
                 (**iter).draw();

     [Figure 193 not displayed.]


 - Static function: void draw_net (const real PENTAGON_DIAMETER, [bool
          PORTRAIT = `true', [bool MAKE_TABS = `true']])
     Draws the net for a `Dodecahedron' in the x-z plane.  The pentagons
     have enclosing circles of diameter PENTAGON_DIAMETER.  The origin
     is used as the center of the middle pentagon of the first half of
     the net.  The centers of the pentagons are numbered.

     If the argument PORTRAIT is `true' (the default), the net is
     arranged for printing in portrait format.  If it's `false', it's
     arranged for printing in landscape format.

     The argument MAKE_TABS currently has no effect.  When I get around
     to programming this, it will be used for specifying whether tabs
     for gluing and/or sewing a cardboard model should be drawn, too.

          Dodecahedron::draw_net(1, false);

     [Figure 194 not displayed.]



File: 3DLDF.info,  Node: Icosahedron,  Prev: Dodecahedron,  Up: Regular Platonic Polyhedra

Icosahedron
-----------

   Class `Icosahedron' is defined in `polyhed.web'.  It is derived from
`Polyhedron' using public derivation.

   Icosahedra have 20 regular triangular faces.

* Menu:

* Icosahedron Data Members::
* Icosahedron Constructors and Setting Functions::
* Icosahedron Net::


File: 3DLDF.info,  Node: Icosahedron Data Members,  Next: Icosahedron Constructors and Setting Functions,  Prev: Icosahedron,  Up: Icosahedron

Data Members
............

 - Protected static `const' variable: real dihedral_angle
     The angle between the faces of the `Icosahedron', namely 138
     degrees  11'  = \pi - \arcsin(2/3).

 - Protected variable: real triangle_radius
     The radius of the circle enclosing a triangular face of the
     `Icosahedron'.


File: 3DLDF.info,  Node: Icosahedron Constructors and Setting Functions,  Next: Icosahedron Net,  Prev: Icosahedron Data Members,  Up: Icosahedron

Constructors and Setting Functions
..................................

 - Default constructor: void Icosahedron (`void')
     Creates an empty `Icosahedron'.

 - Constructor: void Icosahedron (const Point& P, const real
          DIAMETER_OF_TRIANGLE, [real ANGLE_X = 0, [real ANGLE_Y = 0,
          [real ANGLE_Z = 0]]])
     Creates an `Icosahedron' with its center at the origin, where the
     triangular faces have enclosing circles of diameter
     DIAMETER_OF_TRIANGLE.  If any of ANGLE_X, ANGLE_Y, or ANGLE_Z is
     non-zero, the `Icosahedron' is rotated by the amounts specified
     around the corresponding axes.  Finally, if P is not the origin,
     the `Icosahedron' is shifted such that `center' comes to lie at P.

          Icosahedron i(origin, 3, 0, 10);
          i.draw();

     [Figure 195 not displayed.]

          i.filldraw();

     [Figure 196 not displayed.]


