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: Label Data Members,  Next: Copying Labels,  Prev: Label Reference,  Up: Label Reference

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

 - Private variable: Point* pt
     A pointer to the `Point' representing the location of the `Label'.

 - Private variable: bool dot
     `true' if the label should be dotted, otherwise `false'.

     `dot' will be `false', if the label was generated by a call to
     `label()' with the "`dot'" argument `false' (the default), `true',
     if the label was generated by a call to `dotlabel()', or to
     `label()' with the "`dot'" argument `true'.

 - Private variable: string text
     The text of the label.  TEXT is always put between "`btex'" and
     "`etex'" in the MetaPost code, so that TeX will be used to format
     the labels. In particular, this means that TeX's math mode can be
     used.  However, double backslashes must be used instead of single
     backslashes, in order that single backslashes be written to
     `out_stream'.

          Point P(1, 1, 2);
          origin.drawarrow(P);
          P.label("$\\vec{P}$");

     [Figure 76 not displayed.]


 - Private variable: string position
     The position of the text with respect to `*pt'.  Valid values are
     as in MetaPost: "top", "bot" (bottom), "lft" (left), "rt" (right),
     "ulft" (upper left), "llft" (lower left), "urt" (upper right),
     "lrt" (lower right).

 - Public static variable: bool DO_LABELS
     Enables or disables creation of `Labels'.  If `true', `label' and
     `dotlabel()' cause `Labels' to be created and put onto a
     `Picture'.  If `false', they are not.  Note that it is also
     possible to suppress output of existing `Labels' when outputting a
     `Picture'.


File: 3DLDF.info,  Node: Copying Labels,  Next: Outputting Labels,  Prev: Label Data Members,  Up: Label Reference

Copying
=======

 - `const' Function: Label* get_copy (void)
     Creates a copy of the `Label' and returns a pointer to the copy.
     Called in `Picture::operator=()' and `Picture::operator+=()' where
     `Pictures' are copied.  Users should never need to call this
     function directly.  *Note Picture Reference; Operators: Picture
     Operators.

     This function dynamically allocates a new `Label' and a new
     `Point' within the `Label', and copies the `strings' from `*this'
     to the new `Label'.  The standard library functions for `strings'
     take care of the allocation for the `string' members of `Label'.


File: 3DLDF.info,  Node: Outputting Labels,  Prev: Copying Labels,  Up: Label Reference

Outputting
==========

 - Function: void output (const Focus& F, const unsigned short PROJ,
          real FACTOR, const Transform& T)
     Writes MetaPost code for the labels to `out_stream'.  It is called
     in `Picture::output()' (*note Picture Reference; Outputting:
     Outputting Pictures.).  Users should never need to call this
     function directly.

     When `Picture::output()' is invoked, the MetaPost code for
     `Labels' is written to `out_stream' after the code for the drawing
     and filling commands.  This prevents the `Labels' from being
     covered up.  However, they can still be covered by other `Labels',
     or by `Shapes' or `Labels' from subsequent invocations of
     `Picture::output()' within the same figure (*note I/O Functions::,
     for descriptions of `beginfig() and `endfig()'').


File: 3DLDF.info,  Node: Picture Reference,  Next: Point Reference,  Prev: Label Reference,  Up: Top

Picture Reference
*****************

   Class `Picture' is defined in `pictures.web'.

* Menu:

* Picture Data Members::
* Picture Global Variables::
* Picture Constructors::
* Picture Operators::
* Affine Transformations for Pictures::
* Modifying Pictures::
* Showing Pictures::
* Outputting Pictures::


File: 3DLDF.info,  Node: Picture Data Members,  Next: Picture Global Variables,  Prev: Picture Reference,  Up: Picture Reference

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

 - Private variable: Transform transform
     Applied to the `Shapes' on the `Picture' when the latter is
     output.  It is initialized as the identity `Transform', and can be
     modified by the transformation functions, by
     `Picture::operator*=(const Transform&)' (*note Picture Reference;
     Operators: Picture Operators.), and by `Picture::set_transform()'
     (*note Picture Reference; Modifying: Modifying Pictures.).

 - Private variable: vector<Shape*> shapes
     Contains pointers to the `Shapes' on the `Picture'.  When a
     drawing or filling function is invoked for a `Shape', a copy is
     dynamically allocated and a pointer to the copy is placed onto
     `shapes'.

 - Private variable: vector<Label*> labels
     Contains pointers to the `Labels' on the `Picture'.  When a
     `Point' is labelled, either directly or through a call to
     `label()' or `dotlabel()' for another type of `Shape'(1), a
     `Label' is dynamically allocated, the `Point' is copied to
     `*Label::pt', and a pointer to the `Label' is placed onto `labels'.

 - Private variable: bool do_labels
     Used for enabling or disabling output of `Labels' when outputting a
     `Picture'.  The default value is `true'.  It is set to `false' by
     using `suppress_labels()' and can be reset to `true' by using
     `unsuppress_labels()'.  *Note Picture Reference; Output Functions:
     Picture Output Functions.

     Often, when a `Picture' is copied, transformed, and output again in
     a single figure, it's undesirable to have the `Labels' output again
     in their new positions.  To avoid this, use `suppress_labels()'
     after outputting the `Picture' the first time.

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

   (1) `label()' and `dotlabel()' are currently only defined for
`Point' and `Path' (and the latter's derived classes), i.e., not for
`Solid' and its derived classes.


File: 3DLDF.info,  Node: Picture Global Variables,  Next: Picture Constructors,  Prev: Picture Data Members,  Up: Picture Reference

Global Variables
================

 - Variable: Variable Picture current_picture
     The `Picture' used as the default by the drawing and filling
     functions.


File: 3DLDF.info,  Node: Picture Constructors,  Next: Picture Operators,  Prev: Picture Global Variables,  Up: Picture Reference

Constructors
============

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

 - Copy constructor: void Picture (const Picture& P)
     Creates a copy of `Picture' P.

          Circle c(origin, 3);
          c.draw();
          current_picture.output(Projections::PARALLEL_X_Z);
          Picture new_picture(current_picture);
          new_picture.shift(2);
          new_picture.output(Projections::PARALLEL_X_Z);

     [Figure 77 not displayed.]



File: 3DLDF.info,  Node: Picture Operators,  Next: Affine Transformations for Pictures,  Prev: Picture Constructors,  Up: Picture Reference

Operators
=========

 - Assignment operator: void operator= (const Picture& P)
     Makes `*this' a copy of P, destroying the old contents of `*this'.

 - Operator: void operator+= (const Picture& P)
     Adds the contents of P to `*this'.  P remains unchanged.

 - Operator: void operator+= (Shape* S)
     Puts S onto `shapes'.  Note that the pointer S itself is put onto
     `shapes', so any allocation and copying must be performed first.
     This is a low-level function that users normally won't need to use
     directly.

 - Operator: void operator+= (Label* LABEL)
     Puts LABEL onto `labels'.  Note that the pointer LABEL itself is
     put onto `labels', so any allocation and copying must be performed
     first.  This is a low-level function that users normally won't
     need to invoke directly.

 - Operator: Transform operator*= (const Transform& T)
     Multiplies `transform' by T.  This has the effect of transforming
     all of the `Shapes' on `shapes' and all of the `Points' of the
     `Labels' on `labels' by T upon output.

          Transform t;
          t.rotate(0, 0, 180);
          t.shift(3);
          Reg_Polygon pl(origin, 5, 3, 90);
          pl.draw();
          pl.label();
          current_picture.output(Projections::PARALLEL_X_Y);
          current_picture *= t;
          current_picture.output(Projections::PARALLEL_X_Y);

     [Figure 78 not displayed.]



File: 3DLDF.info,  Node: Affine Transformations for Pictures,  Next: Modifying Pictures,  Prev: Picture Operators,  Up: Picture Reference

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

   The functions in this section all operate on the `transform' data
member of the `Picture' and return a `Transform' representing the
transformation--_not_ `transform'.

 - Function: Transform scale (real X, [real Y = 1, [real Z = 1]])
     Performs `transform.scale(X, Y, Z)' and returns the result.  This
     has the effect of scaling all of the elements of `shapes' and
     `labels'.

 - Function: Transform shift (real x, [real Y = 0, [real Z = 0]])
     Performs `transform.shift(X, Y, Z)' and returns the result.  This
     has the effect of shifting all of the `Shapes' and `Labels' on the
     `Picture'.

 - Function: Transform shift (const Point& P)
     Performs `transform.shift(P)' and returns the result.  This has
     the effect of shifting all of the `Shapes' and `Labels' on the
     `Picture' by the x, y, and z-coordinates of P.

 - Function: Transform rotate (const real X, [const real Y = 0, [const
          real Z = 0]])
     Performs `transform.rotate(X, Y, Z)' and returns the result.  This
     has the effect of rotating all of the elements of `shapes' and
     `labels'.

 - Function: Transform rotate (const Point& P0, const Point& P1, [const
          real ANGLE = 180]);
     Performs `transform.rotate(P0, P1, ANGLE)' and returns the result.
     This has the effect of rotating all of the elements of `shapes'
     and `labels' about the line from p_0 to p_1.


File: 3DLDF.info,  Node: Modifying Pictures,  Next: Showing Pictures,  Prev: Affine Transformations for Pictures,  Up: Picture Reference

Modifying
=========

 - Function: void clear (void)
     Destroys the `Shapes' and `Labels' on the `Picture' and removes
     all the `Shape' pointers from `shapes' and the `Label' pointers
     from `labels'.  All dynamically allocated objects are deallocated,
     namely the `Shapes', the `Labels', and the `Points' belonging to
     the `Labels'. `transform' is reset to the identity `Transform'.

 - Function: void reset_transform (void)
     Resets `transform' to the identity `Transform'.

 - Function: Transform set_transform (const Transform& T)
     Sets `transform' to `t' and returns `t'.

 - Function: void kill_labels (void)
     Removes the `Labels' from the `Picture'.


File: 3DLDF.info,  Node: Showing Pictures,  Next: Outputting Pictures,  Prev: Modifying Pictures,  Up: Picture Reference

Showing
=======

 - Function: void show ([string TEXT = "", [bool STOP = `false']])
     Prints information about the `Picture' to standard output.

     `show()' first prints the string `"Showing Picture:"' to standard
     output, followed by TEXT, if the latter is not the empty string
     (`""')(1).  Then it calls `transform.show()', prints the size of
     `shapes' and `labels', and the value of `do_labels'.  Then it calls
     `show()' on each of the `Shapes' on `shapes'.  Since `show()' is a
     `virtual' function in `class Shape', the appropriate `show()' is
     called for each `Shape', i.e., `Point::show()' for a `Point',
     `Path::show()' for a `Path', etc.  If STOP is `true', execution
     stops and the user is requested to type <RETURN> to continue.
     Finally, the string `"Done showing picture."' is printed to
     standard output.

 - Function: void show_transform ([string TEXT = "Transform from
          Picture:"])
     Calls `transform.show()', passing TEXT as the argument to the
     latter function.

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

   (1) Actually, it's printed to standard output even if it is the
empty string, you just don't see it.


File: 3DLDF.info,  Node: Outputting Pictures,  Prev: Showing Pictures,  Up: Picture Reference

Outputting
==========

* Menu:

* Picture Output Namespaces::
* Picture Output Functions::


File: 3DLDF.info,  Node: Picture Output Namespaces,  Next: Picture Output Functions,  Prev: Outputting Pictures,  Up: Outputting Pictures

Namespaces
----------

* Menu:

* Namespace Projections::
* Namespace Sorting::


File: 3DLDF.info,  Node: Namespace Projections,  Next: Namespace Sorting,  Prev: Picture Output Namespaces,  Up: Picture Output Namespaces

Namespace Projections
.....................

   The namespace `Projections' is defined in `pictures.web'.

 - Constant: const unsigned short PERSP
 - Constant: const unsigned short PARALLEL_X_Y
 - Constant: const unsigned short PARALLEL_X_Z
 - Constant: const unsigned short PARALLEL_Z_Y
 - Constant: const unsigned short AXON
 - Constant: const unsigned short ISO
     These constants can be used for the PROJECTION argument in
     `Picture::output()', described in *Note Picture Reference;
     Outputting; Functions: Picture Output Functions, below.


File: 3DLDF.info,  Node: Namespace Sorting,  Prev: Namespace Projections,  Up: Picture Output Namespaces

Namespace Sorting
.................

   The namespace `Sorting' is defined in `pictures.web'.

 - Constant: const unsigned short NO_SORT
 - Constant: const unsigned short MAX_Z
 - Constant: const unsigned short MIN_Z
 - Constant: const unsigned short MEAN_Z
     These constants can be used for the SORT_VALUE argument in
     `Picture::output()', described in *Note Picture Reference;
     Outputting; Functions: Picture Output Functions, below.


File: 3DLDF.info,  Node: Picture Output Functions,  Prev: Picture Output Namespaces,  Up: Outputting Pictures

Output Functions
----------------

 - Function: void output (const Focus& F, [const unsigned short
          PROJECTION = `Projections::PERSP', [real FACTOR = 1, [const
          unsigned short SORT_VALUE = `Sorting::MAX_Z', [const bool
          DO_WARNINGS = `true', [const real MIN_X_PROJ = -40, [const
          real MAX_X_PROJ = 40, [const real MIN_Y_PROJ = -40, [const
          real MAX_Y_PROJ = 40, [const real MIN_Z_PROJ = -40, [const
          real MAX_Z_PROJ = 40]]]]]]]]]])
 - Function: void output ([const unsigned short PROJECTION =
          `Projections::PERSP', [real FACTOR = 1, [const unsigned short
          SORT_VALUE = `Sorting::MAX_Z', [const bool DO_WARNINGS =
          `true', [const real MIN_X_PROJ = -40, [const real MAX_X_PROJ
          = 40, [const real MIN_Y_PROJ = -40, [const real MAX_Y_PROJ =
          40, [const real MIN_Z_PROJ = -40, [const real MAX_Z_PROJ =
          40]]]]]]]]]])
     These functions create a two-dimensional projection of the objects
     on the `Picture' and write MetaPost code to `out_stream' for
     drawing it.

     The arguments:

    `const Focus&' F
          The `Focus' used for projection, also known as the center of
          projection, or the camera.  This argument is used in the
          first version only.  The second version, without a `const
          Focus&' F argument, merely calls the first version and passes
          it the global variable `default_focus' as its first argument,
          so `default_focus' is effectively the default for F.
          Defining two versions in this way makes it possible to call
          `output()' with `projection' as its first (and possibly only)
          argument.  If instead, F were an optional argument with
          `default_focus' as its default, this wouldn't have been
          possible.  It also wouldn't be possible to have F have a
          default in the first version, and to retain the second
          version, because the compiler wouldn't be able to resolve a
          call to `output()' with no arguments.

    `const unsigned short' PROJECTION
          Default: `Projections::PERSP'.  The type of projection.
          Valid values are `const unsigned shorts' defined in
          `namespace Projections' (*note Namespace Projections::):
          `PERSP' for the perspective projection,
          `PARALLEL_X_Y' for parallel projection onto the x-y plane,
          `PARALLEL_X_Z' for parallel projection onto the x-z plane, and
          `PARALLEL_Z_Y' for parallel projection onto the z-y plane.
          %% !! TO DO: I plan to add isometric and axionometric
          projections soon.

    `real' FACTOR
          Default: 1.  Passed from `output()' to `extract()' and from
          there to `project()'.  The `world_coordinates' of the
          `Points' that are projected are multiplied by FACTOR, which
          enlarges or shrinks the projected image without altering the
          `Picture' itself.  FACTOR is probably most useful for
          parallel projections, where the `Focus' F isn't used;  with a
          perspective projection, the parameters of the `Focus' can be
          used to influence the size of the projected image.

    `const unsigned short' SORT_VALUE
          Default: `Sorting::MAX_Z'.  The value used should be one of
          the constants defined in `namespace Sorting', *Note Namespace
          Sorting::, above.  If `MAX_Z' (the default) is used, the
          `Shapes' on the `Picture' are sorted according to the maximum
          z-value of the `projective_extremes' of the `Points'
          belonging to the `Shape'.  If `MIN_Z' is used, they are
          sorted according to the minimum z-value, and if `MEAN_Z' is
          used, they are sorted according to the  mean of the maximum
          and minimum z-values.  If `NO_SORT' is used, the `Shapes' are
          output in the order in which they were put onto the `Picture'.

          The surface hiding algorithm implemented in 3DLDF is quite
          primitive, and doesn't always work right.  For `Shapes' that
          intersect, it _can't_ work right.  I plan to work on
          improving the surface hiding algorithm soon.  This is not a
          trivial problem.  To solve it properly, each `Shape' on a
          `Picture' must be tested for intersection with every other
          `Shape' on the `Picture'.  If two or more `Shapes' intersect,
          they must be broken up into smaller objects until there are
          no more intersections.  I don't expect to have a proper
          solution soon, but I expect that I will be able to make some
          improvements.  *Note Surface Hiding::.

    `const bool' DO_WARNINGS
          Default: `true'.  If `true', `output()' issues warnings to
          `stderr' (standard error output) if a `Shape' cannot be
          output because it lies outside the limits set by the
          following arguments.  Sometimes, a user may only want to
          project a portion of a `Picture', in which case such warnings
          would not be helpful.  In this case, DO_WARNINGS should be
          `false'.

    `const real' MIN_X_PROJ
          Default: -40.  The minimum x-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[0]' of any `Point' on a `Shape' is
          less than MIN_X_PROJ, the `Shape' will not be projected at
          all.

    `const real' MAX_X_PROJ
          Default: 40.  The maximum x-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[0]' of any `Point' on a `Shape' is
          greater than MAX_X_PROJ, the `Shape' will not be projected at
          all.

    `const real' MIN_Y_PROJ
          Default: -40.  The minimum y-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[1]' of any `Point' on a `Shape' is
          less than MIN_Y_PROJ, the `Shape' will not be projected at
          all.

    `const real' MAX_Y_PROJ
          Default: 40.  The maximum y-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[1]' of any `Point' on a `Shape' is
          greater than MAX_Y_PROJ, the `Shape' will not be projected at
          all.

    `const real' MIN_Z_PROJ
          Default: -40.  The minimum z-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[2]' of any `Point' on a `Shape' is
          less than MIN_Z_PROJ, the `Shape' will not be projected at
          all.

    `const real' MAX_Z_PROJ
          Default: 40.  The maximum z-coordinate of the projection of a
          `Shape' such that the `Shape' can be output.  If
          `projective_coordinates[2]' of any `Point' on a `Shape' is
          greater than MAX_Z_PROJ, the `Shape' will not be projected at
          all.

 - Function: void suppress_labels (void)
     Suppresses output of the `Labels' on a `Picture' when `output()'
     is called.  This can be useful when a `Picture' is output,
     transformed, and output again, one or more times, in a single
     figure.  Usually, it will not be desirable to have the `Labels'
     output more than once.

     In [next figure] , `current_picture' is output three times, but the
     `Labels' on it are only output once.

          Ellipse e(origin, 3, 5);
          e.label();
          e.draw();
          Point pt0(-3);
          Point pt1(3);
          pt0.draw(pt1);
          Point pt2(0, 0, -4);
          Point pt3(0, 0, 4);
          pt2.draw(pt3);
          pt0.dotlabel("0", "lft");
          pt1.dotlabel("1", "rt");
          pt2.dotlabel("2", "bot");
          pt3.dotlabel("3");
          current_picture.output(Projections::PARALLEL_X_Z);
          current_picture.rotate(0, 60);
          current_picture.suppress_labels();
          current_picture.output(Projections::PARALLEL_X_Z);
          current_picture.rotate(0, 60);
          current_picture.output(Projections::PARALLEL_X_Z);

     [Figure 79 not displayed.]


 - Inline function: void unsuppress_labels (void)
     Sets `do_labels' to `true'.  If a `Picture' contains `Labels',
     `unsuppress_labels()' ensures that they will be output, when
     `Picture::output()' is called, so long as there is no intervening
     call to `suppress_labels()' or `kill_labels()'.


File: 3DLDF.info,  Node: Point Reference,  Next: Focus Reference,  Prev: Picture Reference,  Up: Top

Point Reference
***************

   Class `Point' is defined in `points.web'.  It is derived from
`Shape' using `protected' derivation.  The function `Transform
Transform::align_with_axis(Point, Point, char)' is a `friend' of
`Point'.

* Menu:

* Point Data Members::
* Point Typedefs and Utility Structures::
* Point Global Constants and Variables::
* Point Constructors and Setting Functions::
* Point Destructor::
* Point Operators::
* Copying Points::
* Querying Points::
* Returning Coordinates::
* Returning Information for Points::
* Modifying Points::
* Affine Transformations for Points::
* Applying Transformations to Points::
* Projecting Points::
* Vector Operations::
* Points and Lines::
* Point Intersections::
* Point Drawing Functions::
* Labelling Points::
* Showing Points::
* Outputting Points::


File: 3DLDF.info,  Node: Point Data Members,  Next: Point Typedefs and Utility Structures,  Prev: Point Reference,  Up: Point Reference

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

 - Private variable: valarray<real> world_coordinates
     The set of four homogeneous coordinates x, y, z, and w that
     represent the position of the `Point' within 3DLDF's global
     coordinate system.

 - Private variable: valarray<real> projective_coordinates
     The set of four homogeneous coordinates x, y, z, and w that
     represent the position of the _projection_ of the `Point' onto a
     two-dimensional plane for output.  The x and y values are used in
     the MetaPost code written to `out_stream'.  The z value is used in
     the hidden surface algorithm (which is currently rather primitive
     and doesn't work very well.  *note Surface Hiding::).  The w value
     can be != 1 , depending on the projection used;  the perspective
     projection is non-affine, so w can take on other values.

 - Private variable: valarray<real> user_coordinates
     A set of four homogeneous coordinates x, y, z, and w.

     `user_coordinates' currently has no function.  It is intended for
     use in user-defined coordinate systems.  For example, a coordinate
     system could be defined with respect to a plane surface that isn't
     parallel to one of the major planes.  Such a coordinate system
     would be convenient for drawing on the plane.  A `Transform' would
     make it possible to convert between `user_coordinates' and
     `world_coordinates'.

 - Private variable: valarray<real> view_coordinates
     A set of four homogeneous coordinates x, y, z, and w.

     `view_coordinates' currently has no function.  It may be useful for
     displaying multiple views in an interactive graphical user
     interface, or for some other purpose.

 - Private variable: Transform transform
     Contains the product of the transformations applied to the `Point'.
     When `apply_transform()' is called for the `Point', directly or
     indirectly, the `world_coordinates' are updated and `transform' is
     reset to the identity `Transform'.  *Note Point Reference;
     Applying Transformations: Applying Transformations to Points.

 - Private variable: bool on_free_store
     Returns `on_free_store'.  This should only be `true' if the
     `Point' was dynamically allocated on the free store.  `Points'
     should only ever be dynamically allocated by
     `create_new<Point>()', which uses `set_on_free_store()' to set
     `on_free_store' to `true'.  *Note Point Reference; Constructors
     and Setting Functions: Point Constructors and Setting Functions,
     and *Note Point Reference; Modifying: Modifying Points.

 - Private variable: signed short drawdot_value
     Used to tell `Point::output()' what MetaPost drawing command
     (`drawdot()' or `undrawdot()') to write to `out_stream' when
     outputting a `Point'.

     When `drawdot()' or `undrawdot()' is called on a `Point', the
     `Point' is copied and put onto the `Picture', which was passed to
     `drawdot()' or `undrawdot()' as an argument (`current_picture' by
     default).  `drawdot_value' is either set to `Shape::DRAWDOT' or
     `Shape::UNDRAWDOT' on the copy; `this->drawdot' is not set.

 - Private variable: const Color* drawdot_color
     Used to tell `Point::output()' what string to write to `out_stream'
     for the color when outputting a `Point'.

 - Private variable: string pen
     Used to tell `Point::output()' what string to write to `out_stream'
     for the pen when outputting a `Point'.

 - Protected variable: valarray<real> projective_extremes
     A set of 6 `real' values indicating the maximum and minumum x, y,
     and z-coordinates of the `Point'.  Used for determining whether a
     `Point' is projectable with the parameters of a particular
     invocation of `Picture::output()'.  *Note Picture Reference;
     Outputting: Outputting Pictures.

     Obviously, the maxima and minima will always be the same for a
     `Point', namely the x, y, and z-coordinates.  However,
     `set_extremes()' and `get_extremes()', the functions that access
     `projective_extremes', are pure virtual functions in `class Shape',
     so the `Point' versions must be consistent with the versions for
     other types derived from `Shape'.

 - Protected variable: bool do_output
     `true' by default.  Set to `false' by `suppress_output()', which
     is called on a `Shape' by `Picture::output()', if the `Shape' is
     not projectable.  *Note Picture Reference; Outputting: Outputting
     Pictures.

 - Public static variable: string measurement_units
     The unit of measurement for all distances within a `Picture',
     `"cm"' (for centimeters) by default.  The x and y-coordinates of
     the  projected `Points' are always followed by `measurement_units'
     when they're written to `out_stream'.  Unlike Metafont, units of
     measurement cannot be indicated for individual coordinates.  Nor
     can `measurement_unit' be changed within a `Picture'.

     When I write an input routine, I plan to make it behave the way
     Metafont does, however, 3DLDF will probably also convert all of
     the input values to a standard unit, as Metafont does.

 - Public static variable: real CURR_Y
 - Public static variable: real CURR_Z
     Default values for the y and z-coordinate of `Points', when the
     x-coordinate, or the x and y-coordinates only are specified.  Both
     are 0 by default.

     These values only used in the constructor and setting function
     taking one required `real' value (for the x-coordinate), and two
     optional `real' values (for the y and z-coordinates).  They are
     not used when a `Point' is declared using the default constructor
     with no arguments.  In this case, the x, y, and z-coordinates will
     all be 0.  *Note Point Reference; Constructors and Setting
     Functions: Point Constructors and Setting Functions.

          Point A(1);
          A.show("A:");
          -| A: (1, 0, 0);
          CURR_Y = 5;
          A.set(2);
          A.show("A:");
          -| A: (2, 5, 0);
          CURR_Z = 12;
          Point B(3);
          B.show("B:");
          -| B: (3, 5, 12);
          Point C;
          C.show("C:");
          -| C: (0, 0, 0);


File: 3DLDF.info,  Node: Point Typedefs and Utility Structures,  Next: Point Global Constants and Variables,  Prev: Point Data Members,  Up: Point Reference

Typedefs and Utility Structures
===============================

 - typedef: point_pair first second
     Synonymous with `pair<Point, Point>'.

 - struct: bool_point b pt
     `b' is a `bool' and `pt' is a `Point'.  `bool_point' also contains
     two constructors and an assignment operator, described below.

 - Default constructor: void bool_point (void)
     Creates a `bool_point' and sets `b' to `false' and `pt' to
     `INVALID_POINT'.

 - Default constructor: void bool_point (bool BB, const Point& PPT)
     Creates a `bool_point' and sets `b' to BB and `pt' to PPT.

 - Assignment operator: void bool_point::operator= (const bool_point&
          BP)
     Sets `b' to BP.`b' and `pt' to BP.`pt'.

 - typedef: bool_point_pair first second
     Synonymous with `pair <bool_point, bool_point>'.

 - struct: bool_point_quadruple first second third fourth
     This structure contains four `bool_points'.  It also has two
     constructors and an assignment operator, described below.

 - Default constructor: void bool_point_quadruple (void)
     Creates a `bool_point_quadruple', and sets `first', `second',
     `third', and `fourth' all to `INVALID_BOOL_POINT'.

 - Constructor: void bool_point_quadruple (bool_point A, bool_point B,
          bool_point C, bool_point D)
     Creates a `bool_point_quadruple' and sets `first' to A, `second'
     to B, `third' to C, and `fourth' to D.

 - Assignment operator: void bool_point_quadruple::operator= (const
          bool_point_quadruple& ARG)
     Makes `*this' a copy of ARG.

 - struct: bool_real_point b r pt
     `b' is a `bool', `r' is a `real', and `pt' is a `Point'.
     `bool_real_point' also contains three constructors and an
     assignment operator, described below.

 - Default constructor: void bool_real_point (void)
     Creates a `bool_real_point' and sets `b' to `false', `r' to
     `INVALID_REAL' and  `pt' to `INVALID_POINT'.

 - Copy constructor: void bool_real_point (const bool_real_point& BRP)
     Creates a `bool_real_point' and sets `b' to BRP.`b', `r' to
     BRP.`r', and  `pt' to BRP.`pt'.

 - Constructor: void bool_real_point (const bool& BB, const real& RR,
          const Point& PPT)
     Creates a `bool_real_point' and sets `b' to BB, `r' to RR, and
     `pt' to PPT.

 - Assignment operator: void bool_real_point::operator= (const
          bool_real_point& BRP)
     Makes `*this' a copy of BRP.


File: 3DLDF.info,  Node: Point Global Constants and Variables,  Next: Point Constructors and Setting Functions,  Prev: Point Typedefs and Utility Structures,  Up: Point Reference

Global Constants and Variables
==============================

 - Constant: Point INVALID_POINT
     The x, y, and z-values in `world_coordinates' are all
     `INVALID_REAL'.

 - Constant: Point origin
     The x, y, and z-values in `world_coordinates' are all 0.

 - Constant: bool_point INVALID_BOOL_POINT
     `b' is `false' and `pt' is `INVALID_POINT'.

 - Constant: bool_point_pair INVALID_BOOL_POINT_PAIR
     `first' and `second' are both `INVALID_BOOL_POINT'.

 - Constant: bool_real_point INVALID_BOOL_REAL_POINT
     `b' is `false', `r' is `INVALID_REAL', and `pt' is `INVALID_POINT'.

 - Constant: bool_point_quadruple INVALID_BOOL_POINT_QUADRUPLE
     `first', `second', `third', and `fourth' are all
     `INVALID_BOOL_POINT'.


File: 3DLDF.info,  Node: Point Constructors and Setting Functions,  Next: Point Destructor,  Prev: Point Global Constants and Variables,  Up: Point Reference

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

 - Default constructor: void Point (void)
     Creates a `Point' and initializes its x, y, and z-coordinates to 0.

 - Constructor: void Point (const real X, [const real Y = `CURR_Y',
          [const real Z = `CURR_Z']])
     Creates a `Point' and initializes its x, y, and z-coordinates to
     the values of the arguments X, Y, and Z.  The arguments Y and Z
     are optional.  If they are not specified, the values of `CURR_Y'
     and `CURR_Z' are used.  They are 0 by default, but can be changed
     by the user.  This can be convenient, if all of the `Points' being
     drawn in a particular section of a program have the same z or y
     and z values.

 - Setting function: void set (const real X, [const real Y = `CURR_Y',
          [const real Z = `CURR_Z']])
     Corresponds to the constructor above, but is used for resetting
     the coordinates of an existing `Point'.

 - Copy constructor: void Point (const Point& P)
     Creates a `Point' and copies the values for its x, y, and
     z-coordinates from P.

 - Setting function: void set (const Point& P)
     Corresponds to the copy constructor above, but is used for
     resetting the coordinates of an existing `Point'.  This function
     exists purely as a convenience; the operator `operator=()' (*note
     Point Reference; Operators: Point Operators.)  performs exactly the
     same function.

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

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

     One use for `create_new<Point>' is in the constructors for
     `classes' of objects that can contain a variable number of
     `Points', such as `Path' and `Polygon'.  Another use is in the
     drawing and filling functions, where objects are copied and the
     copies put onto a `Picture'.

     Programmers who dynamically allocate `Points' must ensure that they
     are deallocated properly using `delete'!


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

Destructor
==========

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


File: 3DLDF.info,  Node: Point Operators,  Next: Copying Points,  Prev: Point Destructor,  Up: Point Reference

Operators
=========

 - Assignment operator: void operator= (const Point& P)
     Makes `*this' a copy of P.

 - Operator: Transform operator*= (const Transform& T)
     Multiplies `transform' by T.  By multiplying a `Point'
     successively by one or more `Transforms', the effect of the
     transformations is "saved up" in `transform'.  Only when an
     operation that needs updated values for the `world_coordinates' is
     called on a `Point', or the `Point' is passed as an argument to
     such an operation, is the transformation stored in `transform'
     applied to `world_coordinates' by `apply_transform()', which
     subsequently, resets `transform' to the identity `Transform'.
     *Note Point Reference; Applying Transformations: Applying
     Transformations to Points.

 - `const' operator: Point operator+ (Point P)
     Returns a `Point' with `world_coordinates' that are the sums of
     the corresponding `world_coordinates' of `*this' and P, after
     they've been updated.  `*this' remains unchanged; as in many other
     functions with `Point' arguments, P is passed by value, because
     `apply_transform()' must be called on it, in order to update its
     `world_coordinates'.  If P were a `const Point&', it would have to
     copied within the function anyway, because `apply_transform()' is
     a non-`const' operation.

          Point p0(-2, -6, -28);
          Point p1(3, 14, 92);
          Point p2(p0 + p1);
          p2.show("p2:");
          -| p2: (1, 8, 64)


 - Operator: void operator+= (Point P)
     Adds the updated `world_coordinates' of P to those of `*this'.
     Equivalent in effect to `shift(P)' In fact, this function merely
     calls `p.apply_transform()' and `Point::shift(real, real, real)'
     with P's x, y, and z coordinates (from `world_coordinates') as its
     arguments.  *Note Point Reference; Affine Transformations: Affine
     Transformations for Points.

 - `const' operator: Point operator- (Point P)
     Returns a `Point' with `world_coordinates' representing the
     difference between the updated values of `this->world_coordinates'
     and P`.world_coordinates'.

 - Operator: void operator-= (Point P)
     Subtracts the updated values of P`.world_coordinates' from those
     of `this->world_coordinates'.

 - Operator: real operator*= (const real R)
     Multiplies the updated x, y, and z coordinates
     (`world_coordinates') of the `Point' by R and returns R.  This
     makes it possible to chain invocations of this function.

     If `P' is a `Point' then `P *= R' is equivalent in its effect to
     `P.scale(R, R, R)', except that `P.world_coordinates' is modified
     directly and immediately, without changing `P.transform'.  This is
     possible, because this function calls `apply_transform()' to
     update the `world_coordinates' before multiplying them `r', so
     `transform' is the identity `Transform'.

          Point P(1, 2, 3);
          P *= 7;
          P.show("P:");
          -| P: (7, 14, 21);
          Point Q(1.5, 2.7, 13.82);
          Q *= P *= -1.28;
          P.show("P:");
          -| P: (-8.96, -17.92, -26.88)
          Q.show("Q:");
          -| Q: (-1.92, -3.456, -17.6896)

 - `const' operator: Point operator* (const real R)
     Returns a `Point' with x, y, and z coordinates
     (`world_coordinates') equal to the updated x, y, and z coordinates
     of `*this' multiplied by R.

 - Non-member operator: Point operator* (const real R, const Point& P)
     Equivalent to `Point::operator*(const real R)' (see above), but
     with R placed first.
          Point p0(10, 11, 12);
          real r = 2.5;
          Point p1 = r * p0;
          p1.show();
          -|Point:
          -|(25, 27.5, 30)


 - `const' operator: Point operator- (void)
     Unary minus (prefix).  Returns a `Point' with x, y, and z
     coordinates (`world_coordinates') equal to the the x, y, and
     z-coordinates (`world_coordinates') of `*this' multiplied by -1.

 - Operator: void operator/= (const real R)
     Divides the updated x, y, and z coordinates (`world_coordinates')
     of the `Point' by R.

 - `const' operator: Point operator/ (const real R)
     Returns a `Point' with x, y, and z coordinates
     (`world_coordinates') equal to the updated x, y, and z coordinates
     of `*this' divided by R.

 - Operator: bool operator== (Point P)
 - `const' operator: bool operator== (const Point& P)
     Equality comparison for `Points'.  These functions return `true'
     if the updated values of the `world_coordinates' of the two
     `Points' differ by less than the value returned by
     `Point::epsilon()', otherwise `false'.  *Note Point Reference;
     Returning Information: Returning Information for Points.

 - `const' operator: bool operator!= (const Point& P)
     Inequality comparison for `Points'.  Returns `false' if `*this ==
     P', otherwise `true'.


File: 3DLDF.info,  Node: Copying Points,  Next: Querying Points,  Prev: Point Operators,  Up: Point Reference

Copying
=======

 - `const' function: Shape* get_copy (void)
     Creates a copy of the `Point', and allocates memory for it on the
     free store using `create_new<Point>()'.  It returns a pointer to
     `Shape' that points to the new `Point'.  This function is used in
     the drawing commands for putting `Points' onto `Pictures'.  *Note
     Point Reference; Drawing: Point Drawing Functions.


File: 3DLDF.info,  Node: Querying Points,  Next: Returning Coordinates,  Prev: Copying Points,  Up: Point Reference

Querying
========

 - `inline' function: bool is_identity (void)
     Returns `true' if `transform' is the identity `Transform'.

 - `const' inline function: Transform get_transform (void)
     Returns `transform'.

 - `const' function: bool is_on_free_store (void)
     Returns `true' if memory for the `Point' has been dynamically
     allocated on the free store, i.e., if the `Point' has been created
     using `create_new<Point>()'.  *Note Point Reference; Constructors
     and Setting Functions: Point Constructors and Setting Functions.

 - `const' function: bool is_on_plane (const Plane& P)
     Returns `true', if the `Point' lies on the `Plane' P, otherwise
     `false'.

     Planes are conceived of as having infinite extension, so while the
     `Point' C in [next figure]  does not lie within the `Rectangle' r,
     it does lie on q, so `C.is_on_plane(q)' returns `true'.(1)

          Point P(1, 1, 1);
          Rectangle r(P, 4, 4, 20, 45, 35);
          Plane q = r.get_plane();
          Point A(2, 0, 2);
          Point B(2, 1.64143, 2);
          Point C(0.355028, 2.2185, 6.48628);
          cout << A.is_on_plane(q);
          -| 0
          cout << B.is_on_plane(q);
          -| 1
          cout << "C.is_on_plane(q)";
          -| 1

     [Figure 80 not displayed.]


 - `const' function: bool is_in_triangle (const Point& P0, const Point&
          P1, const Point& P2, [bool VERBOSE = `false', [bool
          TEST_POINTS = `true']])
     Returns `true', if `*this' lies within the triangle determined by
     the three `Point' arguments, otherwise `false'.

     If the code calling `is_in_triangle()' has ensured that p_0, p_1,
     and p_2 determine a plane, i.e., that they are not colinear, and
     that `*this' lies in that plane, then `false' can be passed to
     `is_in_triangle()' as its TEST_POINTS argument.

     If the VERBOSE argument is `true', information resulting from the
     execution of the function are printed to standard output or
     standard error.

     This function is needed for determining whether a line intersects
     with a polygon.

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

   (1) It's unlikely that `Points' will lie on a `Plane', unless the
user constructs the case specially.  In [next figure] , the coordinates
for B and C were found by using `Plane::intersection_point()'.  *Note
Planes; Intersections: Plane Intersections.


File: 3DLDF.info,  Node: Returning Coordinates,  Next: Returning Information for Points,  Prev: Querying Points,  Up: Point Reference

Returning Coordinates
=====================

   The functions in this section return either a single coordinate or a
set of coordinates.  Each has a `const' and a non-`const' version.

   The arguments are the same, with one exception:

`CHAR' C
     Only in `get_coord()'.  Indicates which coordinate should be
     returned.  Valid values are `'x'', `'X'', `'y'', `'Y'', `'z'',
     `'Z'', `'w'', and `'W''.

`CHAR COORDS'
     Indicates the set of coordinates which should be returned or from
     which the coordinate to be returned should be chosen from.  Valid
     values are `'w'' for `world_coordinates' (the default), `'p'' for
     `projective_coordinates', `'u'' for `user_coordinates', and `'v''
     for `view_coordinates'.

`CONST BOOL' DO_PERSP
     Only relevant if `projective_coordinates', or one of its elements
     is to be returned.  If `true', the default, then `project()' is
     called, thereby generating values for `projective_coordinates'.
     If DO_PERSP is `false', then `projective_coordinates', or one of
     its elements, is returned unchanged, which may sometimes be useful.

`CONST BOOL' DO_APPLY
     If `true' (the default), `apply_transform()' is called, thereby
     updating the `world_coordinates'.  Otherwise, it's not, so that
     the values stored in `world_coordinates' remain unchanged.  Note
     that if COORDS is `'p'' and DO_PERSP is `true',
     `apply_transform()' will be called in `project()' whether
     `do_apply' is `true' or `false'.  If for some reason, one wanted
     get `projective_coordinates', or one of its values, based on the
     projection of `world_coordinates' without first updating them, one
     would have to call `reset_transform()' before calling one of these
     functions.  It would probably be a good idea to save `transform'
     before doing so.

`FOCUS*' F
     Indicates what `Focus' is to be used for projection.  Only
     relevant if `coords' is `'p'', i.e., `projective_coordinates', or
     one of its elements, is to be returned.  The default is 0, in
     which case F points to the global variable `default_focus'.

`CONST UNSIGNED SHORT' PROJ
     Indicates what form of projection is to be used.  Only relevant if
     `coords' is `'p'', i.e., `projective_coordinates', or one of its
     elements, is to be returned.  The default is `Projections::PERSP',
     which causes the perspective projection to be applied.

`REAL' FACTOR
     Passed to `project()'.  The values of the x and y coordinates in
     `projective_coordinates' are multiplied by FACTOR.  Only relevant
     if `coords' is `'p'', i.e., `projective_coordinates', or one of
     its elements, is to be returned.  The default is 1.

 - Function: valarray <real> get_all_coords ([char COORDS = 'w', [const
          bool DO_PERSP = true, [const bool DO_APPLY = true, [Focus* F
          = 0, [const unsigned short PROJ = Projections::PERSP, [real
          factor = 1]]]]]])
     Returns one of the sets of coordinates;  `world_coordinates' by
     default.  Returns a complete set of coordinates:  `'w'' for
     `world_coordinates', `'p'' for `projective_coordinates', `'u'' for
     `user_coordinates', or`'v'' for  `view_coordinates'.

 - Function: real get_coord (char C, [char COORDS = 'w', [const bool
          DO_PERSP = true, [const bool DO_APPLY = true, [Focus* F = 0,
          [const unsigned short PROJ = `Projections::PERSP', [real
          FACTOR = 1]]]]]])
     Returns one `coordinate', x, y, z, or w, from the set of
     coordinates indicated (or `world_coordinates', by default).

 - Function: real get_x ([char COORDS = 'w', [const bool DO_PERSP =
          true, [const bool DO_APPLY = true, [Focus* F = 0, [const
          unsigned short PROJ = Projections::PERSP, [real FACTOR =
          1]]]]]])
     Returns the x-coordinate from the set of coordinates indicated (or
     `world_coordinates', by default).

 - Function: real get_y ([char COORDS = 'w', [const bool DO_PERSP =
          true, [const bool DO_APPLY = true, [Focus* F = 0, [const
          unsigned short PROJ = Projections::PERSP, [real FACTOR =
          1]]]]]])
     Returns the y-coordinate from the set of coordinates indicated (or
     `world_coordinates', by default).

 - Function: real get_z ([char COORDS = 'w', [const bool DO_PERSP =
          true, [const bool DO_APPLY = true, [Focus* F = 0, [const
          unsigned short PROJ = Projections::PERSP, [real FACTOR =
          1]]]]]])
     Returns the z-coordinate from the set of coordinates indicated (or
     `world_coordinates', by default).

 - Function: real get_w ([char COORDS = 'w', [const bool DO_PERSP =
          true, [const bool DO_APPLY = true, [Focus* F = 0, [const
          unsigned short PROJ = Projections::PERSP, [real FACTOR =
          1]]]]]])
     Returns the w-coordinate from the set of coordinates indicated (or
     `world_coordinates', by default).

